Criar um emissor do OpenID Connect no AKS (Serviço de Kubernetes do Azure)

Aplica-se a: ✔️ AKS Automatic ✔️ AKS Standard

Este artigo descreve como criar e gerenciar um emissor do OpenID Connect (OIDC) para seu cluster AKS (Serviço de Kubernetes do Azure). O emissor do OIDC permite que seu cluster do AKS se integre a provedores de identidade, como Microsoft Entra ID, para que você possa autenticar e fornecer recursos de SSO (logon único) com segurança para aplicativos em execução no cluster.

Para a maioria das cargas de trabalho de produção, o AKS Automatic é a experiência padrão recomendada do AKS. O AKS Automatic está pronto para produção por padrão e inclui o emissor OIDC como uma funcionalidade de segurança pré-configurada. No AKS Standard, o comportamento do emissor do OIDC depende da versão do Kubernetes e do estado do cluster e você pode habilitá-lo manualmente quando necessário.

Para saber mais sobre o AKS Automatic, confira O que é AKS (Serviço de Kubernetes do Azure) Automático?

Emissor OIDC no AKS Automatic e AKS Standard

Ambos os modos de cluster do AKS dão suporte ao emissor OIDC, mas a configuração é diferente:

AKS Automatic: o emissor OIDC é pré-configurado.
AKS Standard: talvez seja necessário habilitar explicitamente o emissor do OIDC, dependendo da versão e se ele já está configurado.

Para a maioria dos cenários de produção, comece com o AKS Automatic para usar padrões prontos para produção e reduza a sobrecarga operacional.

Sobre o OpenID Connect (OIDC) no AKS

OpenID Connect (OIDC) estende o protocolo de autorização OAuth 2.0 para uso como outro protocolo de autenticação emitido pelo Microsoft Entra ID. Você pode usar o OIDC para habilitar o SSO (logon único) entre aplicativos habilitados para OAuth em seu cluster do AKS (Serviço de Kubernetes do Azure) usando um token de segurança chamado token de ID. Você pode habilitar o emissor do OIDC em seus clusters do AKS, o que permite que Microsoft Entra ID (ou a plataforma de gerenciamento de acesso e identidade de outro provedor de nuvem) descubra as chaves de assinatura pública do servidor de API.

Pré-requisitos

Requisitos da plataforma:

CLI do Azure versão 2.42.0 ou posterior (az --version para verificar a versão, instalar ou atualizar CLI do Azure, se necessário).
Kubernetes versão 1.22 ou posterior.

Comportamento específico da versão (AKS Standard):

O emissor OIDC está habilitado por padrão (sem necessidade da opção --enable-oidc-issuer) em clusters AKS recém-criados com Kubernetes versão 1.34 ou posterior.
Para clusters existentes, o OIDC não está habilitado por padrão, independentemente da versão do Kubernetes e requer habilitação manual.
Extensão automática de token desativada (--service-account-extend-token-expiration=false) para a versão 1.30.0 ou posterior do Kubernetes.
Se o emissor do OIDC não tiver sido configurado anteriormente, a habilitação manual será necessária para versões do Kubernetes anteriores à 1.34.
Os tokens de conta de serviço projetados são necessários para clusters Kubernetes versão 1.30 ou posterior.

Considerações importantes:

Você não pode desabilitar o emissor OIDC uma vez habilitado.
Habilitar o emissor do OIDC em clusters existentes requer a reinicialização do servidor de API (breve tempo de inatividade).
O tempo de vida máximo do token é de 24 horas (um dia).

Criar um cluster do AKS com o emissor do OIDC

AKS Automático (padrão recomendado para produção)

No AKS Automatic, o emissor do OIDC é pré-configurado. Você não precisa de uma etapa separada para habilitar o emissor OIDC.

Crie um cluster automático do AKS seguindo o início rápido:

Criar um cluster do AKS (Serviço de Kubernetes do Azure) Automático

AKS Standard

Crie um cluster do AKS Standard usando o az aks create comando com o --enable-oidc-issuer parâmetro.

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>
    
# Create the AKS Standard cluster with OIDC issuer enabled
az aks create \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --node-count 1 \
    --enable-oidc-issuer \
    --generate-ssh-keys

Observação

Em clusters do AKS Standard criados com o Kubernetes versão 1.34 ou posterior, o emissor do OIDC é habilitado por padrão para novos clusters.

Habilitar o emissor do OIDC em um cluster padrão do AKS existente

Habilite o emissor OIDC em um cluster AKS Standard existente usando o comando az aks update com o parâmetro --enable-oidc-issuer.

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Enable the OIDC issuer on the existing AKS Standard cluster
az aks update \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --enable-oidc-issuer

Obter a URL do emissor do OIDC

Obtenha a URL do emissor OIDC usando o az aks show comando.

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Get the OIDC issuer URL
az aks show \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP \
    --query "oidcIssuerProfile.issuerUrl" \
    -o tsv

Por padrão, o emissor usa a URL base https://{region}.oic.prod-aks.azure.com, em que o valor de {region} corresponde ao local em que você implantou o cluster do AKS.

Girar a chave de assinatura do OIDC

Importante

Tenha as seguintes considerações em mente ao girar as chaves de assinatura OIDC:

Se você deseja invalidar a chave antiga imediatamente após a rotação de chaves, é necessário rotacionar a chave OIDC duas vezes e reiniciar os pods usando os tokens de conta de serviço projetados.
As chaves antigas e novas permanecem válidas por 24 horas após a rotação.
Você precisa atualizar o token manualmente a cada 24 horas (a menos que esteja usando Azure bibliotecas de clientes de identidade, que são atualizadas automaticamente).

Gire a chave OIDC usando o az aks oidc-issuer comando.

# Set environment variables
RESOURCE_GROUP=<your-resource-group-name>
CLUSTER_NAME=<your-aks-cluster-name>

# Rotate the OIDC signing keys
az aks oidc-issuer rotate-signing-keys \
    --name $CLUSTER_NAME \
    --resource-group $RESOURCE_GROUP

Obter o documento de descoberta

Acesse a URL do emissor do OIDC em seu navegador e adicione /.well-known/openid-configuration à URL.

Exemplo: https://eastus.oic.prod-aks.azure.com/.well-known/openid-configuration

Sua saída deve ser parecida com o seguinte exemplo de saída:

{
  "issuer": "https://eastus.oic.prod-aks.azure.com/ffffffff-eeee-dddd-cccc-bbbbbbbbbbb0/00000000-0000-0000-0000-000000000000/",
  "jwks_uri": "https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks",
  "response_types_supported": [
    "id_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

Obter o documento JWK Set

No navegador, vá para o jwks_uri do documento de descoberta.

Por exemplo: https://eastus.oic.prod-aks.azure.com/00000000-0000-0000-0000-000000000000/00000000-0000-0000-0000-000000000000/openid/v1/jwks