Como autenticar com o OIDC e o AD FS

Nesta página, mostramos como usar o OpenID Connect (OIDC) com o Active Directory Federation Services (AD FS) para configurar a autenticação de clusters de usuários do GKE On-Prem.

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 tornar esse fluxo automático, o GKE On-Prem fornece o plug-in Kubectl para OIDC, um plug-in kubectl (em inglês).

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

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

Esta seção é destinada a administradores e funcionários que querem usar o plug-in Kubectl para OIDC.

Faça o download do plug-in e defina as permissões de acesso:

Linux

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/linux_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Windows

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/windows_amd64/kubectl-oidc .

macOS

gsutil cp gs://gke-on-prem-release/oidc-plugin/v1.1alpha/darwin_amd64/kubectl-oidc .
chmod +x kubectl-oidc

Como instalar o plug-in

Instale o plug-in movendo o arquivo executável para qualquer local no PATH. O arquivo executável precisa ter o nome kubectl-oidc. Para saber mais, consulte Como instalar plug-ins do kubectl (em inglês).

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

Esta seção é destinada aos administradores.

Como parte do estabelecimento de um relacionamento com o servidor do AD FS, especifique um URL de redirecionamento que o servidor do AD FS possa usar para retornar tokens de ID ao plug-in do Kubectl para OIDC. O plug-in do Kubectl para OIDC é executado na máquina local de cada funcionário e detecta em uma porta que você escolher. 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 aos administradores.

Além de ter um URL de redirecionamento para o plug-in do Kubectl para OIDC, 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

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

Como definir os URLs de redirecionamento

  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 Kubectl para OIDC e console do Google Cloud. Salve o ID do cliente para uso posterior.

  5. Selecione Gerar um secret compartilhado. O plug-in Kubectl para OIDC e console do Google Cloud usa esse secret para autenticar no servidor AD FS. Guarde o secret para depois.

Como configurar grupos de segurança (opcional)

  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 Kubectl para OIDC e o console do Google Cloud.

  8. Clique em Concluir.

Como mapear atributos LDAP para nomes de declaraçã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 Kubectl para OIDC e console do Google Cloud com o AD FS

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 do OIDC no arquivo de configuração do cluster

Esta seção é destinada a funcionários que queiram criar um cluster configurado para usar o OIDC.

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:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: obrigatório. URL do provedor de OpenID, como https://example.com/adfs. Aplicativos clientes, como o plug-in do Kubectl para OIDC 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.
  • clientid: obrigatório. O ID do aplicativo cliente que faz solicitações de autenticação para o provedor OpenID. O plug-in do Kubectl para OIDC e o console do Google Cloud usam esse ID.
  • clientsecret: opcional. O secret do aplicativo cliente. O plug-in do Kubectl para OIDC e 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.
  • scopes: opcional. Escopos extras a serem enviados ao provedor OpenID como uma lista delimitada por vírgulas.
  • 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 será implantado no cluster para permitir que o Connect Agent acesse o provedor OIDC local para autenticar usuários. O valor precisa ser uma string: "true" ou "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.

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 salvar o certificado da autoridade de certificação do servidor da API Kubernetes

Esta seção é destinada a funcionários que criaram um cluster de usuário e agora querem usar o plug-in Kubectl para OIDC.

O cluster de usuário tem um servidor da API Kubernetes. E o arquivo kubeconfig do cluster de usuário armazena o certificado da autoridade de certificação que emitiu um certificado para o servidor da API Kubernetes. O certificado da autoridade de certificação é o valor codificado em base 64 do campo certificate-authority-data. É necessário decodificar esse valor e armazená-lo em um arquivo local, como server-ca-cert:

cat [USER_CLUSTER_KUBECONFIG]  | grep certificate-authority-data | awk '{ print $2}' | base64 --decode > server-ca-cert

Como gerar o arquivo de configuração de autenticação do cliente

Esta seção é destinada a funcionários que criaram um cluster de usuário e agora querem usar o plug-in Kubectl para OIDC.

Para gerar um arquivo de configuração de autenticação de cliente, digite o seguinte comando:

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URL] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "[CUSTOM_SCOPES]" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file [SERVER_CA_CERT] \
--issuer-ca-file [PROVIDER_CA_CERT] \
--extra-params [KEY]=[VALUE], ... # e.g. --extra-params "resource=token-groups-claim"
> client-config.yaml

onde:

  • [ISSUER_URI] é o URI de emissor.
  • [REDIRECT_URL] é o URL de redirecionamento do plug-in Kubectl para OIDC.
  • [CLIENT_ID] é o ID do cliente do plug-in do Kubectl para OIDC.
  • [CLIENT_SECRET] é a chave secreta do cliente do plug-in Kubectl para OIDC.
  • [USER_CLUSTER_NAME] é o nome de cluster do usuário.
  • [CLUSTER_URL] é o URL do servidor da API Kubernetes do cluster de usuário.
  • [SERVER_CA_FILE] é o caminho para o certificado da autoridade de certificação que emitiu um certificado para o servidor da API Kubernetes. Este é o arquivo de certificado que você criou na seção anterior.
  • [PROVIDER_CA_CERT] é o caminho para o certificado da autoridade de certificação que assinou o certificado do provedor OpenID. Este é o mesmo valor de oidc:cacert no arquivo de configuração do cluster.
  • [CUSTOM_SCOPES] é a lista separada por vírgulas dos escopos personalizados dos grupos de segurança. Este é o mesmo valor de oidc:scopes no arquivo de configuração do cluster.
  • --extra-params [KEY]=[VALUE], ... é uma lista de pares de chave-valor delimitados por vírgulas a serem incluídos nas solicitações de autorização para o provedor OpenID.

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URL] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "[CUSTOM_SCOPES]" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file [SERVER_CA_CERT] `
--issuer-ca-file [PROVIDER_CA_CERT] `
--extra-params [KEY]=[VALUE]
> client-config.yaml

onde:

  • [ISSUER_URI] é o URI de emissor.
  • [REDIRECT_URL] é o URL de redirecionamento do plug-in Kubectl para OIDC.
  • [CLIENT_ID] é o ID do cliente do plug-in do Kubectl para OIDC.
  • [CLIENT_SECRET] é a chave secreta do cliente do plug-in Kubectl para OIDC.
  • [USER_CLUSTER_NAME] é o nome de cluster do usuário.
  • [CLUSTER_URL] é o URL do servidor da API Kubernetes do cluster de usuário.
  • [SERVER_CA_FILE] é o caminho para o certificado da autoridade de certificação que emitiu um certificado para o servidor da API Kubernetes. Este é o arquivo de certificado que você criou na seção anterior.
  • [PROVIDER_CA_CERT] é o caminho para o certificado da autoridade de certificação que assinou o certificado do provedor OpenID. Este é o mesmo valor de oidc:cacert no arquivo de configuração do cluster.
  • [CUSTOM_SCOPES] é a lista separada por vírgulas dos escopos personalizados dos grupos de segurança. Este é o mesmo valor de oidc:scopes no arquivo de configuração do cluster.
  • --extra-params [KEY]=[VALUE], ... é uma lista de pares de chave-valor delimitados por vírgulas a serem incluídos nas solicitações de autorização para o provedor OpenID.

Esse comando produz um arquivo de configuração de autenticação de cliente chamado client-config.yaml. Não edite esse arquivo manualmente.

Como autenticar em um cluster de usuários usando o plug-in do Kubectl para OIDC

Esta seção é destinada a funcionários que criaram um cluster de usuário e agora querem usar o plug-in Kubectl para OIDC.

  1. Inicialize o plug-in usando o arquivo client-config.yaml:

    kubectl oidc login --clientconfig-file=client-config.yaml --user [NAME] \
    --kubeconfig [KUBECONFIG_OUTPUT_PATH]

    onde:

    • [NAME] é seu nome de usuário.
    • [KUBECONFIG_OUTPUT_PATH] é o caminho para o arquivo kubeconfig em que o plug-in do Kubectl para OIDC armazenará as credenciais.

    kubectl oidc login inicia um navegador em que é possível inserir as credenciais.

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

    Observação: os usuários do Windows podem precisar executar o comando como login kubectl-oidc.exe em vez de kubectl oidc login.

  2. Verifique se a autenticação foi bem-sucedida executando qualquer comando kubectl. Exemplo:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Como usar o OIDC com o console do Google Cloud

Esta seção é destinada a funcionários que criaram um cluster de usuário e agora querem usar o console do Google Cloud para fazer a autenticação no cluster.

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

  2. Verifique se o cluster foi registrado no Google Cloud automaticamente durante a criação dele 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 ao provedor de identidade, em que talvez seja necessário fazer login ou dar o consentimento para o console do Google Cloud acessar 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. Seu provedor OpenID sabe sobre os dois aplicativos de cliente: o plug-in Kubectl para OIDC 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 na 5.0) lista os grupos de segurança aos quais um funcionário pertence.

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. Essa 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