Configurações específicas da aplicação com clientes de aplicação - Amazon Cognito
Tipos de cliente de aplicaçãoToken JSON da webTermos do cliente da aplicaçãoCriar um cliente de aplicaçãoAtualizar um cliente da aplicação do grupo de usuários (AWS CLI e API da AWS)Como obter informações sobre um cliente da aplicação do grupo de usuários (AWS CLI e API da AWS)Como listar todas as informações de um cliente da aplicação em um grupo de usuários (AWS CLI e API da AWS)Como excluir um cliente de aplicação do grupo de usuários (AWS CLI e API da AWS)

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Configurações específicas da aplicação com clientes de aplicação

Um cliente de aplicação de grupo de usuários é uma configuração dentro de um grupo de usuários que interage com um aplicativo móvel ou uma aplicação web que se autentica no Amazon Cognito. Os clientes da aplicação podem chamar operações de API autenticadas e não autenticadas e ler ou modificar alguns ou todos os atributos dos usuários. A aplicação deve se identificar com o respectivo cliente nas operações de registro, login e tratamento de senhas esquecidas. Essas solicitações de API devem incluir autoidentificação com um ID do cliente da aplicação e autorização com um segredo opcional do cliente. Você deve proteger todos os IDs ou segredos do cliente da aplicação para que somente as aplicações clientes autorizadas possam chamar essas operações não autenticadas. Além disso, se você configurar a aplicação para assinar solicitações de API autenticadas com credenciais da AWS, deverá proteger suas credenciais contra inspeção do usuário.

É possível criar várias aplicações para um grupo de usuários. Um cliente da aplicação pode estar vinculado à plataforma de código de uma aplicação ou a um locatário separado no grupo de usuários. Por exemplo, você pode criar uma aplicação para uma aplicação do lado do servidor e uma aplicação Android diferente. Cada aplicativo possui o seu próprio ID de cliente do aplicativo.

Você pode aplicar configurações para os seguintes recursos do grupo de usuários no nível do cliente de aplicação:

  1. Analytics

  2. IdPs, tipos de concessão, URLs de retorno de chamada e personalização de login gerenciado

  3. Servidores de recursos e escopos personalizados

  4. Proteção contra ameaças

  5. Atribuir permissões de leitura e gravação

  6. Expiração e revogação do token

  7. Fluxos de autenticação

Tipos de cliente de aplicação

Ao criar um cliente de aplicação no Amazon Cognito, você pode preencher as opções previamente com base nos tipos de cliente OAuth padrão cliente público e cliente confidencial. Configure um cliente confidencial com um segredo do cliente. Para obter mais informações sobre os tipos de clientes, consulte IETF RFC 6749 #2.1.

Cliente público

Um cliente público é executado em um navegador ou em um dispositivo móvel. Como ele não tem recursos confiáveis no lado do servidor, não tem um segredo do cliente.

Cliente confidencial

Um cliente confidencial tem recursos no lado do servidor que podem ser confiáveis com um segredo do cliente para operações de API não autenticadas. A aplicação pode ser executada como um daemon ou script shell no servidor de backend.

Segredo do cliente

Um segredo do cliente, ou senha do cliente, é uma string fixa que a aplicação deve usar em todas as solicitações de API para o cliente da aplicação. O cliente da aplicação deve ter um segredo de cliente para realizar concessões client_credentials. Para obter mais informações, consulte IETF RFC 6749 #2.3.1.

Você não pode alterar os segredos depois de criar uma aplicação. É possível criar uma aplicação com um novo segredo se você quiser alternar o segredo. Também é possível excluir um aplicativo para bloquear o acesso de aplicativos que usam esse ID de cliente de aplicativo.

nota

O console do Amazon Cognito cria clientes da aplicação com segredos do cliente quando você seleciona as opções Aplicação Web tradicional e Aplicação máquina-a-máquina para o tipo de aplicação. Escolha uma dessas opções para gerar um segredo do cliente ou crie o cliente programaticamente com CreateUserPoolClient e defina GenerateSecret como true.

Você pode usar um cliente confidencial e um segredo do cliente com uma aplicação pública. Use um proxy do Amazon CloudFront para adicionar um SECRET_HASH em trânsito. Para obter mais informações, consulte Proteja clientes públicos para o Amazon Cognito usando um proxy do Amazon CloudFront, no blog da AWS.

Token JSON da web

Os clientes da aplicação do Amazon Cognito podem emitir tokens JSON da web (JWTs) dos seguintes tipos.

Token de identidade (ID)

Uma declaração verificável de que o usuário está autenticado no grupo de usuários. O OpenID Connect (OIDC) adicionou a especificação do token de ID aos padrões de token de acesso e atualização definidos pelo OAuth 2.0. O token de ID contém informações de identidade, como atributos do usuário, que a aplicação pode usar para criar um perfil de usuário e provisionar recursos. Consulte Como entender o token de identidade (ID) para obter mais informações.

Token de acesso

Uma declaração verificável dos direitos de acesso do usuário. O token de acesso contém escopos, um recurso do OIDC e do OAuth 2.0. A aplicação pode apresentar escopos para recursos de back-end e provar que o grupo de usuários autorizou um usuário ou uma máquina a acessar dados de uma API ou seus próprios dados de usuário. Um token de acesso com escopos personalizados, geralmente de uma concessão de credenciais de cliente M2M, autoriza o acesso a um servidor de recursos. Consulte Como entender o token de acesso para obter mais informações.

Token de atualização

Uma declaração criptografada da autenticação inicial que a aplicação pode apresentar ao grupo de usuários quando os tokens do usuário expirarem. Uma solicitação de token de atualização retorna tokens de acesso e ID novos e não expirados. Consulte Tokens de atualização para obter mais informações.

É possível definir a expiração desses tokens para cada cliente da aplicação no menu Clientes da aplicação do grupo de usuários no console do Amazon Cognito.

Termos do cliente da aplicação

Os seguintes termos são propriedades disponíveis para clientes da aplicação no console do Amazon Cognito.

URLs de retorno de chamada permitidos

Um URL de retorno de chamada indica para onde o usuário será redirecionado após um acesso bem-sucedido. Escolha pelo menos um URL de retorno de chamada. O URL de retorno de chamada deve:

  • Ser um URI absoluto.

  • Estar pré-registrado com um cliente.

  • Não incluir um componente de fragmento.

Consulte OAuth 2.0 - redirection endpoint (OAuth 2.0 - endpoint de redirecionamento).

O Amazon Cognito exige HTTPS em vez de HTTP, exceto http://localhost somente para fins de teste.

URLs de retorno de chamada do aplicativo, como myapp://example, também são compatíveis.

URLs de desconexão permitidos

Um URL de saída indica para onde o usuário deve ser redirecionado após fazer logoff.

Atribua permissões de leitura e gravação

O grupo de usuários pode ter muitos clientes, cada um com seu próprio cliente de aplicação e IdPs. Você pode configurar o cliente da aplicação para ter acesso de leitura e gravação somente aos atributos de usuário relevantes para a aplicação. Em casos como autorização entre máquinas (M2M), você não pode conceder acesso a nenhum dos atributos de usuário.

Considerações sobre a configuração de permissões de leitura e gravação de atributos

  • Quando você cria um cliente de aplicação e não personaliza as permissões de leitura e gravação de atributos, o Amazon Cognito concede permissões de leitura e gravação a todos os atributos do grupo de usuários.

  • É possível conceder acesso de gravação a atributos personalizados imutáveis. O cliente da aplicação pode gravar valores em um atributo imutável quando você cria ou cadastra um usuário. Depois disso, não é possível gravar valores em nenhum atributo personalizado imutável para o usuário.

  • Os clientes da aplicação devem ter acesso de gravação aos atributos necessários em seu grupo de usuários. O console do Amazon Cognito define automaticamente os atributos necessários como graváveis.

  • Não é possível permitir que um cliente de aplicação tenha acesso de gravação a email_verified ou phone_number_verified. O administrador do grupo de usuários pode modificar esses valores. Um usuário só pode alterar o valor desses atributos por meio da verificação de atributos.

Fluxos de autenticação

Os métodos que o cliente da aplicação permite para fazer login. A aplicação pode permitir a autenticação com nome de usuário e senha, OTPs por e-mail e SMS, autenticadores de chave de acesso, autenticação personalizada com acionadores do Lambda e atualização de token. Como prática recomendada de segurança, use a autenticação SRP para autenticação de nome de usuário e senha em aplicações personalizadas.

Escopos personalizados

Um escopo personalizado é aquele definido para o seu próprio servidor de recursos em Resource Servers (Servidores de recursos). O formato é resource-server-identifier/escopo. Consulte Escopos, M2M e servidores de recursos.

URI de redirecionamento padrão

Substitui o parâmetro redirect_uri nas solicitações de autenticação para usuários com IdPs de terceiros. Defina essa configuração do cliente de aplicação com o parâmetro DefaultRedirectURI de uma solicitação da API CreateUserPoolClient ou UpdateUserPoolClient. Esse URL também deve ser membro de CallbackURLs para seu cliente de aplicação. O Amazon Cognito redireciona as sessões autenticadas para esse URL quando:

  1. Seu cliente de aplicação tem um provedor de identidades atribuído e vários URLs de retorno de chamada definidos. Seu grupo de usuários redireciona as solicitações de autenticação para o servidor de autorização para o URI de redirecionamento padrão quando elas não incluem um parâmetro redirect_uri.

  2. Seu cliente de aplicação tem um provedor de identidades atribuído e um URL de retorno de chamada definido. Nesse cenário, não é necessário definir um URL de retorno de chamada padrão. Solicitações que não incluem um parâmetro redirect_uri redirecionam para o único URL de retorno de chamada disponível.

Provedores de identidade

Você pode escolher alguns ou todos os provedores de identidades (IdPs) externos do grupo de usuários para autenticar usuários. O cliente da aplicação também pode autenticar apenas usuários locais no grupo de usuários. Ao adicionar um IdP ao cliente da aplicação, é possível gerar links de autorização para o IdP e exibi-los na página de login do login gerenciado. Você pode atribuir vários IdPs, mas deve atribuir pelo menos um. Para obter mais informações sobre o uso de IdPs externos, consulte Login do grupo de usuários com provedores de identidades de terceiros.

Escopos do OpenID Connect

Selecione um ou mais dos seguintes escopos OAuth para especificar os privilégios de acesso que podem ser solicitados para tokens de acesso.

  • O escopo openid declara que você deseja recuperar um token de ID e um ID exclusivo do usuário. Ele também solicita todos ou alguns atributos do usuário, dependendo dos escopos adicionais na solicitação. O Amazon Cognito não retorna um token de ID, a menos que você solicite o escopo openid. O escopo openid autoriza declarações de token de ID estrutural, como expiração e ID da chave, e determina os atributos do usuário que você recebe em uma resposta do endpoint userinfo.

    • Quando openid é o único escopo que você solicita, o Amazon Cognito preenche o token de ID com todos os atributos do usuário que o cliente atual da aplicação pode ler. A resposta userInfo a um token de acesso somente com esse escopo exibe todos os atributos do usuário.

    • Quando você solicita openid com outros escopos, como phone, email ou profile, o token de ID e userInfo exibem o ID exclusivo do usuário e os atributos definidos pelos escopos adicionais.

  • O escopo phone concede acesso às requisições phone_number e phone_number_verified. Esse escopo só pode ser solicitado com o escopo openid.

  • O escopo email concede acesso às requisições email e email_verified. Esse escopo só pode ser solicitado com o escopo openid.

  • O escopo aws.cognito.signin.user.admin concede acesso às operações da API de grupos de usuários do Amazon Cognito que exigem tokens de acesso, como UpdateUserAttributes e VerifyUserAttribute.

  • O escopo profile concede acesso a todos os atributos do usuário que são legíveis pelo cliente. Esse escopo só pode ser solicitado com o escopo openid.

Para obter mais informações sobre os escopos, consulte a lista de escopos OIDC padrão.

Tipos de concessão do OAuth

Uma concessão do OAuth é um método de autenticação que recupera tokens do grupo de usuários. O Amazon Cognito agora é compatível com seguintes tipos de concessões. Para integrar essas concessões do OAuth à aplicação, é necessário adicionar um domínio ao grupo de usuários.

Concessão de código de autorização

A concessão do código de autorização gera um código que a aplicação pode trocar por tokens do grupo de usuários com o Endpoint de token. Quando você troca um código de autorização, a aplicação recebe tokens de ID, acesso e atualização. Esse fluxo do OAuth, como a concessão implícita, acontece nos navegadores dos usuários. Uma concessão de código de autorização é a concessão mais segura que o Amazon Cognito oferece, porque os tokens não são visíveis nas sessões dos usuários. Em vez disso, a aplicação gera a solicitação que retorna tokens e pode armazená-los em cache no armazenamento protegido. Para obter mais informações, consulte Authorization code no IETF RFC 6749 #1.3.1.

nota

Como prática recomendada de segurança em aplicações de clientes públicos, ative somente o fluxo OAuth de concessão de código de autorização e implemente o Proof Key for Code Exchange (PKCE) para restringir a troca de tokens. Com o PKCE, um cliente só pode trocar um código de autorização depois de fornecer ao endpoint do token o mesmo segredo apresentado na solicitação de autenticação original. Para obter mais informações sobre PKCE, consulte IETF RFC 7636.

Concessão implícita

A concessão implícita fornece um token de acesso e ID, mas não um token de atualização, à sessão do navegador do usuário diretamente do Autorizar endpoint. Uma concessão implícita remove a exigência de uma solicitação separada para o endpoint do token, mas não é compatível com o PKCE e não retorna tokens de atualização. Essa concessão acomoda cenários de teste e arquitetura de aplicação que não podem concluir concessões de código de autorização. Para obter mais informações, consulte Implicit grant em IETF RFC 6749 #1.3.2. É possível ativar tanto a concessão de código de autorização como a concessão implícita em um cliente da aplicação e usar cada concessão conforme necessário.

Concessão de credenciais do cliente

A concessão de credenciais de cliente destina-se a comunicações entre máquinas (M2M). O código de autorização e as concessões implícitas emitem tokens para usuários humanos autenticados. As credenciais do cliente concedem autorização baseada em escopo de um sistema não interativo para uma API. A aplicação pode solicitar credenciais do cliente diretamente do endpoint do token e receber um token de acesso. Para obter mais informações, consulte Client Credentials em IETF RFC 6749 #1.3.4. Você só pode ativar concessões de credenciais de cliente em clientes de aplicações que tenham um segredo de cliente e que não permitam códigos de autorização ou concessões implícitas.

nota

Como você não invoca o fluxo de credenciais do cliente como usuário, essa concessão só pode adicionar escopos personalizados a tokens de acesso. Um escopo personalizado é aquele definido para o seu próprio servidor de recursos. Os escopos-padrão, como openid e profile, não se aplicam a usuários não humanos.

Como os tokens de ID são uma validação dos atributos do usuário, eles não são relevantes para a comunicação M2M, e as concessões de credenciais de um cliente não os emitem. Consulte Escopos, M2M e servidores de recursos.

As concessões de credenciais do cliente adicionam custos à sua fatura da AWS. Para mais informações, consulte Preço do Amazon Cognito.

Criar um cliente de aplicação

Console de gerenciamento da AWS
Para criar um cliente de aplicação (console)

  1. Acesse o console do Amazon Cognito. Se solicitado, insira suas credenciais da AWS.

  2. Escolha User Pools (Grupos de usuários).

  3. Escolha um grupo de usuários existente na lista ou crie um grupo de usuários. Ambas as opções solicitam que você configure um cliente da aplicação com configurações específicas da aplicação.

  4. Selecione um Tipo de aplicação que reflita a arquitetura da aplicação.

  5. Dê um nome para sua aplicação com um identificador amigável.

  6. Insira um URL de retorno.

  7. Escolha Criar cliente da aplicação. Você pode alterar as opções avançadas após criar o cliente da aplicação.

  8. O Amazon Cognito retorna você aos detalhes do cliente da aplicação. Para acessar o código de exemplo da sua aplicação, selecione uma plataforma na guia Guia de configuração rápida.

AWS CLI
aws cognito-idp create-user-pool-client --user-pool-id MyUserPoolID --client-name myApp
nota

Use o formato JSON para URLs de saída e de retorno de chamada para impedir que a CLI trate-os como arquivos parâmetro remoto:

--callback-urls "["https://example.com"]"
--logout-urls "["https://example.com"]"

Consulte a referência de comandos da AWS CLI para obter mais informações: create-user-pool-client.

Amazon Cognito user pools API

Gere uma solicitação de API CreateUserPoolClient. Você deve especificar um valor para todos os parâmetros que não deseja definir como padrão.

Atualizar um cliente da aplicação do grupo de usuários (AWS CLI e API da AWS)

Na AWS CLI, insira o seguinte comando:

aws cognito-idp update-user-pool-client --user-pool-id  "MyUserPoolID" --client-id "MyAppClientID" --allowed-o-auth-flows-user-pool-client --allowed-o-auth-flows "code" "implicit" --allowed-o-auth-scopes "openid" --callback-urls "["https://example.com"]" --supported-identity-providers "["MySAMLIdP", "LoginWithAmazon"]"

Se o comando for bem-sucedido, a AWS CLI retornará uma confirmação:

{
    "UserPoolClient": {
        "ClientId": "MyClientID",
        "SupportedIdentityProviders": [
            "LoginWithAmazon",
            "MySAMLIdP"
        ],
        "CallbackURLs": [
            "https://example.com"
        ],
        "AllowedOAuthScopes": [
            "openid"
        ],
        "ClientName": "Example",
        "AllowedOAuthFlows": [
            "implicit",
            "code"
        ],
        "RefreshTokenValidity": 30,
        "AuthSessionValidity": 3,
        "CreationDate": 1524628110.29,
        "AllowedOAuthFlowsUserPoolClient": true,
        "UserPoolId": "MyUserPoolID",
        "LastModifiedDate": 1530055177.553
    }
}

Consulte a referência de comandos da AWS CLI para obter mais informações: update-user-pool-client.

API da AWS: UpdateUserPoolClient

Como obter informações sobre um cliente da aplicação do grupo de usuários (AWS CLI e API da AWS)

aws cognito-idp describe-user-pool-client --user-pool-id MyUserPoolID --client-id MyClientID

Consulte a referência de comandos da AWS CLI para obter mais informações: describe-user-pool-client.

API da AWS: DescribeUserPoolClient

Como listar todas as informações de um cliente da aplicação em um grupo de usuários (AWS CLI e API da AWS)

aws cognito-idp list-user-pool-clients --user-pool-id "MyUserPoolID" --max-results 3

Consulte a referência de comandos da AWS CLI para obter mais informações: list-user-pool-clients.

API da AWS: ListUserPoolClients

Como excluir um cliente de aplicação do grupo de usuários (AWS CLI e API da AWS)

aws cognito-idp delete-user-pool-client --user-pool-id "MyUserPoolID" --client-id "MyAppClientID"

Consulte a referência de comandos da AWS CLI para obter mais informações: delete-user-pool-client.

AWS API: DeleteUserPoolClient