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
- Use o Active Directory Federation Services (ADFS) como o provedor do OpenID e use uma instância local do AD como o banco de dados de funcionários. Consulte Como fazer a autenticação com OIDC e ADFS.
- Use algum outro provedor OpenID.
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, comohttps://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, comoemail
ouname
, dependendo do provedor OIDC. No entanto, declarações diferentes deemail
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 eusername
não for um e-mail, o prefixo usará o padrãoissueruri#
. 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 grupofoobar
e um prefixogid-
,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:
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.
Agora você está autenticado. Para ver se você foi autenticado com sucesso, digite qualquer comando
kubectl
. Exemplo:kubectl get nodes --kubeconfig [KUBECONFIG_OUTPUT_PATH]