Como autenticar com o OIDC e ADFS

Nesta página, mostramos como usar o OpenID Connect (OIDC) com os serviços federados do Active Directory (ADFS, na sigla em inglês) 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.

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. Para tornar o fluxo de autenticação automático para usuários de cluster, o GKE On-Prem fornece o plug-in do Kubectl para OIDC, um plug-in kubectl.

Neste exercício, você usa um conjunto de assistentes de gerenciamento do ADFS para configurar um relacionamento entre a ferramenta de linha de comando kubectl, o servidor ADFS 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 presume que você esteja familiarizado com os escopos e as reivindicações do OpenID.

Estes tópicos se aplicam 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 ADFS atua como um provedor OpenID.

Como fazer o download do plug-in do 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.

Como criar um URI de redirecionamento

É necessário fornecer um URI de redirecionamento que o provedor OpenID possa usar para retornar tokens de código. Os tokens vão para o plug-in do Kubectl para OIDC, que é executado na máquina local de cada funcionário e escuta uma porta escolhida. Escolha um número de porta maior que 1.024 que seja adequado para essa finalidade. Em seguida, o URI de redirecionamento é:

http://localhost:[PORT]/callback

em que [PORT] é o número da porta.

Como configurar o ADFS

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

Como definir o URI de redirecionamento

  1. Abra o painel de gerenciamento do ADFS.

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

  4. Insira seu URI de redirecionamento. Você recebe um ID de cliente. É assim que o provedor OpenID identifica o aplicativo kubectl. Salve o ID do cliente para uso posterior.

  5. Selecione Gerar um secret compartilhado. O aplicativo kubectl usa esse secret para se autenticar no provedor OpenID. Guarde o secret para mais tarde.

Como configurar grupos de segurança (opcional)

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

  2. Selecione Reconhecimento de reivindicaçõ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 kubectl oidc.

  8. Clique em Finish.

Como mapear atributos LDAP para reivindicar nomes

  1. No gerenciamento do ADFS, selecione Confianças de terceira parte confiáveis > Editar política de emissão de reivindicações.

  2. Selecione Send LDAP Attributes as Claims e clique em Next.

  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 Grupos de token - Nomes qualificados. Em Tipo de reivindicação de saída, selecione grupos.

  6. Clique em Concluir e em Aplicar.

Como registrar o kubectl com o ADFS

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

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

onde:

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

  • [SERVER_ROLE_IDENTIFIER] é o identificador de reivindicaçã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

Durante uma instalação, você gera um arquivo de configuração do GKE On-Prem usando gkectl create-config. A configuração inclui a seguinte especificação oidc. Preencha "oidc" com valores específicos do provedor:

oidc:
  issuerurl:
  kubectlredirecturl:
  clientid:
  clientsecret:
  username:
  usernameprefix:
  group:
  groupprefix:
  scopes:
  extraparams:
  usehttpproxy:
  capath:
  • issuerurl: o URL do provedor OpenID, como https://example.com/adfs. Os aplicativos cliente, como o plug-in Kubectl para OIDC, enviam solicitações de autorização para esse URL. O servidor da API Kubernetes usa esse URL para descobrir chaves públicas para verificação de tokens. Precisam usar HTTPS. Este campo é obrigatório.
  • kubectlredirecturl: URL de redirecionamento localhost para o plug-in do Kubectl para OIDC. Você precisa registrar o URL de redirecionamento com o provedor OpenID para uso pelo ID do cliente atribuído a esse cluster. Este campo é obrigatório.
  • clientid: o ID do aplicativo cliente, como o plug-in do Kubectl para OIDC, que faz solicitações de autenticação para o provedor OpenID. Este campo é obrigatório.
  • clientsecret: o secret para o aplicativo cliente. Este campo é obrigatório.
  • usehttpproxy: escolha se quer implantar um proxy reverso 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". Este campo é obrigatório.
  • username: a declaração do JWT a ser usada como nome de usuário. O padrão é sub, que precisa ser um identificador exclusivo do usuário final. Você pode escolher outras declarações, como email ou name, dependendo do provedor OIDC. No entanto, declarações diferentes de email são prefixadas com o URL do emissor para evitar conflitos de nomenclatura com outros plug-ins.
  • usernameprefix: prefixo anexado a declarações de nome de usuário para evitar conflitos com nomes existentes. Se essa sinalização não for fornecida e username não for um e-mail, o prefixo usará o padrão issueruri#. O valor - pode ser usado para desativar todos os prefixos.
  • group: a declaração do JWT que será usada como o grupo do usuário. Se a declaração estiver presente, ela precisa ser uma matriz de strings.
  • groupprefix: prefixo anexado a declarações de grupo para evitar conflitos com nomes existentes. Por exemplo, com um grupo foobar e um prefixo gid-, gid-foobar.
  • scopes: escopos adicionais que serão enviados ao provedor OpenID como uma lista delimitada por comentários.
  • extraparams: parâmetros de chave-valor adicionais que serão enviados ao provedor OpenID.
  • capath: caminho para o certificado da autoridade de certificação (CA) que assinou o certificado da Web do provedor de identidade.

    Os clusters do GKE On-Prem usam TLS para proteger a comunicação entre os componentes. Para que o Kubernetes gere certificados de cliente automaticamente durante a instalação e a inicialização do nó, o GKE On-Prem precisa ser instalado com uma autoridade de certificação.

    Por padrão, o GKE On-Prem cria uma nova autoridade de certificação durante a instalação que gera certificados TLS. A autoridade de certificação e os certificados gerados são armazenados localmente no cluster de administrador.

Exemplo: como autenticar e autorizar um grupo

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 um risco de disponibilidade (se um usuário alterar o e-mail principal) e, potencialmente, um risco de segurança (se um e-mail puder ser reatribuído).

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

Suponha que o provedor crie tokens OpenID que incluam os seguintes campos:

{
  'iss': 'https://server.example.com'
  'sub': 'u98523-4509823'
  'groupList: ['developers@example.corp', 'us-east1-cluster-admins@example.corp']
  ...
}
Dado 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-'
...

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 o certificado da autoridade de certificação (CA) do servidor

O kubeconfig do cluster de usuário armazena os dados da autoridade de certificação do host no 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

Depois de criar e configurar o cluster de usuário para o OpenID, um usuário pode fazer login no cluster transmitindo um arquivo de configuração de autenticação do cliente para kubectl oidc login. Gere um arquivo de configuração de autenticação do cliente digitando este comando:

PowerShell

kubectl oidc client-config `
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URI] `
--client-id [CLIENT_ID] `
--client-secret [CLIENT_SECRET] `
--scopes "allatclaims" `
--cluster-name [USER_CLUSTER_NAME] `
--server [CLUSTER_URL] `
--server-ca-file server-ca-cert `
--issuer-ca-file [ADFS_CA_CERT] `
--extra-params "resource=token-groups-claim"
> client-config.yaml
  • [ISSUER_URI] é o URI de emissor.
  • [REDIRECT_URI] é o URI de redirecionamento.
  • [CLIENT_ID] é o ID do cliente do aplicativo `kubectl`.
  • [CLIENT_SECRET] é a chave secreta do cliente gerada para você.
  • [USER_CLUSTER_NAME] é o nome de cluster do usuário.
  • [CLUSTER_URL] é o URL do servidor da API Kubernetes do cluster.
  • --server-ca-file aceita o caminho para o arquivo de autoridade de certificação criado na seção anterior.
  • [ADFS_CA_CERT] é o caminho para o arquivo de certificado público da autoridade de certificação do ADFS;
  • --extra-param envia um par de chave-valor com a solicitação de autenticação para o provedor OIDC.

Linux

kubectl oidc client-config \
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URI] \
--client-id [CLIENT_ID] \
--client-secret [CLIENT_SECRET] \
--scopes "allatclaims" \
--cluster-name [USER_CLUSTER_NAME] \
--server [CLUSTER_URL] \
--server-ca-file server-ca-cert \
--issuer-ca-file [ADFS_CA_CERT] \
--extra-params "resource=token-groups-claim"
> client-config.yaml
  • [ISSUER_URI] é o URI de emissor.
  • [REDIRECT_URI] é o URI de redirecionamento.
  • [CLIENT_ID] é o ID do cliente do aplicativo `kubectl`.
  • [CLIENT_SECRET] é a chave secreta do cliente gerada para você.
  • [USER_CLUSTER_NAME] é o nome de cluster do usuário.
  • [CLUSTER_URL] é o URL do servidor da API Kubernetes do cluster.
  • --server-ca-file aceita o caminho para o arquivo de autoridade de certificação criado na seção anterior.
  • [ADFS_CA_CERT] é o caminho para o arquivo de certificado público da autoridade de certificação do ADFS;
  • --extra-param envia um par de chave-valor com a solicitação de autenticação para o provedor OIDC.

Esse comando produz um arquivo de autenticação de cliente chamado client-config.yaml. Não edite esse arquivo manualmente. Cada funcionário que precisa se autenticar no cluster de usuário precisa receber client-config.yaml.

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

Para autenticar em um cluster de usuário usando o arquivo de autenticação do cliente, execute as seguintes etapas na máquina local ou na VM:

  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] é o nome de usuário escolhido;
    • [KUBECONFIG_OUTPUT_PATH] é o local de saída do arquivo kubeconfig em que as credenciais são armazenadas.

    kubectl oidc login inicia um navegador em que o usuário ou o funcionário pode 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.

  2. Agora você está autenticado. Para ver se você foi autenticado com sucesso, digite qualquer comando kubectl. Exemplo:

    kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]

Resumo

Sua empresa executa um servidor ADFS que atua como o provedor OpenID. O provedor de OpenID conhece o aplicativo kubectl e sabe que kubectl pode solicitar os escopos openid e allatclaims.

O atributo LDAP Token-Groups Qualified Names no banco de dados do AD é mapeado para a declaração groups no provedor OpenID. 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 lista os grupos de segurança aos quais um funcionário pertence.

A seguir

Anterior
Como autenticar com o OIDC
Próxima
Registro de auditoria