Como autenticar com o OIDC e AD FS

Nesta página, mostramos como usar o OpenID Connect (OIDC) com os Serviços de Federação do Active Directory (AD FS) para configurar a autenticação de clusters de usuários do GKE On-Prem. O AD FS só é compatível com o OIDC nas versões 2016 e superior.

Para uma visão geral do fluxo de autenticação, consulte Autenticação. Para informações sobre como usar provedores OpenID diferentes do AD FS, consulte Como autenticar com o OpenID Connect.

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. Use um conjunto de assistentes de gerenciamento do AD FS para configurar o servidor do AD FS e o banco de dados de funcionários do AD.

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 (links em inglês).

Este tópico se aplica a empresas que têm a seguinte infraestrutura:

  • A empresa usa o Active Directory (AD) para o banco de dados de funcionários.
  • A empresa executa um servidor dos Serviços de Federação do Active Directory (AD FS).
  • O servidor do AD FS atua como um provedor 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 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 do AD FS, você precisa especificar um URL de redirecionamento que o servidor do AD FS pode usar para retornar tokens de ID 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 servidor do AD FS, especifique http://localhost:[PORT]/callback como um dos 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 seu servidor do AD FS, especifique https://console.cloud.google.com/kubernetes/oidc como um dos URLs de redirecionamento.

Como configurar o AD FS

Veja nas seções a seguir como configurar o AD FS para o GKE On-Prem.

Como definir os URLs de redirecionamento

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

  1. Abra o painel de gerenciamento do AD FS.

  2. Selecione Grupos de aplicativos, > Ações > Adicionar um grupo de aplicativos.

  3. Selecione Aplicativo do servidor. Insira um nome e uma descrição de sua escolha. Clique em Próximo.

  4. Insira os dois URLs de redirecionamento. Você recebe um ID de cliente. É assim que o servidor do AD FS identifica o plug-in do Anthos para Kubectl e o Console do Google Cloud. Salve o ID do cliente para uso posterior.

  5. Selecione Gerar um secret compartilhado. O plug-in do Anthos para Kubectl e o Console do Google Cloud usa esse secret para fazer a autenticação no servidor do AD FS. Guarde o secret para depois.

Como configurar grupos de segurança (opcional)

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

  1. No gerenciamento do AD FS, selecione Confiança de terceira parte confiável > Adicionar uma nova confiança de terceira parte confiável.

  2. Selecione Reconhecimento de declarações e clique em Iniciar.

  3. Selecione Inserir dados sobre terceiros confiáveis manualmente.

  4. Insira um nome de exibição.

  5. Pule os próximos dois passos.

  6. Insira um identificador de confiança da parte confiável. Sugestão: token-groups-claim.

  7. Em Política de controle de acesso, selecione Permitir todos. Isso significa que todos os funcionários compartilham as informações do grupo de segurança com o plug-in do Anthos para Kubectl e o Console do google Cloud.

  8. Clique em Concluir.

Como mapear atributos LDAP para nomes de declaração

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

  1. No gerenciamento do AD FS, selecione Confiança de terceira parte confiável > Editar política de emissão de declarações.

  2. Selecione Enviar atributos LDAP como declarações e clique em Próximo.

  3. Em Nome da regra de declaração, insira groups.

  4. Em Armazenamento de atributos, selecione Active Directory.

  5. Na tabela, em Atributo LDAP, selecione:

    • AD FS versão 5.0 e mais recentes: Grupos de token qualificados pelo nome de domínio
    • Versões do AD FS anteriores à 5.0: Nomes qualificados de grupos de token

  6. Em Tipo de declaração de saída, selecione:

    • AD FS versão 5.0 e mais recentes: Grupo
    • Versões do AD FS anteriores à 5.0: grupos

  7. Clique em Concluir e em Aplicar.

Como registrar o plug-in do Anthos para Kubectl e o Console do Google Cloud com o AD FS

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

Abra uma janela do PowerShell no modo de administrador e digite este comando:

Grant-AD FSApplicationPermission `
    -ClientRoleIdentifier "[CLIENT_ID]" `
    -ServerRoleIdentifier [SERVER_ROLE_IDENTIFIER] `
    -ScopeName "allatclaims", "openid"

em que:

  • [CLIENT_ID] é o ID do cliente que você recebeu anteriormente;

  • [SERVER_ROLE_IDENTIFIER] é o identificador de declaração inserido anteriormente. Lembre-se de que o identificador sugerido foi token-groups-claim.

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. Outros escopos a serem enviados ao provedor OpenID como uma lista delimitada por vírgulas.
    • Para autenticação com o Microsoft Azure, 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".

  • 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, 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.

Resumo

Sua empresa executa um servidor AD FS que atua como o provedor OpenID. O provedor OpenID conhece seus dois aplicativos clientes: o plug-in Anthos para Kubectl e o Console do Google Cloud. O provedor OpenID sabe que os aplicativos cliente podem solicitar os escopos openid e allatclaims.

Na versão do AD FS anterior à 5.0, o atributo LDAP Token-Groups Qualified Names no banco de dados do AD é mapeado para a declaração groups no provedor de OpenID. Na versão 5.0 e mais recentes, o atributo é Token-Groups Qualified by Domain name. O provedor retorna tokens que incluem o ID do funcionário, o ID do emissor, a declaração openid e a declaração groups. A declaração groups (Group em 5.0) lista os grupos de segurança aos quais um funcionário pertence.

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