Como autenticar com o OIDC e o Google

Nesta página, mostramos como usar o OpenID Connect (OIDC) com o GKE On-Prem. Para usar o OIDC, é necessário especificar um provedor OpenID. Este tópico mostra como configurar o GKE On-Prem para usar o Google como o provedor OpenID.

Para uma visão geral do fluxo de autenticação, consulte Autenticação. Para informações gerais sobre como usar provedores OpenID com o GKE On-Prem, consulte Como autenticar com o OpenID Connect.

Limitações

O provedor do Google OpenID não é compatível com grupos. Ao usar o controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes para conceder papéis a usuários autenticados, você precisa conceder papéis a usuários individuais, não a grupos.

Visão geral

O GKE On-Prem é compatível com OpenID Connect (OIDC) como um dos mecanismos de autenticação para interagir com um servidor da API Kubernetes do cluster de um usuário. Com o OIDC, é possível gerenciar o acesso aos clusters do Kubernetes usando os procedimentos padrão na sua organização para criar, ativar e desativar contas de funcionários.

Há duas maneiras de um funcionário usar o fluxo de autenticação do OIDC:

  • Um funcionário pode usar kubectl para iniciar um fluxo do OIDC. Para automatizar esse fluxo, o GKE On-Prem fornece o plug-in do Anthos para Kubectl, um plug-in do kubectl.

  • Um funcionário pode usar o console do Google Cloud para iniciar um fluxo de autenticação do OIDC.

Neste exercício, você configurará as duas opções: kubectl e Console do Google Cloud.

Antes de começar

Antes de ler este tópico, familiarize-se com o OAuth 2.0 e o OpenID Connect. Você também precisa ter familiaridade com os escopos e as declarações do OpenID (links em inglês).

Perfis

Este tópico se refere a três perfis:

  • Administrador da organização: essa pessoa escolhe um provedor OpenID e registra aplicativos cliente com o provedor.

  • Administrador de cluster: essa pessoa cria um ou mais clusters de usuário e cria arquivos de configuração de autenticação para desenvolvedores que usam os clusters.

  • Desenvolvedor: essa pessoa executa cargas de trabalho em um ou mais clusters e usa o OIDC para fazer a autenticação.

Como criar um URL de redirecionamento para o plug-in do Anthos para Kubectl

Esta seção é destinada a administradores da organização.

Como parte da configuração do Google como provedor OpenID, você precisa especificar um URL de redirecionamento que o Google pode usar para retornar tokens de ID ao plug-in do Anthos para Kubectl. O plug-in do Anthos para Kubectl é executado na máquina local de cada desenvolvedor e detecta em uma porta de sua escolha. Escolha um número de porta maior que 1.024 que seja adequado para essa finalidade. Em seguida, o URL de redirecionamento é:

http://localhost:[PORT]/callback

[PORT] é o número da porta.

Ao configurar o provedor do Google OpenID, especifique http://localhost:[PORT]/callback como um dos seus URLs de redirecionamento.

Como configurar um URL de redirecionamento para o Console do Google Cloud

Esta seção é destinada a administradores da organização.

Além de ter um URL de redirecionamento para o plug-in do Anthos para Kubectl, você precisa de um URL de redirecionamento para o Console do Google Cloud. O URL de redirecionamento do console do Google Cloud é:

https://console.cloud.google.com/kubernetes/oidc

Ao configurar o provedor Google OpenID, especifique https://console.cloud.google.com/kubernetes/oidc como um dos seus URLs de redirecionamento.

Nesta seção, você configura a tela de consentimento do OAuth do Google. Quando um desenvolvedor em sua organização inicia a autenticação em um cluster de usuário, ele é direcionado para essa tela de consentimento. Nesse momento, ele prova sua identidade e dá permissão ao Google para criar um token que fornece informações de identificação ao cliente OAuth. No contexto deste tópico, o cliente OAuth é o plug-in do Anthos para Kubectl ou Console do Google Cloud.

  1. Acesse a página Tela de consentimento OAuth no Console do Google Cloud.

    Configure a tela de consentimento OAuth

  2. Selecione Interno e clique em Criar.

  3. Em Tipo de aplicativo, selecione Interno.

  4. Em Nome do aplicativo, insira um nome de sua escolha. Sugestão: GKE on-prem.

  5. Em Domínios autorizados, adicione google.com.

  6. Preencha os campos adicionais conforme achar adequado.

  7. Clique em Save.

Como registrar um aplicativo cliente no Google

Nesta seção, você registrará o GKE On-Prem com o Google para que ele atue como o provedor OpenID dos desenvolvedores da sua organização. Como parte do registro, você precisa fornecer os dois URLs de redirecionamento criados anteriormente.

  1. Acesse a página Credenciais no Console do Google Cloud.

    Acessar a página Credenciais

  2. Clique em Criar credenciais e selecione ID do cliente do OAuth.

  3. Em Tipo de aplicativo, selecione Aplicativo da Web.

  4. Em Nome, digite um nome de sua escolha.

  5. Em URIs de redirecionamento autorizados, adicione os dois URLs de redirecionamento. Lembre-se de que você criou um URL de redirecionamento para o plug-in do Anthos para Kubectl e um URL de redirecionamento para o Console do Google Cloud.

  6. Clique em Criar.

  7. Você recebe um ID do cliente e uma chave secreta do cliente. Salve-os para uso posterior.

Como preencher a especificação oidc no arquivo de configuração do GKE On-Prem

Esta seção é destinada aos administradores de cluster.

Antes de criar um cluster de usuário, gere um arquivo de configuração do GKE On-Prem usando gkectl create-config. A configuração inclui a especificação oidc a seguir. Preencha oidc com valores específicos de seu provedor:

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: defina como "https://accounts.google.com". Aplicativos cliente, como o plug-in do Anthos para Kubectl e o Console do Google Cloud, enviam solicitações de autorização para esse URL. O servidor da API Kubernetes usa esse URL a fim de descobrir chaves públicas para verificação de tokens.
  • kubectlredirecturl: o URL de redirecionamento que você configurou anteriormente para o plug-in do Anthos para Kubectl.
  • clientid: ID do aplicativo cliente que faz solicitações de autenticação ao provedor OpenID. Tanto o plug-in do Anthos para Kubectl quanto o Console do Google Cloud usam esse ID. Você recebeu esse ID quando registrou seu aplicativo cliente no Google.
  • clientsecret: secret para o aplicativo cliente. Tanto o plug-in do Anthos para Kubectl quanto o Console do Google Cloud usam esse secret. Você recebeu esse ID quando registrou seu aplicativo cliente no Google.
  • username: defina como "email".
  • usernameprefix: opcional. Prefixo anexado a declarações de nome de usuário para evitar conflitos com nomes atuais. Se você não fornecer esse campo e username for um valor diferente de email, o prefixo será padronizado como issuerurl#. É possível usar o valor - para desativar todos os prefixos.
  • group: deixe em branco.
  • groupprefix: deixe em branco.
  • scopes: defina como "email"
  • extraparams: defina como "prompt=consent,access_type=offline".
  • usehttpproxy: defina como "false".
  • capath: deixe em branco.

Como criar uma política de RBAC para o cluster de usuário

Esta seção é destinada aos administradores de cluster.

Depois de criar um cluster, use o controle de acesso baseado em papéis (RBAC) do Kubernetes para conceder acesso a usuários de cluster autenticados. Para conceder acesso a recursos em um namespace específico, crie um Papel e um RoleBinding. Para conceder acesso a recursos em um cluster inteiro, crie um ClusterRole e um ClusterRoleBinding.

Ao usar o Google como seu provedor OpenID, você precisa conceder acesso a usuários individuais. Ele não funciona para conceder acesso a grupos. Isso ocorre porque o token que o provedor do Google OpenID retorna não tem informações sobre os grupos a que um usuário individual pertence.

Por exemplo, suponha que você queira que jane@example.com visualize todos os objetos secret por todo o cluster.

Veja um manifesto para um ClusterRole chamado secret-viewer. Uma pessoa que tem esse papel pode receber, observar e listar qualquer secret no cluster.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-viewer
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "watch", "list"]

Veja um manifesto para um ClusterRoleBinding chamado people-who-view-secrets. A vinculação concede o papel secret-viewer a um usuário chamado jane@example.com.

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: people-who-view-secrets
subjects:
- kind: User
  name: jane@example.com
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-viewer
  apiGroup: rbac.authorization.k8s.io

Para criar o ClusterRole, salve o manifesto em um arquivo chamado secret-viewer-cluster-role.yaml e digite este comando:

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role.yaml

em que [USER_CLUSTR_KUBECONFIG] é o arquivo kubeconfig do cluster de usuário.

Para criar o ClusterRoleBinding, salve o manifesto em um arquivo chamado secret-viewer-cluster-role-binding.yaml e digite este comando:

kubectl --kubeconfig [USER_CLUSTER_KUBECONFIG] apply -f secret-viewer-cluster-role-binding.yaml

Como criar seu primeiro arquivo de configuração de autenticação

Esta seção é destinada aos administradores de cluster.

Depois de criar um cluster de usuário, crie um arquivo de configuração de autenticação para o cluster:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG]

onde [USER_CLUSTER_KUBECONFIG] é o caminho do arquivo kubeconfig do cluster de usuário. Quando você criou o cluster de usuário, gkectl create cluster gerou um arquivo kubeconfig para o cluster.

O comando anterior cria um arquivo chamado kubectl-anthos-config.yaml no diretório atual.

Como adicionar outros clusters ao arquivo de configuração de autenticação

Esta seção é destinada aos administradores de cluster.

É possível armazenar a configuração de autenticação para vários clusters em um único arquivo. Depois, é possível distribuir um arquivo para os desenvolvedores que precisam ter acesso a todos esses clusters.

Comece com um arquivo de configuração de autenticação existente. Em seguida, use o seguinte comando para mesclar esse arquivo com a configuração de um cluster extra:

gkectl create-login-config --kubeconfig [USER_CLUSTER_KUBECONFIG] \
    --merge-from [IN_AUTH_CONFIG_FILE] --output [OUT_AUTH_CONFIG_FILE]

em que

  • [USER_CLUSTER_KUBECONFIG] é o arquivo kubeconfig do cluster extra.

  • [IN_AUTH_CONFIG_FILE] é o caminho do arquivo de configuração de autenticação existente.

  • [OUT_AUTH_CONFIG_FILE] é o caminho em que você quer salvar o arquivo que contém a configuração mesclada. Pode ser o mesmo que [IN_AUTH_CONFIG_FILE].

Como distribuir o arquivo de configuração de autenticação

Esta seção é destinada aos administradores de cluster.

O arquivo de configuração de autenticação que você distribui para os desenvolvedores precisa ter o nome kubectl-anthos-config.yaml. É possível distribuir o arquivo de configuração de autenticação de várias maneiras:

  • Forneça manualmente o arquivo para cada desenvolvedor.

  • Hospede o arquivo em um URL para que os desenvolvedores façam o download dele.

  • Envie o arquivo para a máquina de cada desenvolvedor.

Independentemente do método de distribuição, o arquivo de configuração de autenticação precisa ser colocado neste local na máquina de cada desenvolvedor:

Linux

$HOME/.config/google/anthos/kubectl-anthos-config.yaml

macOS

$HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

Windows

%APPDATA%\google\anthos\kubectl-anthos-config.yaml

Como colocar o arquivo de configuração de autenticação

Esta seção é destinada a desenvolvedores.

O arquivo de configuração de autenticação contém os detalhes de todos os clusters com que é possível fazer autenticação. Não modifique o conteúdo desse arquivo.

Se o administrador do cluster tiver fornecido um arquivo de configuração de autenticação, coloque o arquivo no diretório correto. Se o administrador do cluster já tiver colocado a configuração na máquina, pule esta seção.

Copie o arquivo de configuração de autenticação para o local padrão:

Linux

mkdir -p  $HOME/.config/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/.config/google/anthos/kubectl-anthos-config.yaml

[AUTH_CONFIG_FILE] é o nome do arquivo de configuração de autenticação.

macOS

mkdir -p  $HOME/Library/Preferences/google/anthos/
cp [AUTH_CONFIG_FILE] $HOME/Library/Preferences/google/anthos/kubectl-anthos-config.yaml

[AUTH_CONFIG_FILE] é o nome do arquivo de configuração de autenticação.

Windows

md "%APPDATA%\google\anthos"
copy [AUTH_CONFIG_FILE] "%APPDATA%\google\anthos\kubectl-anthos-config.yaml"

[AUTH_CONFIG_FILE] é o nome do arquivo de configuração de autenticação.

Como conseguir o plug-in do Anthos para Kubectl

Esta seção é destinada aos administradores de cluster.

O plug-in do Anthos para Kubectl está incluído na estação de trabalho do administrador em:

Linux

/usr/bin/kubectl_anthos/v1.0beta/linux_amd64/kubectl-anthos

macOS

/usr/bin/kubectl_anthos/v1.0beta/darwin_amd64/kubectl-anthos

Windows

/usr/bin/kubectl_anthos/v1.0beta/windows_amd64/kubectl-anthos

É possível distribuir o plug-in para os desenvolvedores ou fazer o download dele diretamente.

Como fazer o download do plug-in do Anthos para Kubectl

Esta seção é destinada a administradores e desenvolvedores de clusters.

Cada desenvolvedor precisa ter o plug-in do Anthos para Kubectl em sua própria máquina. Os desenvolvedores podem fazer o download do plug-in individualmente ou o administrador do cluster pode fazer o download do plug-in e distribuí-lo aos desenvolvedores.

Observação para desenvolvedores: pergunte ao administrador do cluster qual versão do plug-in você precisa usar.

Faça o download do plug-in do Anthos para Kubectl:

Linux

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/linux_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

macOS

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/darwin_amd64/kubectl-anthos ./
chmod +x kubectl-anthos

Windows

gsutil cp gs://gke-on-prem-release/kubectl-anthos/v1.0beta/windows_amd64/kubectl-anthos ./
rename kubectl-anthos kubectl-anthos.exe.

Como instalar o plug-in do Anthos para Kubectl

Esta seção é destinada a desenvolvedores.

O administrador do cluster pode fornecer o plug-in do Anthos para Kubectl. Outra opção é o administrador do cluster pedir para você fazer o download do plug-in.

Para instalar o plug-in do Anthos para Kubectl, mova o arquivo executável para qualquer local no seu PATH. O arquivo executável precisa ter o nome kubectl-anthos. Saiba mais em Como instalar plug-ins do kubectl (em inglês).

Verifique se o plug-in do Anthos para Kubectl está instalado:

kubectl plugin list
kubectl anthos version

Como listar clusters disponíveis

Esta seção é destinada a desenvolvedores.

Se o arquivo de configuração de autenticação estiver no caminho padrão, digite este comando para listar os clusters em que é possível fazer autenticação:

kubectl anthos listclusters

Se o arquivo de configuração de autenticação não estiver no caminho padrão, digite este comando para listar os clusters:

kubectl anthos listclusters --loginconfig [AUTH_CONFIG_FILE]

em que [AUTH_CONFIG_FILE] é o caminho para o arquivo de configuração.

Como usar o plug-in do Anthos para Kubectl para fazer autenticação

Esta seção é destinada a desenvolvedores.

Faça login em um cluster de usuário:

kubectl anthos login --cluster [CLUSTER_NAME] --user [USER_NAME] \
    --loginconfig [AUTH_CONFIG_FILE] --kubeconfig [USER_CLUSTER_KUBECONFIG]

em que:

  • [CLUSTER_NAME] pelo nome do cluster de usuário. O nome precisa ser selecionado na lista fornecida pelo comando kubectl anthos listclusters.

  • [USER_NAME] é um parâmetro opcional que especifica o nome de usuário das credenciais armazenadas no arquivo kubeconfig. O valor padrão é [CLUSTER_NAME]-anthos-default-user.

  • [AUTH_CONFIG_FILE] é o caminho do arquivo de configuração de autenticação. Se o arquivo de configuração de autenticação estiver no local padrão, será possível omitir esse parâmetro.

  • [USER_CLUSTER_KUBECONFIG] é o caminho do arquivo kubeconfig do cluster de usuário. Se um arquivo kubeconfig não existir, o comando gerará um novo arquivo kubeconfig a partir do arquivo de configuração de autenticação e adicionará os detalhes e tokens do cluster ao arquivo kubeconfig.

kubectl anthos login inicia um navegador em que é possível inserir suas credenciais.

O arquivo kubeconfig fornecido agora contém um token de ID que kubectl pode usar para fazer a autenticação no servidor da API Kubernetes no cluster de usuário.

O comando kubectl anthos login tem uma sinalização --dry-run opcional. Se você incluir a sinalização --dry-run, o comando imprimirá os comandos kubectl que adicionariam tokens ao arquivo kubeconfig, mas não os salvará no arquivo kubeconfig.

Verifique se a autenticação foi concluída inserindo um comando kubectl. Exemplo:

kubectl get nodes --kubeconfig [USER_CLUSTER_KUBECONFIG]

Como usar o OIDC com o console do Google Cloud

Esta seção é destinada a desenvolvedores.

  1. Verifique se o cluster está configurado para o OIDC.

  2. Verifique se o cluster foi registrado no Google Cloud automaticamente durante a criação do cluster ou manualmente.

  3. Acesse a página Clusters do Kubernetes no Console do Google Cloud.

    Acessar a página de clusters do Kubernetes

  4. Na lista de clusters, localize o cluster do GKE On-Prem e clique em Login.

  5. Selecione Autenticar com o Provedor de identidade configurado para o cluster e clique em LOGIN.

    Você será redirecionado para o provedor de identidade, em que talvez seja necessário fazer login ou consentir para que o console do Google Cloud acesse sua conta. Em seguida, você será redirecionado para a página Clusters do Kubernetes no Console do Google Cloud.

Configuração personalizada

Por padrão, o plug-in do Anthos para Kubectl espera que o arquivo de configuração de autenticação esteja em um determinado local. Se você não quiser colocar o arquivo de configuração de autenticação no local padrão, transmita o caminho do arquivo de configuração de autenticação para os comandos do plug-in usando a sinalização --login-config. Por exemplo, consulte Como usar o plug-in do Anthos para Kubectl para autenticação.

Solução de problemas do OIDC no GKE On-Prem

Configuração inválida

Se o Console do Google Cloud não conseguir ler a configuração do OIDC do cluster, o botão LOGIN será desativado.

Configuração de provedor inválida

Se a configuração do provedor de identidade for inválida, você verá uma tela de erro do provedor de identidade depois de clicar em LOGIN. Siga as instruções específicas do provedor para configurar corretamente o provedor ou o cluster.

Permissões inválidas

Se você concluir o fluxo de autenticação, mas ainda não vir os detalhes do cluster, verifique se concedeu as permissões RBAC corretas à conta usada com o OIDC. Ela pode ser uma conta diferente daquela que você usa para acessar o Console do Google Cloud.

Error: missing 'RefreshToken' field in 'OAuth2Token' in credentials struct

Pode ser que você receba esse erro se o servidor de autorização solicitar o consentimento, mas o parâmetro de autenticação necessário não tiver sido fornecido. Forneça o parâmetro prompt=consent ao campo oidc: extraparams do arquivo de configuração do GKE On-Prem e gere novamente o arquivo de autenticação do cliente com a sinalização --extra-params prompt=consent.

A seguir