Escopos, M2M e APIs com servidores de recursos - Amazon Cognito
Autorização da APIAutorização de máquina a máquina (M2M)Sobre escoposSobre servidores de recursos

Escopos, M2M e APIs com servidores de recursos

Depois de configurar um domínio para o grupo de usuários, o Amazon Cognito fornecerá automaticamente um servidor de autorização do OAuth 2.0 e uma interface de usuário da web hospedada com as páginas de cadastro e login que a aplicação pode apresentar aos usuários. Para ter mais informações, consulte Adicionar um cliente da aplicação com a interface do usuário hospedada. Você pode escolher os escopos que deseja que o servidor de autorização adicione aos tokens de acesso. Os escopos autorizam o acesso aos servidores de recursos e aos dados de usuário.

Um servidor de recursos é um servidor de API do OAuth 2.0. Para proteger recursos protegidos por acesso, ele valida se os tokens de acesso do grupo de usuários contêm os escopos que autorizam o método e o caminho solicitados na API que ele protege. Ele confirma o emissor, com base na assinatura do token, a validade, com base no tempo de expiração do token, e o nível de acesso, com base nos escopos das solicitações de token. Os escopos do grupo de usuários estão na reivindicação scope do token de acesso. Para obter mais informações sobre as reivindicações nos tokens de acesso do Amazon Cognito, consulte Como entender o token de acesso.

Com o Amazon Cognito, os escopos nos tokens de acesso podem autorizar o acesso às APIs externas ou aos atributos do usuário. Você pode emitir tokens de acesso para usuários locais, usuários federados ou identidades de máquinas.

Autorização da API

Veja a seguir algumas maneiras pelas quais você pode autorizar solicitações de APIs com tokens do Amazon Cognito:

Token de acesso

Ao adicionar um autorizador do Amazon Cognito a uma configuração de solicitação de método da API REST, adicione escopos de autorização à configuração do autorizador. Com essa configuração, sua API aceita tokens de acesso no cabeçalho Authorization e analisa os escopos aceitos neles.

Token de ID

Quando você passa um token de ID válido para um autorizador do Amazon Cognito em sua API REST, o API Gateway aceita a solicitação e passa o conteúdo do token de ID para o backend da API.

Amazon Verified Permissions

No Verified Permissions, você tem a opção de criar um repositório de políticas vinculado à API. O Verified Permissions cria e atribui um autorizador Lambda que processa tokens de ID ou de acesso do cabeçalho Authorization da sua solicitação. Esse autorizador Lambda passa seu token para o repositório de políticas, onde o Verified Permissions o compara com as políticas e retorna uma decisão de permissão ou negação ao autorizador.

Mais atributos

Autorização de máquina a máquina (M2M)

O Amazon Cognito aceita aplicações que acessam dados de API com identidades de máquinas. As identidades de máquinas em grupos de usuários são clientes confidenciais executados em servidores de aplicações e se conectam a APIs remotas. Sua operação acontece sem a interação do usuário: tarefas agendadas, fluxos de dados ou atualizações de ativos. Quando esses clientes autorizam suas solicitações com um token de acesso, eles realizam a autorização máquina a máquina, ou M2M. Na autorização M2M, um segredo compartilhado substitui as credenciais do usuário no controle de acesso.

Uma aplicação que acessa uma API com autorização M2M deve ter um ID do cliente e uma chave secreta do cliente. Em seu grupo de usuários, você deve criar um cliente de aplicação que permita a concessão de credenciais de clientes. Para permitir credenciais de cliente, o cliente de aplicação deve ter um segredo, enquanto você deve ter um domínio de grupo de usuários. Nesse fluxo, a identidade da sua máquina solicita um token de acesso diretamente do Endpoint de token. Você pode autorizar somente escopos personalizados de servidores de recursos em tokens de acesso para concessões de credenciais de clientes. Para obter mais informações sobre a configuração de clientes de aplicação, consulte Configurações específicas da aplicação com clientes de aplicação.

O token de acesso de uma concessão de credenciais do cliente é uma declaração verificável das operações que você deseja permitir que a identidade da sua máquina solicite de uma API. Para saber mais sobre como os tokens de acesso autorizam solicitações de API, leia a seguir. Para ver um exemplo de aplicação, consulte Autorização máquina a máquina baseada no Amazon Cognito e no API Gateway usando o CDK da AWS.

A autorização M2M tem um modelo de cobrança que difere da forma como os usuários ativos mensais (MAUs) são cobrados. Quando a autenticação do usuário tem um custo por usuário ativo, a cobrança de M2M reflete as credenciais ativas do cliente, os clientes da aplicação e o volume total de solicitações de tokens. Para mais informações, consulte Preços do Amazon Cognito. Para controlar os custos da autorização M2M, otimize a duração dos tokens de acesso e o número de solicitações de token que as aplicações fazem. Consulte Gerenciar a expiração e o armazenamento em cache do token do grupo de usuários para saber como usar o cache do API Gateway para reduzir as solicitações de novos tokens na autorização M2M.

Para obter informações sobre como otimizar as operações do Amazon Cognito que adicionam custos à fatura da AWS, consulte Gerenciar custos da .

Sobre escopos

Um escopo é um nível de acesso que um aplicativo pode solicitar para um recurso. Em um token de acesso do Amazon Cognito, o escopo é respaldado pela confiança que você configura com o grupo de usuários: um emissor confiável de tokens de acesso com uma assinatura digital conhecida. Os grupos de usuários podem gerar tokens de acesso com escopos que provam que o cliente tem permissão para gerenciar parte ou a totalidade de seu próprio perfil de usuário ou recuperar dados de uma API de back-end. Os grupos de usuários do Amazon Cognito emitem tokens de acesso com o escopo reservado da API dos grupos de usuários, escopos personalizados e escopos do OpenID Connect (OIDC).

O escopo reservado da API do grupo de usuários

O escopo do aws.cognito.signin.user.admin autoriza operações de autoatendimento para o usuário atual na API de grupos de usuários do Amazon Cognito. Ele autoriza o portador de um token de acesso a consultar e atualizar todas as informações sobre o portador com, por exemplo, as operações de API GetUser e UpdateUserAttributes. Quando você autentica o usuário com a API de grupos de usuários do Amazon Cognito, esse é o único escopo que você recebe no token de acesso. Também é o único escopo necessário para ler e gravar atributos de usuário que você autorizou o cliente da aplicação a ler e gravar. Também é possível solicitar esse escopo em solicitações ao Autorizar endpoint. Esse escopo por si só não é suficiente para solicitar atributos de usuário do endpoint userinfo. Para tokens de acesso que autorizam a API de grupos de usuários e solicitações userInfo para os usuários, é necessário solicitar os dois escopos openid e aws.cognito.signin.user.admin em uma solicitação /oauth2/authorize.

Escopos personalizados

Os escopos personalizados autorizam solicitações às APIs externas que os servidores de recursos protegem. Você pode solicitar escopos personalizados com outros tipos de escopos. É possível encontrar mais informações sobre escopos personalizados em toda esta página.

Escopos do OpenID Connect (OIDC)

Ao autenticar usuários com o servidor de autorização do grupo de usuários, inclusive com a interface de usuário hospedada, você deve solicitar escopos. É possível autenticar usuários locais do grupo de usuários e usuários federados de terceiros no servidor de autorização do Amazon Cognito. Os escopos do OIDC autorizam a aplicação a ler as informações de usuário do endpoint userinfo do grupo de usuários. O modelo do OAuth, em que você consulta os atributos do usuário por meio do endpoint userInfo, pode otimizar a aplicação para um alto volume de solicitações de atributos do usuário. O endpoint userInfo retorna atributos em um nível de permissão que é determinado pelos escopos no token de acesso. Você pode autorizar seu cliente de aplicação a emitir tokens de acesso com os seguintes escopos padrão do OIDC.

OpenID

Um escopo mínimo para consultas do OpenID Connect (OIDC). Autoriza o token de ID, a reivindicação de identificador exclusivo sub e a capacidade de solicitar outros escopos.

nota

Quando você solicita o escopo openid e nenhum outro, o token de ID do grupo de usuários e a resposta userInfo incluem declarações para todos os atributos do usuário que o cliente da aplicação pode ler. Quando você solicita openid e outros escopos OIDC, como profile, email e phone, o conteúdo do token de ID e a resposta userInfo são limitados às restrições dos escopos adicionais.

Por exemplo, uma solicitação ao Autorizar endpoint com o parâmetro scope=openid+email retorna um token de ID com sub, email e email_verified. O token de acesso dessa solicitação exibe os mesmos atributos de endpoint userinfo. Uma solicitação com o parâmetro scope=openid exibe todos os atributos legíveis pelo cliente no token de ID e de userInfo.

profile

Autoriza todos os atributos de usuário que o cliente da aplicação pode ler.

email

Autoriza os atributos do usuário email e email_verified. O Amazon Cognito vai gerar email_verified se tiver um valor definido explicitamente.

phone

Autoriza os atributos do usuário phone_number e phone_number_verified.

Sobre servidores de recursos

Uma API do servidor de recursos pode conceder acesso às informações em um banco de dados ou controlar seus recursos de TI. Um token de acesso do Amazon Cognito pode autorizar o acesso a APIs compatíveis com o OAuth 2.0. As APIs REST do Amazon API Gateway têm suporte integrado para autorização com tokens de acesso do Amazon Cognito. A aplicação transmite o token de acesso na chamada de API para o servidor de recursos. O servidor de recursos inspeciona o token de acesso para determinar se o acesso deve ser concedido.

O Amazon Cognito pode fazer futuras atualizações no esquema dos tokens de acesso do grupo de usuários. Se a aplicação analisar o conteúdo do token de acesso antes de passá-lo para uma API, você deverá criar seu código para aceitar atualizações no esquema.

Os escopos personalizados são definidos por você e ampliam os recursos de autorização de um grupo de usuários para incluir propósitos não relacionados à consulta e modificação de usuários e seus atributos. Por exemplo, se você possui um servidor de recursos para fotos, ele pode definir dois escopos: photos.read para acesso de leitura das fotos e photos.write para acesso de gravação/exclusão. É possível configurar uma API para aceitar tokens de acesso para autorização e conceder solicitações HTTP GET para acessar tokens com photos.read na reivindicação scope, e solicitações HTTP POST de tokens com photos.write. Estes são escopos personalizados.

nota

O servidor de recursos deve verificar a assinatura e a data de expiração do token de acesso antes de processar quaisquer reivindicações dentro do token. Para obter mais informações sobre como verificar tokens, consulte Como verificar um token Web JSON. Para obter mais informações sobre como verificar e usar tokens de grupos de usuários no Amazon API Gateway, consulte o blog Integrating Amazon Cognito User Pools with API Gateway. O API Gateway é uma boa opção para inspecionar os tokens de acesso e proteger seus recursos. Para obter mais informações sobre autorizadores do Lambda do API Gateway, consulte Usar os autorizadores do Lambda do API Gateway.

Visão geral

Com o Amazon Cognito, é possível criar Servidores de recursos do OAuth 2.0 e associar Escopos personalizados a eles. Escopos personalizados em um token de acesso autorizam ações específicas na API. Você pode autorizar qualquer cliente de aplicação no grupo de usuários a emitir escopos personalizados de qualquer um dos servidores de recursos. Associe escopos personalizados a um cliente da aplicação e solicite esses escopos nas concessões de código de autorização do OAuth 2.0, nas concessões implícitas e nas concessões de credenciais de cliente do Endpoint de token. O Amazon Cognito adiciona escopos personalizados na reivindicação scope em um token de acesso. Um cliente pode usar o token de acesso em seu servidor de recursos, o que faz com que a decisão de autorização baseada nos escopos esteja presente no token. Para obter mais informações sobre o escopo do token de acesso, consulte Usar tokens com grupos de usuários.

Uma visão geral do fluxo de um servidor de recursos. O cliente solicita uma concessão com um escopo personalizado, o grupo de usuários retorna um token de acesso com o escopo personalizado e o cliente apresenta o token de acesso a uma API.

Para obter um token de acesso com escopos personalizados, a aplicação precisa fazer uma solicitação ao Endpoint de token para resgatar um código de autorização ou solicitar uma concessão de credenciais de cliente. Na UI hospedada, você também pode solicitar escopos personalizados em um token de acesso por meio de uma concessão implícita.

nota

Como eles foram projetados para autenticação interativa humana com o grupo de usuários como o IdP, as solicitações InitiateAuth e AdminInitiateAuth produzem apenas uma reivindicação scope no token de acesso com o valor único aws.cognito.signin.user.admin.

Gerenciar o servidor de recursos e os escopos personalizados

Ao criar um servidor de recursos, é necessário fornecer um nome e um identificador do servidor de recursos. Para cada escopo criado no servidor de recursos, é necessário fornecer o nome e a descrição do escopo.

  • Nome do servidor de recursos: um nome fácil de lembrar para o servidor de recursos, como Solar system object tracker ou Photo API.

  • Identificador do servidor de recursos: um identificador exclusivo do servidor de recursos. O identificador é qualquer nome que você deseja associar à API, por exemplo solar-system-data. É possível configurar identificadores mais longos, por exemplo https://solar-system-data-api.example.com, como uma referência mais direta aos caminhos de URI da API, mas strings mais longas aumentam o tamanho dos tokens de acesso.

  • Nome do escopo: o valor que você quer nas reivindicações scope. Por exemplo, sunproximity.read.

  • Descrição: uma descrição simples do escopo. Por exemplo, Check current proximity to sun.

O Amazon Cognito pode incluir escopos personalizados nos tokens de acesso para qualquer usuário, seja local para o grupo de usuários ou federado com um provedor de identidade de terceiros. Você pode escolher escopos para os tokens de acesso de usuários durante os fluxos de autenticação com o servidor de autorização OAuth 2.0 que inclui a interface de usuário hospedada. A autenticação do usuário deve começar no Autorizar endpoint com scope como um dos parâmetros da solicitação. O formato a seguir é recomendado para servidores de recursos. Para um identificador, use um nome fácil para a API. Para um escopo personalizado, use a ação autorizada.

resourceServerIdentifier/scopeName

Por exemplo, você descobriu um novo asteroide no cinturão de Kuiper e deseja registrá-lo por meio da API solar-system-data. O escopo que autoriza operações de gravação no banco de dados de asteroides é asteroids.add. Ao solicitar o token de acesso que autorizará você a registrar sua descoberta, formate o parâmetro de solicitação HTTPS scope como scope=solar-system-data/asteroids.add.

Excluir um escopo de um servidor de recursos não exclui a sua associação com todos os clientes. Em vez disso, o escopo é marcado como inativo. O Amazon Cognito não adiciona escopos inativos aos tokens de acesso, mas continua normalmente caso a aplicação solicite um. Se você adicionar o escopo ao servidor de recursos novamente mais tarde, o Amazon Cognito o gravará novamente no token de acesso. Se você solicitar um escopo que não tenha associado ao cliente de aplicação, independentemente de tê-lo excluído do servidor de recursos do grupo de usuários, a autenticação falhará.

É possível usar o AWS Management Console, a API e a CLI para definir os servidores de recursos e os escopos para o grupo de usuários.

Como definir um servidor de recurso para o grupo de usuários (AWS Management Console)

Você pode usar o AWS Management Console para definir um servidor de recursos para o seu grupo de usuários.

Para definir um servidor de recursos

  1. Faça login no console do Amazon Cognito.

  2. No painel de navegação, escolha User Pools (Grupos de usuários) e escolha o grupo de usuários que deseja editar.

  3. Escolha a guia App integration (Integração da aplicação) e localize Resource servers (Servidores de recursos).

  4. Escolha Create a resource server (Criar um servidor de recursos).

  5. Insira um Resource server name (Nome do servidor de recursos). Por exemplo, Photo Server.

  6. Insira um Resource server identifier (Identificador do servidor de recursos). Por exemplo, com.example.photos.

  7. Insira os Custom scopes (Escopos personalizados) para seus recursos, como read e write.

  8. Para cada Scope name (Nome de escopo), insira uma Description (Descrição), como view your photos e update your photos.

  9. Escolha Criar.

Seus escopos personalizados podem ser revisados na guia App integration (Integração da aplicação) em Resource servers (Servidores de recursos), na coluna Custom scopes (Escopos personalizados). É possível habilitar escopos personalizados para clientes de aplicações na guia App integration (Integração da aplicação) em App clients (Clientes da aplicação). Selecione um cliente da aplicação, localize Hosted UI settings (Configurações de interface do usuário hospedada) e escolha Edit (Editar). Adicione Custom scopes (Escopos personalizados) e escolha Save changes (Salvar alterações).

Como definir um servidor de recursos para o grupo de usuários (AWS CLI e API da AWS)

Use os comandos a seguir para especificar as configurações do servidor de recursos para o seu grupo de usuários.

Para criar um servidor de recursos
Para obter informações sobre as configurações do servidor de recursos
Para listar informações sobre todos os servidores de recursos do seu grupo de usuários
Para excluir um servidor de recursos
Para atualizar as configurações de um servidor de recursos