Clientes de aplicações de grupos de usuários

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 seu aplicativo para assinar solicitações de API autenticadas com AWS credenciais, deverá protegê-las contra a 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.

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.

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

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 usar o token de ID Para 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 usar o token de acesso Para 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 Como usar o token de atualização Para mais informações.

É possível definir a expiração desses tokens para cada cliente de aplicação na guia Integração 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

Seu grupo de usuários pode ter muitos clientes, cada um com seu próprio cliente de aplicativo IdPs e. 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 machine-to-machine (M2M), você não pode conceder acesso a nenhum dos seus 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 aplicativo 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, senha remota segura (SRP), autenticação personalizada com acionadores do Lambda e atualização de token. Como prática recomendada de segurança, use a autenticação SRP como principal método de login. A interface de usuário hospedada conecta automaticamente os usuários com o SRP.

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/scope. Consulte Escopos, M2M e autorização de API com servidores de recursos.

URI de redirecionamento padrão

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

1. Seu cliente de aplicativo tem um provedor de identidade 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 aplicativo tem um provedor de identidade atribuído e um URL de retorno de chamada definido. Nesse cenário, não é necessário definir uma URL de retorno de chamada padrão. Solicitações que não incluem um redirect_uri parâmetro redirecionam para o único URL de retorno de chamada disponível.

Provedores de identidade

Você pode escolher alguns ou todos os provedores de identidade externos (IdPs) do seu grupo de usuários para autenticar seus 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-lo na página de login da interface de usuário hospedada. Você pode atribuir vários IdPs, mas deve atribuir pelo menos um. Para obter mais informações sobre o uso externo IdPs, consulteComo adicionar acesso a grupo de usuários por meio 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 do 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 aws.cognito.signin.user.admin escopo concede acesso às operações de API dos grupos de usuários do Amazon Cognito que exigem tokens de acesso, como e. UpdateUserAttributesVerifyUserAttribute

• 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 do cliente é para comunicações machine-to-machine (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 autorização de API com servidores de recursos.

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

Criar um cliente de aplicação

AWS Management Console

Para criar um cliente de aplicação (console)

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

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.

4. Selecione a guia App integration (Integração da aplicação).

5. Em App clients (Clientes da aplicação), selecione Create an app client (Criar um cliente da aplicação).

6. Selecione um App type (Tipo de aplicação): Public client (Cliente público), Confidential client (Cliente confidencial) ou Other (Outro).

7. Insira um App client name (Nome do cliente da aplicação).

8. Selecione Gerar segredo do cliente para que o Amazon Cognito gere um segredo do cliente para você. Normalmente segredos dos clientes são associados a clientes confidenciais.

9. Selecione os Authentication flows (Fluxos de autenticação) que deseja permitir no cliente da aplicação.

10. Configure a Authentication flow session duration (Duração da sessão do fluxo de autenticação). Esse é o tempo que os usuários têm para concluir cada desafio de autenticação antes que o token da sessão expire.

11. (Opcional) Se desejar configurar a validade do token, conclua as etapas a seguir:

    1. Especifique a Refresh token expiration (Validade do token de atualização) para o cliente da aplicação. O valor padrão é de 30 dias. Você pode alterá-la para qualquer valor entre 1 hora e 10 anos.

    2. Especifique a Access token expiration (Validade do token de acesso) para o cliente da aplicação. O valor padrão é uma hora. Você pode alterá-la para qualquer valor entre 5 minutos e 24 horas.

    3. Especifique ID token expiration (Validade do token de ID) para o cliente da aplicação. O valor padrão é uma hora. Você pode alterá-la para qualquer valor entre 5 minutos e 24 horas.

       Importante

       Se você usar a interface do usuário hospedada e definir o ciclo de vida do token para menos de uma hora, o usuário será capaz de usar tokens com base na duração do cookie de sessão, que atualmente está fixada em uma hora.

12. Escolha se você vai Enable token revocation (Habilitar revogação de token) para esse cliente da aplicação. Isso aumentará o tamanho dos tokens que o Amazon Cognito emite.

13. Selecione se você vai Evitar mensagens de erro que revelem a existência do usuário para esse cliente de aplicativo. O Amazon Cognito responderá a solicitações de acesso para usuários inexistentes com uma mensagem genérica informando que o nome de usuário ou a senha estavam incorretos.

14. Se você quiser usar a interface de usuário hospedada com esse cliente de aplicativo, defina as configurações da interface do usuário hospedada.

    1. Insira um ou mais URLs de retorno de chamada permitidos. Esses são os URLs da web ou do aplicativo para os quais você deseja que o Amazon Cognito redirecione seus usuários depois que eles concluírem a autenticação.

    2. Insira um ou mais URLs de saída permitidos. Esses são os URLs que você deseja que seu aplicativo aceite em solicitações para o Endpoint de logout.

    3. Escolha um ou mais provedores de identidade nos quais você deseja conectar usuários ao seu aplicativo. Você pode escolher qualquer combinação existente IdPs. Você pode autenticar usuários somente com seu grupo de usuários ou com um ou mais terceiros IdPs que você configurou em seu grupo de usuários.

    4. Selecione os tipos de concessão do OAuth 2.0 que você deseja que seu cliente de aplicativo aceite.

       • Selecione Concessão do código de autorização para transmitir códigos para seu aplicativo que ele possa trocar por tokens com o Endpoint de token.

       • Selecione Concessão implícita para passar o ID e acessar os tokens diretamente ao seu aplicativo. O fluxo de concessão implícito expõe os tokens diretamente aos seus usuários.

       • Selecione Credenciais do cliente para passar tokens de acesso ao seu aplicativo com base em seu conhecimento, não das credenciais do usuário, mas do segredo do cliente. O fluxo de concessão de credenciais do cliente é mutuamente exclusivo com código de autorização e fluxos de concessão implícitos.

    5. Selecione os Escopos do OpenID Connect que deseja autorizar para esse cliente de aplicativo. Você pode gerar tokens de acesso somente com o escopo aws.cognito.signin.user.admin por meio da API de grupos de usuários. Para escopos adicionais, você deve solicitar seus tokens de acesso ao Endpoint de token.

    6. Selecione os escopos personalizados que você deseja autorizar com seu cliente de aplicativo. Os escopos personalizados são usados com mais frequência para autorizar o acesso a APIs de terceiro.

15. Defina as Permissões de leitura e gravação de atributos para esse cliente de aplicativo. Seu cliente de aplicativo pode ter permissão para leitura e gravação de tudo ou um subconjunto limitado do esquema de atributos do seu grupo de usuários.

16. Escolha Criar cliente da aplicação.

17. Anote o Client id (ID do cliente). Isso identificará o cliente da aplicação nas solicitações de cadastro e acesso.

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 do AWS CLI comando para obter mais informações: create-user-pool-client

Amazon Cognito user pools API

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

Atualização de um cliente de aplicativo de grupo de usuários (AWS CLI e AWS API)

No AWS CLI, digite 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, ele 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 do AWS CLI comando para obter mais informações: update-user-pool-client.

AWS API: UpdateUserPoolClient

Obter informações sobre um cliente de aplicativo de grupo de usuários (AWS CLI e AWS API)

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

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

AWS API: DescribeUserPoolClient

Listar todas as informações do cliente do aplicativo em um grupo de usuários (AWS CLI e AWS API)

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

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

AWS API: ListUserPoolClients

Excluindo um cliente de aplicativo de grupo de usuários (AWS CLI e AWS API)

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

Consulte a referência do AWS CLI comando para obter mais informações: delete-user-pool-client

AWS API: DeleteUserPoolClient