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

Nesta página, mostramos como usar um provedor OpenID para configurar a autenticação de clusters de usuário do GKE On-Prem. Para saber como usar o OIDC com o AD FS, consulte Como autenticar com o OIDC e o 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. 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ê configurará um relacionamento entre o provedor OpenID e kubectl.

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 declarações do OpenID.

Como escolher um provedor de identidade

Independentemente da opção escolhida, é possível o plug-in do Kubectl para OIDC, descrito nestas instruções, para agilizar a configuração da autenticação e o próprio processo de autenticação. Este tópico explica como usar um provedor OpenID diferente do ADFS.

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

Como parte do estabelecimento de um relacionamento com o provedor OpenID, especifique um URI de redirecionamento que o provedor possa usar para retornar tokens de ID. Os tokens vão para o plug-in do Kubectl para OIDC, que é executado na máquina local de cada funcionário e detecta 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 registrar o plug-in do Kubectl para OIDC com o provedor OpenID

Antes de usar o plug-in Kubectl para OIDC com o provedor do OpenID, você precisa registrar o plug-in no provedor. O registro inclui estas etapas:

  • Saiba o URI do emissor do provedor. É aqui que o plug-in envia solicitações de autenticação.

  • Informe ao provedor o URI de redirecionamento.

  • Estabeleça um ID de cliente. Esse é o ID que o provedor usará para identificar o plug-in.

  • Estabeleça uma chave secreta do cliente. O plug-in usa essa chave secreta para se autenticar no provedor OpenID.

  • Estabeleça um escopo personalizado que o plug-in 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 ADFS, consulte Como fazer a autenticação com OIDC e ADFS.

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:

Linux

kubectl oidc client-config
--issuer-uri [ISSUER_URI] \
--redirect-uri [REDIRECT_URI] \
--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 [CA_CERT] \
--extra-params [KEY]=[VALUE]
> 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 de usuário.
  • --server-ca-file aceita o caminho para o arquivo da autoridade de certificação criado na seção anterior.
  • [CA_CERT] é o caminho para o arquivo da autoridade de certificação público do emissor.
  • [CUSTOM_SCOPES] é a lista separada por vírgulas dos escopos personalizados dos grupos de segurança.
  • --extra-param envia um par de chave-valor com a solicitação de autenticação para o provedor OIDC.

PowerShell

kubectl oidc client-config
--issuer-uri [ISSUER_URI] `
--redirect-uri [REDIRECT_URI] `
--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 [CA_CERT] `
--extra-params [KEY]=[VALUE]
> 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 de usuário.
  • --server-ca-file aceita o caminho para o arquivo da autoridade de certificação criado na seção anterior.
  • [CA_CERT] é o caminho para o arquivo da autoridade de certificação público do emissor.
  • [CUSTOM_SCOPES] é a lista separada por vírgulas dos escopos personalizados dos grupos de segurança.
  • --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.

Sobre certificados TLS

Os clusters de usuário do GKE On-Prem usam TLS para proteger toda a comunicação entre os componentes do cluster. 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.

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 serã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]
Próxima
Como autenticar com o OIDC e ADFS