Pular para o conteúdo

Provedores de Identidade para Website

Autenticação de website cria um user pool do Amazon Cognito, e por padrão apenas usuários que têm um nome de usuário e senha nesse pool podem fazer login. Se sua equipe ou clientes já têm contas em um provedor de identidade (IdP), como Okta, Auth0 ou Microsoft Entra ID, eles precisariam de uma segunda conta apenas para o seu website.

Executar ts#website#auth com --federation=oidc permite que você adicione provedores de identidade OpenID Connect (OIDC) externos ao user pool. Você lista os provedores de identidade no seu código de infraestrutura: a prop oidcIdentityProviders de UserIdentity no CDK, ou a variável oidc_identity_providers do módulo user_identity no Terraform. A página de login então mostra um botão para cada provedor de identidade ao lado do formulário de nome de usuário e senha.

  • Seu website ainda envia usuários para a página de login do Cognito. A página agora tem um botão nomeado após cada provedor de identidade.
  • Um usuário que escolhe um botão faz login naquele provedor de identidade. O provedor de identidade os envia de volta ao Cognito em seu URI de redirecionamento, https://<cognito domain>/oauth2/idpresponse.
  • O Cognito cria um usuário no seu user pool para eles, um usuário federado, e copia as claims que você mapeia (por exemplo email) nos atributos do usuário.
  • O Cognito então emite o mesmo tipo de tokens que emite para um usuário local. Suas APIs, agentes e identity pool os aceitam sem nenhuma alteração.

Usuários com um nome de usuário e senha no pool ainda podem fazer login.

Adicionar um provedor de identidade pode permitir que muito mais pessoas entrem no seu website do que você espera. A opção allowSignup de ts#website#auth não se aplica a usuários federados. O Cognito cria um usuário federado na primeira vez que alguém faz login através do provedor de identidade, mesmo quando o user pool não permite que os usuários se cadastrem. Cada usuário federado também recebe a função autenticada do identity pool, para que possam chamar suas APIs e agentes como qualquer usuário conectado pode.

Os provedores de identidade se aplicam a todo o user pool. Cada website que usa o pool mostra seus botões e aceita seus usuários.

O provedor de identidade, portanto, decide quem pode fazer login. Configure-o para que faça login apenas das pessoas que precisam do seu website:

  • Microsoft Entra ID: nas propriedades da aplicação empresarial da aplicação, defina “Assignment required?” como Yes e atribua apenas os usuários ou grupos que precisam de acesso. Com o padrão, No, todos os usuários no seu tenant podem fazer login.
  • Okta: atribua a aplicação apenas aos grupos que precisam de acesso.
  • Auth0: desabilite cadastros em cada conexão que a aplicação usa e habilite para a aplicação apenas as conexões cujos usuários precisam de acesso. Caso contrário, qualquer pessoa que se cadastre através de uma conexão habilitada, por exemplo uma conexão social, pode fazer login.

Execute o gerador ts#website#auth com --federation=oidc. Você pode executá-lo em um website que ainda não tem autenticação, ou em um website que já a tem. Ambos dão o mesmo resultado.

Execute este gerador@aws/nx-plugin:ts#website#auth

pnpm nx g @aws/nx-plugin:ts#website#auth --federation=oidc
Monte seu comando6

Obrigatório

O gerador não adiciona nenhum provedor de identidade. A lista começa vazia, então o login funciona como antes até que você adicione uma entrada. Você adiciona provedores de identidade ao seu código de infraestrutura, então adicionar um segundo não precisa de outra execução do gerador.

Executar o gerador novamente com --federation=oidc não altera nenhum arquivo. Executá-lo com --federation=none, ou sem --federation, mantém a federação que já está lá.

Adicione uma entrada para cada provedor de identidade e então faça o deploy. O client secret nunca vai para o seu código. Você o armazena no AWS Secrets Manager e fornece seu nome, conforme Configurar seu provedor de identidade descreve.

Passe os provedores de identidade para UserIdentity na sua stack:

packages/infra/src/stacks/application-stack.ts
import { MyWebsite, UserIdentity } from '@my-scope/common-constructs';
const identity = new UserIdentity(this, 'Identity', {
oidcIdentityProviders: [
{
name: 'Okta',
issuerUrl: 'https://example.okta.com',
clientId: '0oa1example',
clientSecretName: 'okta-oidc-client-secret',
},
{
name: 'Entra',
issuerUrl: 'https://login.microsoftonline.com/<tenant-id>/v2.0',
clientId: '11111111-2222-3333-4444-555555555555',
clientSecretName: 'entra-oidc-client-secret',
identifiers: ['example.com'],
},
],
});
new MyWebsite(this, 'MyWebsite');

OidcIdentityProviderProps, o tipo de cada entrada, é exportado do seu pacote de constructs compartilhados, então você pode construir a lista em outro lugar e importar o tipo.

Cada provedor de identidade na lista tem estas propriedades. As opções do gerador são descritas em autenticação de website.

Prop CDKAtributo TerraformObrigatórioPadrãoDescrição
namenameSimMostrado no botão de login. O Cognito prefixa nomes de usuário federados com ele em minúsculas (<name>_<sub>). 3-32 letras, dígitos e hífens, começando com uma letra. Não COGNITO. Único na lista, ignorando maiúsculas/minúsculas. No CDK deve ser uma string literal, não um token.
issuerUrlissuer_urlSimO issuer exatamente como aparece na claim iss dos tokens do provedor de identidade. Deve usar https://.
clientIdclient_idSimClient ID da aplicação registrada no provedor de identidade.
clientSecretNameclient_secret_nameSimNome do secret do Secrets Manager que contém o client secret como uma string simples. Um nome, não um ARN.
scopesscopesNãoopenid, email, profileEscopos OAuth a solicitar. Deve incluir openid.
attributeMappingattribute_mappingNãoemail, given_name e family_name, cada um para a claim com o mesmo nomeAtributo do user pool para claim do provedor de identidade. Veja Mapeamento de atributos.
identifiersidentifiersNãoNenhumIdentificadores, como domínios de email, que o Cognito pode usar para enviar um usuário a este provedor de identidade.

O código fornecido verifica cada entrada antes que qualquer coisa seja implantada:

UserIdentity lança uma exceção quando você o cria com uma entrada que quebra uma regra, então cdk synth falha. O build do projeto infra executa cdk synth. A mensagem nomeia a entrada, por exemplo UserIdentity: oidcIdentityProviders[1] (Entra): Microsoft Entra ID issuers have no trailing slash. Use https://login.microsoftonline.com/<tenant-id>/v2.0.

Um valor que é um token, por exemplo um lido do AWS Systems Manager Parameter Store, não é verificado. Um valor errado então falha no deploy em vez do synth. name não deve ser um token.

As regras:

  • name: 3-32 letras, dígitos e hífens, começando com uma letra. Não COGNITO em nenhum caso, porque o Cognito o reserva para login com o próprio user pool.
  • Os nomes são únicos na lista, ignorando maiúsculas/minúsculas, porque o Cognito prefixa nomes de usuário federados com o nome em minúsculas. Por exemplo, Okta e OKTA não podem estar ambos na lista. test-idp e testidp podem, porque seus prefixos diferem.
  • O issuer usa https:// e não tem query, fragment, nome de usuário, senha ou espaços em branco. No CDK ele também deve ser analisável como uma URL. No Terraform uma expressão regular o verifica, que aceita algumas URLs malformadas que o CDK recusa.
  • Microsoft Entra ID: os issuers multi-tenant (common, organizations, consumers e 9188040d-6c67-4c5b-b112-36a304b66dad) são recusados, e o issuer não deve terminar com uma barra.
  • Auth0: um issuer em *.auth0.com deve terminar com uma barra.
  • O client ID não está vazio.
  • O nome do secret tem 1-512 letras, dígitos e / _ + = . @ -. Estas são as regras de nomenclatura do Secrets Manager, então um ARN é recusado.
  • Os escopos incluem openid. No CDK cada escopo também deve ser não vazio e não ter espaços em branco.
  • As chaves e valores do mapeamento de atributos seguem as regras em Mapeamento de atributos.
  • No máximo 50 identificadores. Cada um tem 1-40 letras, dígitos, espaços ou _ + = . @ -.

Com --federation=oidc o gerador adiciona estes arquivos e edições para o seu provedor iac selecionado:

  • Directorypackages/common/constructs/src/core
    • oidc-identity-providers.ts O construct OidcIdentityProviders, suas props e a validação
    • index.ts Agora exporta oidc-identity-providers.ts
    • user-identity.ts Agora tem a prop oidcIdentityProviders e cria os provedores de identidade

As edições permitem que o web client do user pool, o app client do Cognito através do qual seu website faz login, aceite os provedores de identidade:

packages/common/constructs/src/core/user-identity.ts
import {
OidcIdentityProviders,
type OidcIdentityProviderProps,
} from './oidc-identity-providers.js';
readonly mfaSecondFactor?: MfaSecondFactor;
/**
* OpenID Connect identity providers users can sign in through, next to the user pool's own sign-in.
* Applies to every website that uses this user pool.
* ...
*/
readonly oidcIdentityProviders?: OidcIdentityProviderProps[];
}
mfaSecondFactor = { sms: true, otp: true },
oidcIdentityProviders = [],
}: UserIdentityProps = {},
this.userPoolDomain = this.createUserPoolDomain(this.userPool);
new OidcIdentityProviders(this, 'OidcIdentityProviders', {
userPool: this.userPool,
userPoolDomain: this.userPoolDomain,
providers: oidcIdentityProviders,
});
this.userPoolClient = this.createUserPoolClient(this.userPool);

UserIdentity cria os provedores de identidade antes do web client, então o web client os lista, seguidos por COGNITO.

O gerador não sobrescreve suas edições nos novos arquivos. Se você alterou user-identity.ts, ou main.tf ou identity.tf, de modo que o gerador não os reconheça mais, o gerador deixa esses arquivos inalterados. Ele ainda adiciona os novos arquivos e imprime as linhas para adicionar manualmente.

O deploy que adiciona um provedor de identidade lê seu client secret do Secrets Manager. Se o secret não existir, o deploy falha.

O CloudFormation lê o secret com a função de execução da stack, por padrão cdk-hnb659fds-cfn-exec-role-<account>-<region>. Essa função precisa de secretsmanager:GetSecretValue no secret, mais kms:Decrypt na chave se o secret estiver criptografado com uma chave AWS KMS gerenciada pelo cliente.

Siga estas etapas nesta ordem. O gerador também as imprime quando termina.

  1. Execute ts#website#auth com --federation=oidc, e faça o deploy uma vez.
  2. Encontre o URI de redirecionamento do seu user pool. Todos os provedores de identidade do pool usam o mesmo.

A stack que contém UserIdentity tem uma saída cuja chave começa com <id>OidcIdentityProvidersIdpRedirectUri, onde <id> é o ID do construct que você deu a UserIdentity, por exemplo IdentityOidcIdentityProvidersIdpRedirectUri. Você também pode calculá-lo antes de fazer o deploy, a partir do cognitoDomain que você escolheu para ts#website#auth, seu ID de conta AWS e sua região:

https://<cognitoDomain>-<account>.auth.<region>.amazoncognito.com/oauth2/idpresponse
  1. Registre uma aplicação no provedor de identidade com aquele URI de redirecionamento, e anote seu client ID e client secret. Registre apenas este URI /oauth2/idpresponse no provedor de identidade. As URLs do seu próprio website são registradas com o Cognito, não com o provedor de identidade.

  2. Armazene o client secret no Secrets Manager. Passe-o em um arquivo, não como um argumento de linha de comando. Um argumento permanece no histórico do seu shell, e outros usuários do mesmo computador podem vê-lo na lista de processos enquanto o comando é executado:

    Janela do terminal
    (
    umask 077
    d=$(mktemp -d) || exit
    trap 'rm -rf "$d"' EXIT
    trap 'exit 1' HUP INT TERM
    unset CLIENT_SECRET
    IFS= read -rs CLIENT_SECRET || exit 1
    printf '%s' "$CLIENT_SECRET" > "$d/secret" || exit 1
    unset CLIENT_SECRET
    aws secretsmanager create-secret --name okta-oidc-client-secret --secret-string "file://$d/secret" --region <region>
    )

    Os comandos são executados em um subshell, entre os parênteses. read espera que você cole o client secret e pressione Enter, e não o mostra. Os dois comandos unset mantêm o secret fora do ambiente do comando aws, mesmo se você exportou CLIENT_SECRET anteriormente. IFS= e -r mantêm o secret exatamente como você o cola, incluindo espaços em ambas as extremidades e barras invertidas. mktemp -d cria um novo diretório que apenas você pode abrir (modo 700), e printf escreve o secret nele sem uma nova linha no final. A AWS CLI lê o valor de --secret-string do arquivo nomeado após file:// e o passa inalterado, então uma nova linha no final do arquivo se tornaria parte do secret. Quando o subshell termina, os comandos trap excluem o diretório. Eles também fazem isso se o comando aws falhar ou você pressionar Ctrl-C. Os comandos funcionam em bash e zsh, os shells padrão no Linux e macOS. Para Windows, consulte Mitigate the risks of using the AWS CLI to store your AWS Secrets Manager secrets.

    Defina --region para a região da sua stack. O secret deve existir nessa região antes do deploy que adiciona o provedor de identidade. Armazene o secret como uma string simples, não JSON, porque o Cognito recebe o valor inteiro do secret como o client secret. No console do Secrets Manager, escolha Plaintext, não Key/value.

  3. Adicione o provedor de identidade à lista, com o nome do secret como clientSecretName (client_secret_name no Terraform), conforme Adicionar provedores de identidade mostra. Então faça o deploy.

O user pool gerado requer os atributos email, given_name e family_name. O Cognito os preenche a partir das claims do provedor de identidade em cada login. Se o provedor de identidade não enviar um deles, o primeiro login do usuário falha. UserIdentity e a variável Terraform, portanto, recusam um mapeamento de atributos que deixe de fora qualquer um dos três.

attributeMapping (attribute_mapping no Terraform) mapeia atributos do user pool para claims. Cada chave é um atributo do user pool, e cada valor é o nome da claim do provedor de identidade, com 1-128 caracteres de comprimento. Um mapeamento que você fornece substitui o padrão. O padrão mapeia cada atributo obrigatório para a claim com o mesmo nome:

attributeMapping: { email: 'email', given_name: 'given_name', family_name: 'family_name' },
  • Uma chave pode ser qualquer atributo padrão, como name ou phone_number, phone_number_verified, ou um atributo personalizado como custom:department (até 20 letras, dígitos ou underscores após custom:). As chaves usam os nomes de atributos do Cognito tanto no CDK quanto no Terraform. username é recusado.
  • O Cognito trata um endereço de email mapeado como não verificado. Mapeie email_verified apenas de um provedor de identidade que verifica endereços de email por si só. Caso contrário, um usuário poderia definir o endereço de outra pessoa no provedor de identidade e tê-lo marcado como verificado no seu pool.
  • Se o endereço de email de um usuário mudar no provedor de identidade, o Cognito escreve o novo endereço no user pool no próximo login do usuário. email_verified permanece false.
  • Um atributo personalizado já deve existir no user pool, e deve ser mutável.

O recurso do provedor de identidade Terraform, em identity/oidc-identity-providers.tf, também define dois valores que o Cognito adiciona quando retorna o provedor de identidade: username = "sub" em attribute_mapping e attributes_url_add_attributes = "false" em provider_details. Como o arquivo os define, um segundo terraform plan após o primeiro deploy não mostra nenhuma alteração no provedor de identidade. Se um segundo plan ainda mostrar uma alteração em provider_details com outro provedor de identidade, adicione essa chave ao arquivo com o valor que o plan mostra o Cognito retornando.

As configurações abaixo vêm da documentação de cada fornecedor. Okta foi testado na AWS com CDK e Terraform. As configurações de Auth0 e Microsoft Entra ID foram verificadas contra o documento de descoberta OpenID publicado por cada fornecedor, mas não com um login ao vivo.

Testado na AWS com CDK e Terraform. Crie uma OIDC Web Application no Okta, com o Authorization Code grant e um client secret. Defina seu URI de redirecionamento de login para o URI de redirecionamento /oauth2/idpresponse da etapa 2 de Configurar seu provedor de identidade. Ele não precisa de URI de redirecionamento de logout. O issuer é seu domínio Okta, https://<your-org>.okta.com, que é a forma que foi testada. Um servidor de autorização personalizado, como https://<your-org>.okta.com/oauth2/default, também tem um issuer, mas essa forma não foi testada. Os escopos padrão, openid email profile, retornam email, given_name e family_name, então o mapeamento padrão funciona. Cada usuário precisa de um email, um primeiro nome e um sobrenome definidos no Okta. Atribua a aplicação apenas aos usuários ou grupos que precisam de acesso.

Verificado contra o documento de descoberta do Auth0, não testado com um login ao vivo. Crie uma Regular Web Application no Auth0. O issuer é https://<your-tenant>.auth0.com/, incluindo a barra final.

O Auth0 retorna given_name e family_name apenas quando a conexão do usuário os fornece. Usuários de uma conexão sem eles não podem fazer login até que você mapeie outras claims.

Verificado contra o documento de descoberta da Microsoft, não testado com um login ao vivo. Registre uma aplicação single-tenant no Entra ID. O issuer é https://login.microsoftonline.com/<tenant-id>/v2.0. O código fornecido recusa os issuers multi-tenant (common, organizations e consumers), porque eles aceitam usuários de qualquer tenant do Entra ID. Ele também recusa o tenant 9188040d-6c67-4c5b-b112-36a304b66dad, que aceita qualquer conta pessoal da Microsoft.

O issuer não deve terminar com uma barra: use /v2.0, não /v2.0/. A claim iss nos tokens do Entra ID não tem barra, então o login falharia. O código fornecido recusa a forma com a barra.

Adicione email, given_name e family_name como claims opcionais ao token ID da aplicação. O Entra ID os envia apenas se você fizer isso. Cada usuário precisa ter o campo Mail definido. Caso contrário, a claim email fica vazia, e o primeiro login do usuário falha, porque o user pool requer email. A claim email do Entra ID não é verificada, então não mapeie email_verified do Entra ID.

Para testar com outro user pool do Cognito como provedor de identidade, use o issuer https://cognito-idp.<region>.amazonaws.com/<user pool id>. Dê ao seu app client um client secret, o authorization code grant e os escopos openid email profile.

  • Identifique usuários pela claim sub (o ID único do usuário no seu user pool), nunca por email. Um usuário federado é um novo usuário no seu pool com seu próprio sub, mesmo quando seu email corresponde a um usuário local. O código que o plugin gera usa sub.
  • Use um issuer single-tenant. Um issuer multi-tenant permite que usuários de qualquer organização façam login.
  • Remova as URLs de callback http://localhost dos estágios de produção, conforme autenticação de website descreve. A federação não adiciona nenhuma URL de callback.
  • MFA (autenticação multifator) exigida no seu user pool não se aplica a usuários federados. O Cognito deixa sua autenticação para o provedor de identidade, então imponha MFA no provedor de identidade.

  • Fazer logout do seu website encerra apenas a sessão do Cognito. Não encerra a sessão do usuário no provedor de identidade OIDC, então o próximo login através do botão pode ser concluído sem uma senha. Em um computador compartilhado, os usuários também devem fazer logout no provedor de identidade.

  • O menu do usuário mostra o nome de usuário do Cognito. Para um usuário federado, é o nome do provedor de identidade, um underscore e o sub do usuário no provedor de identidade, em minúsculas, por exemplo okta_00u1abcd.

  • Remover ou desabilitar um usuário no provedor de identidade interrompe apenas o próximo login dele através dele. O Cognito renova tokens com seu próprio refresh token e não pergunta ao provedor de identidade, e o website renova tokens sem que o usuário perceba. O usuário pode, portanto, manter o acesso até que o refresh token expire, até 30 dias após seu último login. Para impedir que o usuário obtenha novos tokens, também desconecte-o de todas as sessões e desabilite-o no user pool. Seu nome de usuário é <identity provider name in lowercase>_<sub>:

    Janela do terminal
    aws cognito-idp admin-user-global-sign-out --user-pool-id <user pool id> --username okta_<sub>
    aws cognito-idp admin-disable-user --user-pool-id <user pool id> --username okta_<sub>

    Isso foi testado na AWS. Após admin-user-global-sign-out e admin-disable-user, o provedor de identidade ainda faz o login do usuário, mas o Cognito os recusa.

    Esses comandos não encerram o acesso que o usuário já tem. admin-user-global-sign-out revoga os refresh tokens do usuário, então o website não pode obter novos tokens para eles, e admin-disable-user interrompe o próximo login deles. Tokens de ID e acesso que o Cognito já emitiu permanecem válidos até expirarem, por padrão uma hora após terem sido emitidos (validade de token de ID e acesso). As credenciais AWS que o identity pool já forneceu ao website também permanecem válidas até expirarem, uma hora após terem sido emitidas (fluxo de autenticação de identity pools). Até que expirem, o usuário ainda pode usar o website e a função autenticada do identity pool.

    Uma validade de refresh token mais curta no web client (refreshTokenValidity no CDK, refresh_token_validity no Terraform) reduz o tempo que um usuário removido mantém o acesso se você não executar esses comandos. Uma validade de token de ID e acesso mais curta (idTokenValidity e accessTokenValidity no CDK, id_token_validity e access_token_validity no Terraform) reduz o tempo que os tokens já emitidos permanecem válidos após você executar os comandos, mas sempre resta algum tempo. Nenhum dos dois foi testado na AWS.

O Cognito mantém o client secret nas configurações do provedor de identidade. Qualquer pessoa autorizada a chamar cognito-idp:DescribeIdentityProvider no seu user pool pode lê-lo. É assim que o Cognito funciona, qualquer que seja o provedor IaC que você use.

O construct passa o secret para o CloudFormation como uma referência dinâmica, {{resolve:secretsmanager:<clientSecretName>:SecretString:::}}. O template sintetizado contém apenas essa referência. O CloudFormation lê o secret quando cria ou atualiza o provedor de identidade. Se você rotacionar o secret, o Cognito obtém o novo valor apenas quando o recurso do provedor de identidade muda em um deploy posterior.

O CloudFormation resolve a referência dentro das configurações do provedor de identidade (ProviderDetails), então o login federado funciona com o secret armazenado, e o template implantado ainda mantém apenas a referência. Após uma rotação, um deploy sem nenhuma outra alteração deixa o secret antigo no Cognito. Ambos foram verificados na AWS.

Para enviar um secret rotacionado ao Cognito:

Altere o recurso do provedor de identidade no deploy que segue a rotação. Uma maneira é armazenar o secret rotacionado sob um novo nome e definir clientSecretName para esse nome. A referência no template então muda, então o CloudFormation atualiza o provedor de identidade e lê o novo secret. Exclua o secret antigo depois. Isso segue a documentação do CloudFormation para referências dinâmicas e não foi testado na AWS.

Um app client é a configuração do Cognito através da qual uma aplicação faz login. O gerador adiciona os provedores de identidade apenas ao app client do website, o web client. Outro app client no mesmo user pool aceita usuários federados apenas se ele também listar os provedores de identidade. Por exemplo, o app client que você cria para um DCR proxy (que permite que clientes MCP, as ferramentas de IA que usam o Model Context Protocol, façam login através do Cognito) precisa deles. Caso contrário, usuários federados não podem fazer login no seu servidor MCP.

Um app client que você cria com identity.userPool.addClient(...) após UserIdentity, sem supportedIdentityProviders, lista todos os provedores de identidade do pool e COGNITO. O exemplo do DCR proxy faz isso. Se seu app client define supportedIdentityProviders, adicione os provedores de identidade do pool a ele:

import { UserPoolClientIdentityProvider } from 'aws-cdk-lib/aws-cognito';
supportedIdentityProviders: [
UserPoolClientIdentityProvider.COGNITO,
...identity.userPool.identityProviders.map((p) =>
UserPoolClientIdentityProvider.custom(p.providerName),
),
],

O target <agent>-chat de um agente TypeScript com autenticação Cognito lê um access token do Cognito da variável de ambiente AGENT_ACCESS_TOKEN. Um usuário federado não tem senha do Cognito, então admin-initiate-auth não funciona para eles. Em vez disso, faça login no seu website, abra as ferramentas de desenvolvedor do navegador e copie access_token da entrada oidc.user:... no session storage.