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

Alfa

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Atenção: planeje a instalação com antecedência. As configurações dos clusters, conforme declaradas no arquivo de configuração do GKE On-Prem, tornam-se imutáveis após a criação deles. Não é possível alterar a maioria dos aspectos dos clusters depois de criá-los, incluindo rede e autenticação. As únicas exceções configuráveis são estas:

• Como redimensionar clusters de usuário
• Como criar outros clusters de usuário
• Como fazer upgrade de clusters
• Como criar e gerenciar pools de nós

Nesta página, mostramos como configurar o GKE On-Prem para usar um provedor OpenID para 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.

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

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

Como escolher um provedor de OpenID

Esta seção é destinada aos administradores.

É 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. Para mais informações, consulte Como autenticar com o OIDC e o AD FS.

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 seu provedor OpenID, especifique um URL de redirecionamento que o provedor possa usar para retornar tokens de código ao plug-in 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 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 aos administradores.

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 seus aplicativos cliente com o provedor OpenID

Esta seção é destinada aos administradores.

Antes que seus funcionários possam usar o plug-in Kubectl para OIDC ou o console do Google Cloud com seu provedor OpenID, você precisa registrar esses dois clientes com o provedor OpenID. O registro inclui estas etapas:

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

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

• 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. Esse é o ID que o provedor usa para identificar o plug-in Kubectl para OIDC e o console do Google Cloud.

• Estabelecer uma única chave secreta do cliente. O plug-in do Kubectl para OIDC e o console do Google Cloud usam essa chave secreta para se autenticar no provedor OpenID.

• Estabeleça um escopo personalizado que o plug-in Kubectl para OIDC ou console do Google Cloud possa 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 maneira como você executa essas etapas depende do provedor OpenID. Para saber como executar as etapas de registro com o AD FS, consulte Como autenticar com OIDC e AD FS.

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

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.
  • Para uma lista de parâmetros de autenticação, consulte Parâmetros de URI de autenticação.
  • Para ver uma lista dos parâmetros de autenticação do Microsoft Azure, consulte Enviar a solicitação de login.
  • Se você estiver autorizando um grupo, transmita resource=token-groups-claim.
  • Se o servidor de autorização solicitar consentimento, transmita prompt=consent.
• 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: ['[e-mail]', '[e-mail]']
  ...
}

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.
  • Para uma lista de parâmetros de autenticação, consulte Parâmetros de URI de autenticação.
  • Se você estiver autorizando um grupo, transmita resource=token-groups-claim.
  • Se o servidor de autorização solicitar consentimento, transmita prompt=consent.

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.
  • Para ver uma lista dos parâmetros de autenticação do Google, consulte Parâmetros de URI de autenticação.
  • Para ver uma lista dos parâmetros de autenticação do Microsoft Azure, consulte Enviar a solicitação de login.
  • Se você estiver autorizando um grupo, transmita resource=token-groups-claim.
  • Se o servidor de autorização solicitar consentimento, transmita prompt=consent.

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.

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.