Como fazer a autenticação com o OpenID Connect (OIDC)

Nesta página, mostramos como configurar o GKE On-Prem para usar um provedor de OpenID para a autenticação em clusters de usuários. Saiba como usar o OIDC com o AD FS em Como autenticar com o OIDC e AD FS. Saiba como usar o OIDC com o provedor do Google OpenID em Como autenticar com OIDC e Google.

Para uma visão geral do fluxo de autenticação do GKE On-Prem, consulte Autenticação.

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

Este tópico presume que você já conhece o OAuth 2.0 e o OpenID Connect. Este tópico pressupõe que você já conhece os escopos e as declarações do OpenID.

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 escolher um provedor de OpenID

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

É possível usar qualquer provedor OpenID da sua escolha. Para ver uma lista de provedores certificados, consulte Certificação OpenID.

Uma possibilidade é usar os Serviços federados do Active Directory (AD FS) como seu provedor OpenID e usar uma instância local do Active Directory como banco de dados de funcionários. Saiba mais em Como autenticar com o OIDC e AD FS.

Outra possibilidade é usar o Google como seu provedor de OpenID.

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 comunicação com seu servidor de OpenID, você precisa especificar um URL de redirecionamento que o provedor possa 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 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 de OpenID, especifique http://localhost:[PORT]/callback como um dos seus URLs de redirecionamento. A maneira de fazer isso depende do seu provedor.

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 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 de OIDC, especifique https://console.cloud.google.com/kubernetes/roidc como um dos seus URLs de redirecionamento. A maneira de fazer isso depende do provedor.

Como registrar aplicativos cliente com o provedor de OpenID

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

Antes que os desenvolvedores possam usar o plug-in do Anthos para Kubectl ou o console do Google Cloud com seu provedor de OpenID, registre esses dois clientes com o provedor de OpenID. O registro inclui estas etapas:

  • Descobrir o URI do emissor do provedor. É aqui que o plug-in do Anthos para Kubectl ou o console do Google Cloud envia as solicitações de autenticação.

  • Forneça ao provedor o URL de redirecionamento do plug-in do Anthos para Kubectl.

  • Forneça ao provedor o URL de redirecionamento para o Console do Google Cloud. Acesse https://console.cloud.google.com/kubernetes/oidc.

  • Estabelecer um único ID do cliente. Este é o ID que o provedor usa para identificar o plug-in do Anthos para Kubectl e o console do Google Cloud.

  • Estabelecer uma única chave secreta do cliente. O plug-in do Anthos para Kubectl e o console do Google Cloud usam este secret para fazer a autenticação no provedor de OpenID.

  • Estabeleça um escopo personalizado que o plug-in do Anthos para Kubectl ou o console do Google Cloud possam usar para solicitar os grupos de segurança do usuário.

  • Estabeleça um nome de declaração personalizado que o provedor usará para retornar os grupos de segurança do usuário.

A execução dessas etapas depende do seu provedor OpenID. Saiba como executar as etapas de registro com o AD FS em Como autenticar com o OIDC e AD FS.

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: obrigatório. URL do provedor de OpenID, como "https://example.com/adfs". 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 para descobrir chaves públicas a fim de verificar tokens. É necessário usar HTTPS.
  • kubectlredirecturl:: obrigatório. O URL de redirecionamento configurado anteriormente para o plug-in do Anthos para Kubectl.
  • clientid: obrigatório. O ID do aplicativo cliente que faz solicitações de autenticação para o provedor OpenID. Tanto o plug-in do Anthos para Kubectl quanto o Console do Google Cloud usam esse ID.
  • clientsecret: opcional. O secret do aplicativo cliente. Tanto o plug-in do Anthos para Kubectl quanto o Console do Google Cloud usam esse secret.
  • username: opcional. Declaração do JWT a ser usada como nome de usuário. O padrão é sub, que deve ser um identificador exclusivo do usuário final. É possível escolher outras declarações, como email ou name, dependendo do provedor OpenID. No entanto, declarações diferentes de email são prefixadas com o URL do emissor para evitar conflitos de nomes com outros plug-ins.
  • 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: opcional. A declaração do JWT que o provedor usará para retornar seus grupos de segurança.
  • groupprefix: opcional. Prefixo anexado para agrupar declarações e evitar conflitos com nomes atuais. Por exemplo, um grupo foobar e um prefixo gid-, gid-foobar. Por padrão, esse valor está vazio e não há prefixo.
  • scopes: opcional. Escopos extras a serem enviados ao provedor OpenID como uma lista delimitada por vírgulas.
    • Para autenticação com o Microsoft Azure ou Okta, transmita offline_access.

  • extraparams: opcional. Outros parâmetros de chave-valor a serem enviados ao provedor OpenID como uma lista delimitada por vírgulas.
  • usehttpproxy: opcional. Especifica se um proxy reverso precisa ser implantado no cluster para permitir que o Console do Google Cloud acesse o provedor OIDC local para autenticar usuários. O valor precisa ser uma string: "true" ou "false". Se o provedor de identidade não estiver acessível pela Internet pública e você quiser autenticar usando o Console do Google Cloud, esse campo precisará ser definido como "true". Se for deixado em branco, o padrão deste campo será "false".

  • capath: opcional. Caminho para o certificado da autoridade de certificação (CA, na sigla em inglês) que emitiu o certificado da Web do seu provedor de identidade. Pode ser que esse valor não seja necessário. Por exemplo, se o certificado do provedor de identidade tiver sido emitido por uma CA pública conhecida, você não precisará fornecer um valor aqui. No entanto, se usehttpproxy for "true", esse valor precisará ser fornecido, mesmo para uma CA pública conhecida.

Exemplo: como autorizar usuários e grupos

Muitos provedores codificam propriedades de identificação do usuário, como IDs de e-mail e usuário, em um token. No entanto, essas propriedades têm riscos implícitos para políticas de autenticação:

  • Os IDs do usuário podem dificultar a leitura e a auditoria das políticas.
  • Os e-mails podem criar riscos de disponibilidade (se um usuário alterar o e-mail principal) e de segurança (se um e-mail puder ser reatribuído).

Portanto, é uma prática recomendada usar políticas de grupo, já que um ID de grupo pode ser permanente e fácil de auditar.

Suponha que seu provedor crie tokens de identidade que incluam os campos a seguir:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}

Com esse formato de token, você preencheria a especificação oidc do arquivo de configuração da seguinte forma:

issueruri: 'https://server.example.com'
username: 'sub'
usernameprefix: 'uid-'
group: 'groupList'
groupprefix: 'gid-'
extraparams: 'resource=token-groups-claim'
...

Depois de criar o cluster de usuário, use o controle de acesso baseado em papéis (RBAC, na sigla em inglês) do Kubernetes para conceder acesso prioritário aos usuários autenticados. Por exemplo, crie um ClusterRole que conceda aos usuários acesso somente leitura aos secrets do cluster e um recurso ClusterRoleBinding para vincular o papel ao grupo autenticado:

ClusterRole

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: secret-reader
rules:
- apiGroups: [""]
  # The resource type for which access is granted
  resources: ["secrets"]
  # The permissions granted by the ClusterRole
  verbs: ["get", "watch", "list"]

ClusterRoleBinding

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: read-secrets-admins
subjects:
  # Allows anyone in the "us-east1-cluster-admins" group to
  # read Secrets in any namespace within this cluster.
- kind: Group
  name: gid-us-east1-cluster-admins # Name is case sensitive
  apiGroup: rbac.authorization.k8s.io
  # Allows this specific user to read Secrets in any
  # namespace within this cluster
- kind: User
  name: uid-u98523-4509823
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: ClusterRole
  name: secret-reader
  apiGroup: rbac.authorization.k8s.io

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, para uma configuração padrã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

Se você não quiser usar a configuração padrão, crie uma configuração personalizada.

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 para Linux e macOS precisa ter o nome kubectl-anthos. O arquivo executável para Windows precisa ter o nome kubectl-anthos.exe. Saiba mais em Como instalar plug-ins do kubectl.

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.