Configure clusters para o GKE Identity Service com OIDC

Este documento destina-se a administradores de clusters ou operadores de aplicações que querem configurar o GKE Identity Service em clusters individuais, permitindo que os programadores e outros utilizadores iniciem sessão nos clusters através dos respetivos detalhes de identidade existentes de um fornecedor OpenID Connect (OIDC).

Pré-requisitos

• O seu cluster tem de ser um cluster do GKE nas instalações (VMware ou bare metal), na AWS ou no Azure. A configuração OIDC por cluster não é suportada para clusters anexados nem clusters do GKE.
• Para autenticar através da Google Cloud consola, cada cluster que quer configurar para a autenticação OIDC tem de estar registado na sua frota de projetos.

Antes de começar

• Certifique-se de que o administrador da plataforma lhe deu todas as informações necessárias do artigo Registe o serviço de identidade do GKE junto do seu fornecedor antes de iniciar a configuração, incluindo o ID de cliente e o segredo do serviço de identidade do GKE.

• Certifique-se de que tem as seguintes ferramentas de linha de comandos instaladas:

  • A versão mais recente da CLI do Google Cloud, que inclui o gcloud, a ferramenta de linha de comandos para interagir com o Google Cloud. Se precisar de instalar a CLI do Google Cloud, consulte o guia de instalação.
  • kubectl para executar comandos em clusters do Kubernetes. Se precisar de instalar o kubectl, siga estas instruções.

  Se estiver a usar o Cloud Shell como ambiente de shell para interagir com o Google Cloud, estas ferramentas são instaladas automaticamente.

• Certifique-se de que inicializou a CLI gcloud para utilização com o projeto onde os clusters estão registados.

• Se precisar de estabelecer ligação ao plano de controlo de um cluster do GKE da AWS ou do Azure que esteja fora da sua VPC atual através de um anfitrião bastion, certifique-se de que criou o anfitrião bastion e iniciou um túnel SSH na porta 8118 antes desta configuração. Em seguida, adicione HTTPS_PROXY=http://localhost:8118 antes dos comandos kubectl quando seguir este guia. Se usou uma porta diferente ao iniciar o túnel SSH, substitua 8118 pela porta selecionada.

Configure clusters

Para configurar os seus clusters de modo a usarem o fornecedor escolhido, o GKE Identity Service precisa que especifique detalhes sobre o fornecedor de identidade, as informações nos tokens JWT que fornece para identificação do utilizador e outras informações facultadas quando regista o GKE Identity Service como uma aplicação cliente.

Por exemplo, se o seu fornecedor criar tokens de identidade com os seguintes campos (entre outros), em que iss é o URI do fornecedor de identidade, sub identifica o utilizador e groupList lista os grupos de segurança aos quais o utilizador pertence:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList': ['[e-mail]', '[e-mail]']
  ...
}

… a sua configuração terá os seguintes campos correspondentes:

issuerURI: 'https://server.example.com'
userClaim: 'sub'
groupsClaim: 'groupList'
...

O administrador da plataforma ou quem gere a identidade na sua organização deve fornecer-lhe a maioria das informações de que precisa para criar a configuração.

O GKE Identity Service usa um tipo de recurso personalizado (CRD) do Kubernetes denominado ClientConfig para a configuração do cluster, com campos para todas as informações de que o GKE Identity Service precisa para interagir com o fornecedor de identidade. Cada cluster do GKE tem um recurso ClientConfig denominado default no espaço de nomes kube-public que atualiza com os detalhes da configuração, seguindo as instruções abaixo.

Pode ver algumas configurações de exemplo específicas para fornecedores populares em Configurações específicas do fornecedor.

kubectl

Para editar o ClientConfig predefinido, certifique-se de que consegue estabelecer ligação ao cluster através de kubectl e execute o seguinte comando:

kubectl --kubeconfig=KUBECONFIG_PATH edit ClientConfigs default -n kube-public

Substitua KUBECONFIG_PATH pelo caminho para o ficheiro kubeconfig do cluster, por exemplo, $HOME/.kube/config.

Um editor de texto carrega o recurso ClientConfig do seu cluster. Adicione o objeto spec.authentication.oidc, conforme mostrado abaixo. Não modifique os dados predefinidos que já foram escritos.

apiVersion: authentication.gke.io/v2alpha1
kind: ClientConfig
metadata:
  name: default
  namespace: kube-public
spec:
  authentication:
  - name: NAME
    oidc:
      certificateAuthorityData: CERTIFICATE_STRING
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      deployCloudConsoleProxy: PROXY_BOOLEAN
      extraParams: EXTRA_PARAMS
      groupsClaim: GROUPS_CLAIM
      groupPrefix: GROUP_PREFIX
      issuerURI: ISSUER_URI
      kubectlRedirectURI: KUBECTL_REDIRECT_URI
      scopes: SCOPES
      userClaim: USER_CLAIM
      userPrefix: USER_PREFIX
      enableAccessToken: ENABLE_ACCESS_TOKEN
    proxy: PROXY_URL

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Sugestão: o GKE Identity Service permite-lhe configurar várias configurações de fornecedores de identidade OIDC, LDAP e SAML num único ClientConfig recurso personalizado (CRD) para autenticação de clientes. O serviço de identidade do GKE tenta a autenticação com cada CRD na ordem em que são definidos e para após a primeira autenticação bem-sucedida.

Pode configurar vários fornecedores de identidade no seu ClientConfig de acordo com os seus requisitos. Isto simplifica a gestão e oferece flexibilidade, permitindo-lhe configurar vários métodos de autenticação num recurso de configuração unificado. O exemplo seguinte ClientConfig define vários fornecedores de identidade na ordem necessária de precedência da autenticação.

apiVersion: v1
items:
- apiVersion: authentication.gke.io/v2alpha1
  kind: ClientConfig
...
  spec:
    authentication:
    - aws:
        region: us-west-2
      name: AWS Login
    - ldap:
    ...
    - saml:
      ...
    - azureAD:
      ...
    - oidc:
      name: Okta OIDC
      ...
    -oidc:
      name: Google OIDC
      ...

A tabela seguinte descreve os campos do objeto ClientConfig oidc. A maioria dos campos é opcional. Os campos que tem de adicionar dependem do seu fornecedor de identidade e das opções de configuração escolhidas pelo administrador da plataforma ao configurar o fornecedor para o GKE Identity Service.

Campo	Obrigatória	Descrição	Formato
nome	sim	O nome que quer usar para identificar esta configuração, normalmente o nome do fornecedor de identidade. Um nome de configuração tem de começar por uma letra, seguida de até 39 letras minúsculas, números ou hífenes, e não pode terminar com um hífen.	String
certificateAuthorityData	Não	Se fornecido pelo administrador da plataforma, uma string de certificado com codificação PEM para o fornecedor de identidade. Inclua a string resultante em certificateAuthorityData como uma única linha.	String
clientID	Sim	O ID de cliente devolvido quando registar o serviço de identidade do GKE junto do seu fornecedor de OIDC.	String
clientSecret	Não	Segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.	String
deployCloudConsoleProxy	Não	Especifica se é implementado um proxy que permite que a Google Cloud consola se ligue a um fornecedor de identidade no local que não seja acessível publicamente através da Internet. Por predefinição, esta opção está definida como false.	Booleano
extraParams	Não	Parâmetros adicionais de chave=valor a enviar para o fornecedor de identidade, especificados como uma lista separada por vírgulas, por exemplo, `prompt=consent,access_type=offline`.	Lista delimitada por vírgulas
groupsClaim	Não	A reivindicação JWT (nome do campo) que o seu fornecedor usa para devolver os grupos de segurança de uma conta.	String
groupPrefix	Não	O prefixo que quer antepor aos nomes dos grupos de segurança para evitar conflitos com os nomes existentes nas suas regras de controlo de acesso se tiver configurações para vários fornecedores de identidade (normalmente, o nome do fornecedor).	String
issuerURI	Sim	O URI onde os pedidos de autorização são feitos ao seu fornecedor de identidade. O URI tem de usar HTTPS e não deve terminar com uma barra invertida.	String de URL
kubectlRedirectURI	Sim	O URL de redirecionamento e a porta usados pela CLI gcloud e especificados pelo administrador da plataforma no registo, normalmente no formato http://localhost:PORT/callback.	String de URL
âmbitos	Sim	Âmbitos adicionais a enviar para o fornecedor OpenID. Por exemplo, o Microsoft Azure e o Okta requerem o âmbito offline_access.	Lista delimitada por vírgulas
userClaim	Não	A reivindicação JWT (nome do campo) que o seu fornecedor usa para identificar uma conta de utilizador. Se não especificar um valor aqui, o serviço de identidade do GKE usa "sub", que é a reivindicação de ID do utilizador usada por muitos fornecedores. Pode escolher outras reivindicações, como "email" ou "nome", consoante o fornecedor OpenID. As reivindicações que não sejam "email" têm o prefixo do URL do emissor para evitar conflitos de nomenclatura.	String
userPrefix	Não	O prefixo que quer anteposto às reivindicações do utilizador para evitar conflitos com nomes existentes, se não quiser usar o prefixo predefinido.	String
enableAccessToken	Não	Se estiver ativado, o GKE Identity Service pode usar o ponto final userinfo do fornecedor de identidade para obter informações de grupos quando um utilizador inicia sessão a partir da linha de comandos. Isto permite-lhe usar grupos de segurança para autorização se tiver um fornecedor (como o Okta) que forneça reivindicações de grupos a partir deste ponto final. Se não estiver definido, considera-se que é false.	Booleano
proxy	Não	Endereço do servidor proxy a usar para estabelecer ligação ao fornecedor de identidade, se aplicável. Pode ter de definir esta opção se, por exemplo, o seu cluster estiver numa rede privada e precisar de se ligar a um fornecedor de identidade público. Por exemplo: http://user:password@10.10.10.10:8888.	String

Depois de concluir o ClientConfig, guarde o ficheiro, o que atualiza o ClientConfig no seu cluster. Se cometer erros de sintaxe, é-lhe pedido que volte a editar a configuração para os corrigir.

Configurações específicas do fornecedor

Esta secção fornece orientações de configuração para alguns fornecedores de OIDC populares, incluindo configurações de exemplo que pode copiar e editar com os seus próprios detalhes.

Aviso: tem de usar o método OIDC padrão ou o método Azure AD (avançado). Não aplique ambas. Estas configurações são mutuamente exclusivas. A tentativa de usar ambos em simultâneo faz com que o plugin OIDC padrão substitua o plugin do Azure AD (avançado), o que leva a falhas de autenticação para utilizadores com mais de 200 associações a grupos.

Azure AD

Esta é a configuração predefinida para configurar o GKE Identity Service com o Azure AD. A utilização desta configuração permite que o GKE Identity Service obtenha informações sobre a associação de utilizadores e grupos do Azure AD, e permite-lhe configurar o controlo de acesso baseado em funções (RBAC) do Kubernetes com base em grupos. No entanto, a utilização desta configuração limita a obtenção de aproximadamente 200 grupos por utilizador.

Se precisar de obter mais de 200 grupos por utilizador, consulte as instruções para o Azure AD (avançado).

...
spec:
  authentication:
  - name: oidc-azuread
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      extraParams: prompt=consent, access_type=offline
      issuerURI: https://login.microsoftonline.com/TENANT_ID/v2.0
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: openid,email,offline_access
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Substitua o seguinte:

• CLIENT_ID: o ID de cliente devolvido quando registar o serviço de identidade do GKE junto do seu fornecedor.
• CLIENT_SECRET: segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.
• TENANT: o tipo de conta do Azure AD a autenticar. Os valores suportados são o ID do inquilino ou o nome do inquilino para contas pertencentes a um inquilino específico. O nome do inquilino também é conhecido como o domínio principal. Para ver detalhes sobre como encontrar estes valores, consulte o artigo Encontre o ID do inquilino e o nome do domínio principal do Microsoft Azure AD.
• PORT: o número da porta escolhido para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registo.

Azure AD (avançado)

Esta configuração opcional para o Azure AD permite que o serviço de identidade do GKE obtenha informações de utilizadores e grupos sem limite no número de grupos por utilizador, através da API Microsoft Graph.

Para ver informações sobre as plataformas que suportam esta configuração, consulte o artigo Configuração avançada para o Azure AD.

Se precisar de obter menos de 200 grupos por utilizador, recomendamos que use a configuração predefinida com um ponto de ancoragem oidc no seu ClientConfig. Para mais informações, consulte as instruções para o Azure AD.

Todos os campos na configuração do exemplo seguinte são obrigatórios.

...
spec:
  authentication:
  - name: NAME
    proxy: PROXY_URL
    azureAD:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      tenant: TENANT_ID
      kubectlRedirectURI: http://localhost:PORT/callback
      groupFormat: GROUP_FORMAT
      userClaim: USER_CLAIM

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Substitua o seguinte:

• NAME: o nome que quer usar para identificar esta configuração, normalmente o nome do fornecedor de identidade. Um nome de configuração tem de começar por uma letra, seguida de até 39 letras minúsculas, números ou hífenes, e não pode terminar com um hífen.
• PROXY_URL: endereço do servidor proxy a usar para estabelecer ligação ao fornecedor de identidade, se aplicável. Pode ter de definir esta opção se, por exemplo, o seu cluster estiver numa rede privada e precisar de se ligar a um fornecedor de identidade público. Por exemplo: http://user:password@10.10.10.10:8888.
• CLIENT_ID: o ID de cliente devolvido quando registar o serviço de identidade do GKE junto do seu fornecedor.
• CLIENT_SECRET: segredo partilhado entre a aplicação cliente OIDC e o fornecedor OIDC.
• TENANT: o tipo de conta do Azure AD a autenticar. Os valores suportados são o ID do inquilino ou o nome do inquilino para contas pertencentes a um inquilino específico. O nome do inquilino também é conhecido como o domínio principal. Para ver detalhes sobre como encontrar estes valores, consulte o artigo Encontre o ID do inquilino e o nome do domínio principal do Microsoft Azure AD.
• PORT: o número da porta escolhido para o URL de redirecionamento usado pela CLI gcloud, especificado pelo administrador da plataforma no registo.
• GROUP_FORMAT: o formato no qual quer obter informações do grupo. Este campo pode assumir valores correspondentes a ID ou NAME dos grupos de utilizadores. Tenha em atenção que esta definição está atualmente disponível apenas para clusters em implementações do Google Distributed Cloud bare metal.
• USER_CLAIM (Opcional): a reivindicação JWT (nome do campo) que o seu fornecedor usa para identificar uma conta. Se não especificar um valor aqui, o GKE Identity Service usa um valor na ordem de "email", "preferred_username" ou "sub" para obter os detalhes do utilizador. Este atributo pode ser usado a partir da versão 1.28 do GKE Enterprise.

Okta

A imagem seguinte mostra como configurar a autenticação usando utilizadores e grupos com o Okta como fornecedor de identidade. Esta configuração permite que o Anthos Identity Service obtenha reivindicações de utilizadores e grupos através de um token de acesso e do ponto final userinfo do Okta.

Nota: embora esta configuração seja para o Okta, também pode obter informações de utilizadores e grupos de qualquer outro fornecedor de identidade que suporte um ponto final userinfo. Na sua configuração, especifique enableAccessToken: true para usar esta funcionalidade.

...
spec:
  authentication:
  - name: okta
    oidc:
      clientID: CLIENT_ID
      clientSecret: CLIENT_SECRET
      cloudConsoleRedirectURI: https://console.cloud.google.com/kubernetes/oidc
      enableAccessToken: true
      extraParams: prompt=consent
      groupsClaim: groups
      issuerURI: https://OKTA_ISSUER_URI/
      kubectlRedirectURI: http://localhost:PORT/callback
      scopes: offline_access,email,profile,groups
      userClaim: email

# Rest of the resource is managed by Google. DO NOT MODIFY.
...

Limites de acesso de grupo

Para utilizadores do Okta, o Anthos Identity Service pode obter informações de grupos para utilizadores cujos nomes de grupos, se concatenados, tenham um comprimento inferior a 170 000 carateres. Isto corresponde a uma associação de aproximadamente 650 grupos, tendo em conta o comprimento máximo do grupo do Okta. Se o utilizador for membro de demasiados grupos, a chamada de autenticação falha.

O que se segue?

Depois de aplicar a configuração, continue a configurar o acesso dos utilizadores aos clusters.