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 qualquer cliente de aplicativo IDs ou segredos para que somente aplicativos clientes autorizados 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.

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. Login gerenciado IdPs, tipos de concessão URLs, retorno de chamada e personalização

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 aplicativo no Amazon Cognito, você pode pré-preencher as opções com base nos tipos de OAuth cliente 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 de aplicativos com segredos de clientes quando você seleciona as opções de aplicativo web tradicional e achine-to-machine aplicativo M para o tipo de aplicativo. Escolha uma dessas opções para gerar um segredo do cliente ou crie o cliente programaticamente com CreateUserPoolCliente GenerateSecret defina como. true

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 do aplicativo Amazon Cognito podem emitir tokens web JSON (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 pela versão 2.0. OAuth 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 2.0. OAuth 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 Como entender o token de atualização para obter mais informações.

Você pode definir a expiração desses tokens para cada cliente do aplicativo no menu Clientes do aplicativo do seu 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.

Retorno de chamada permitido URLs

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 - endpoint de redirecionamento.

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

Também há suporte para retornos de chamadas de aplicativos, URLs como myapp://example os do tipo.

Sair permitido URLs

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

Atribuir 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 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. Seu aplicativo pode oferecer suporte à autenticação com nome de usuário e senha, e-mail e mensagem SMS OTPs, autenticadores de chave de acesso, autenticação personalizada com acionadores Lambda e atualização de token. Como melhor prática de segurança, use a autenticação SRP para autenticação de nome de usuário e senha em aplicativos personalizados.

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 APIs 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 de CallbackURLs para seu cliente de aplicação. 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 retornos de chamada URLs 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 retorno de chamada URLs 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 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 seu cliente de aplicativo, você pode gerar links de autorização para o IdP e exibi-los na sua página de login gerenciado. Você pode atribuir vários IdPs, mas deve atribuir pelo menos um. Para obter mais informações sobre o uso externo IdPs, consulteLogin do grupo de usuários com provedores de identidade terceirizados.

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 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.

OAuth tipos de subsídios

Uma OAuth concessão é 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 OAuth concessões ao seu aplicativo, você deve adicionar um domínio ao seu 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 OAuth fluxo, como a concessão implícita, acontece nos navegadores dos seus 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 melhor prática de segurança em aplicativos de clientes públicos, ative somente o OAuth fluxo de concessão do 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 APIs com servidores de recursos.

As concessões de credenciais do cliente adicionam custos à sua AWS fatura. Para mais informações, consulte Preço 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. Ambas as opções solicitam que você configure um cliente de aplicativo com configurações específicas do aplicativo.

4. Escolha um tipo de aplicativo que reflita a arquitetura do seu aplicativo.

5. Nomeie seu aplicativo 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 depois de criar seu cliente de aplicativo.

8. O Amazon Cognito retorna você aos detalhes do cliente do aplicativo. Para acessar o código de exemplo do seu aplicativo, 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 retorno de chamada e saída para evitar que URLs a CLI os trate como arquivos de parâmetros remotos:

--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