Mapeamento de tokens do Amazon Cognito para o esquema

Talvez você queira adicionar uma fonte de identidade a um repositório de políticas e mapear declarações ou tokens do provedor ao esquema do repositório de políticas. Você pode automatizar esse processo usando a Configuração guiada para criar seu repositório de políticas com uma fonte de identidade ou atualizar seu esquema manualmente após a criação do repositório de políticas. Depois de mapear os tokens para o esquema, você pode criar políticas que façam referência a eles.

Esta seção do guia do usuário tem as seguintes informações:

• Quando você pode preencher automaticamente os atributos de um esquema de armazenamento de políticas

• Como usar declarações de token do Amazon Cognito em suas políticas de permissões verificadas

• Como criar manualmente um esquema para uma fonte de identidade

Os repositórios de políticas vinculados à API e os repositórios de políticas com uma fonte de identidade que foram criados por meio da configuração guiada não exigem o mapeamento manual dos atributos do token de identidade (ID) para o esquema. Você pode fornecer Permissões Verificadas com os atributos em seu grupo de usuários e criar um esquema preenchido com atributos de usuário. Na autorização do token de ID, as Permissões verificadas mapeiam as reivindicações aos atributos de uma entidade principal. Talvez seja necessário mapear manualmente os tokens do Amazon Cognito para o seu esquema nas seguintes condições:

• Você criou um repositório de políticas vazio ou um repositório de políticas a partir de uma amostra.

• Você deseja estender o uso de tokens de acesso além do controle de acesso baseado em funções (RBAC).

• Você cria repositórios de políticas com a API REST de permissões verificadas, um AWS SDK ou o. AWS CDK

Para usar o Amazon Cognito como fonte de identidade em seu repositório de políticas de permissões verificadas, você deve ter atributos de provedor em seu esquema. O esquema é fixo e deve corresponder às entidades que os tokens do provedor criam IsAuthorizedWithTokenou às solicitações de BatchIsAuthorizedWithTokenAPI. Se você criou seu repositório de políticas de uma forma que preenche automaticamente seu esquema a partir das informações do provedor em um token de ID, você está pronto para escrever políticas. Se você criar um repositório de políticas sem um esquema para sua fonte de identidade, deverá adicionar atributos de provedor ao esquema que correspondam às entidades criadas usando solicitações de API. Em seguida, você pode escrever políticas usando atributos do token do provedor.

Para obter mais informações sobre o uso do Amazon Cognito ID e tokens de acesso para usuários autenticados em Permissões verificadas, consulte Autorização com permissões verificadas da Amazon no Guia do desenvolvedor do Amazon Cognito.

Mapeamento de tokens de ID para o esquema

As permissões verificadas processam as reivindicações de token de ID como atributos do usuário: seus nomes e títulos, sua associação ao grupo, suas informações de contato. Os tokens de ID são mais úteis em um modelo de autorização de controle de acesso baseado em atributos (ABAC). Quando você quiser que as Permissões Verificadas analisem o acesso aos recursos com base em quem está fazendo a solicitação, escolha tokens de ID para sua fonte de identidade.

Os tokens de ID do Amazon Cognito funcionam com a maioria das bibliotecas confiáveis do OIDC. Eles ampliam os recursos do OIDC com reivindicações adicionais. Seu aplicativo pode autenticar o usuário com as operações da API de autenticação de grupos de usuários do Amazon Cognito ou com a interface de usuário hospedada do grupo de usuários. Para obter mais informações, consulte Como usar a API e os endpoints no Guia do Desenvolvedor do Amazon Cognito.

Declarações úteis em tokens de ID do Amazon Cognito

cognito:username e preferred_username

Variantes do nome de usuário do usuário.

sub

O identificador de usuário exclusivo (UUID) do usuário

Reivindicações com um custom: prefixo

Um prefixo para atributos personalizados do grupo de usuários, comocustom:employmentStoreCode.

Reivindicações padrão

Afirmações padrão do OIDC, como e. email phone_number Para obter mais informações, consulte Declarações padrão no OpenID Connect Core 1.0 incorporando o conjunto de erratas 2.

cognito:groups

As associações de um usuário ao grupo. Em um modelo de autorização baseado no controle de acesso baseado em funções (RBAC), essa declaração apresenta as funções que você pode avaliar em suas políticas.

Reivindicações transitórias

Declarações que não são propriedade do usuário, mas são adicionadas em tempo de execução por um acionador Lambda de pré-geração de tokens do grupo de usuários. As reivindicações transitórias se assemelham às reivindicações padrão, mas estão fora do padrão, por exemplo tenant ou. department

Nas políticas que fazem referência aos atributos do Amazon Cognito que têm um : separador, faça referência aos atributos no formato. principal["cognito:username"] A reivindicação de funções cognito:groups é uma exceção a essa regra. As permissões verificadas mapeiam o conteúdo dessa declaração para as entidades principais da entidade do usuário.

Para obter mais informações sobre a estrutura dos tokens de ID dos grupos de usuários do Amazon Cognito, consulte Uso do token de ID no Guia do Desenvolvedor do Amazon Cognito.

O exemplo de token de ID a seguir tem cada um dos quatro tipos de atributos. Ele inclui a reivindicação específica do Amazon Cognito cognito:username, a reivindicação personalizada custom:employmentStoreCode, a reivindicação padrão email e a reivindicação temporária tenant.

{
    "sub": "91eb4550-XXX",
    "cognito:groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "email_verified": true,
    "clearance": "confidential",
    "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE",
    "cognito:username": "alice",
    "custom:employmentStoreCode": "petstore-dallas",
    "origin_jti": "5b9f50a3-05da-454a-8b99-b79c2349de77",
    "aud": "1example23456789",
    "event_id": "0ed5ad5c-7182-4ecf-XXX",
    "token_use": "id",
    "auth_time": 1687885407,
    "department": "engineering",
    "exp": 1687889006,
    "iat": 1687885407,
    "tenant": "x11app-tenant-1",
    "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111",
    "email": "[e-mail]"
}

Ao criar uma fonte de identidade com seu grupo de usuários do Amazon Cognito, você especifica o tipo de entidade principal com a qual o Verified Permissions gera nas solicitações de autorização. IsAuthorizedWithToken Suas políticas poderão, então, testar os atributos dessa entidade principal como parte da avaliação dessa solicitação. Seu esquema define o tipo e os atributos principais de uma fonte de identidade e, em seguida, você pode referenciá-los nas políticas do Cedar.

Você também especifica o tipo de entidade de grupo que deseja derivar da declaração do grupo de tokens de ID. Nas solicitações de autorização, as Permissões verificadas mapeiam cada membro da reivindicação do grupo para esse tipo de entidade do grupo. Nas políticas, você pode referenciar essa entidade do grupo como principal.

O exemplo a seguir mostra como refletir os atributos do exemplo de token de identidade no esquema do Verified Permissions. Para obter mais informações sobre a edição do esquema, consulte Editando esquemas de armazenamento de políticas. Se a configuração da origem de identidade especificar o tipo de entidade principal User, você poderá incluir algo semelhante ao exemplo a seguir para disponibilizar esses atributos ao Cedar.

"User": {
   "shape": {
      "type": "Record",
      "attributes": {
         "cognito:username": {
            "type": "String",
            "required": false
         },
         "custom:employmentStoreCode": {
            "type": "String",
            "required": false
         },
         "email": {
            "type": "String"
         },
         "tenant": {
            "type": "String",
            "required": true
         }
      }
   }
}

Para obter um exemplo de política que será validada em relação a esse esquema, consulte. Reflete os atributos do token de ID do Amazon Cognito

Mapeamento de tokens de acesso

As permissões verificadas processam declarações de token de acesso diferentes das reivindicações do grupo como atributos da ação ou atributos de contexto. Além da associação ao grupo, os tokens de acesso do seu IdP podem conter informações sobre o acesso à API. Os tokens de acesso são úteis em modelos de autorização que usam controle de acesso baseado em funções (RBAC). Os modelos de autorização que dependem de declarações de token de acesso que não sejam a associação ao grupo exigem um esforço adicional na configuração do esquema.

Os tokens de acesso do Amazon Cognito têm reivindicações que podem ser usadas para autorização:

Declarações úteis em tokens de acesso do Amazon Cognito

client_id

O ID do aplicativo cliente de uma parte confiável do OIDC. Com a ID do cliente, as Permissões Verificadas podem verificar se a solicitação de autorização vem de um cliente permitido para o repositório de políticas. Na autorização machine-to-machine (M2M), o sistema solicitante autoriza uma solicitação com um segredo do cliente e fornece o ID e os escopos do cliente como evidência da autorização.

scope

Os escopos OAuth 2.0 que representam as permissões de acesso do portador do token.

cognito:groups

As associações de um usuário ao grupo. Em um modelo de autorização baseado no controle de acesso baseado em funções (RBAC), essa declaração apresenta as funções que você pode avaliar em suas políticas.

Reivindicações transitórias

Declarações que não são uma permissão de acesso, mas são adicionadas em tempo de execução por um acionador Lambda de pré-geração de tokens do grupo de usuários. As reivindicações transitórias se assemelham às reivindicações padrão, mas estão fora do padrão, por exemplo tenant ou. department A personalização dos tokens de acesso adiciona custo à sua AWS fatura.

Para obter mais informações sobre a estrutura dos tokens de acesso dos grupos de usuários do Amazon Cognito, consulte Uso do token de acesso no Guia do Desenvolvedor do Amazon Cognito.

Um token de acesso do Amazon Cognito é mapeado para um objeto de contexto quando transmitido para o Verified Permissions. Os atributos do token de acesso podem ser referenciados por meio de context.token.attribute_name. O exemplo de token de acesso a seguir inclui as reivindicações client_id e scope.

{
    "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e",
    "cognito:groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE",
    "client_id": "1example23456789",
    "origin_jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111",
    "event_id": "bda909cb-3e29-4bb8-83e3-ce6808f49011",
    "token_use": "access",
    "scope": "MyAPI/mydata.write",
    "auth_time": 1688092966,
    "exp": 1688096566,
    "iat": 1688092966,
    "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222",
    "username": "alice"
}

O exemplo a seguir mostra como refletir os atributos do exemplo de token de acesso no esquema do Verified Permissions. Para obter mais informações sobre a edição do esquema, consulte Editando esquemas de armazenamento de políticas.

{
   "MyApplication": {
      "actions": {
         "Read": {
            "appliesTo": {
               "context": {
                  "type": "ReusedContext"
               },
               "resourceTypes": [
                  "Application"
               ],
               "principalTypes": [
                  "User"
               ]
            }
         }
      },
      ...
      ...
      "commonTypes": {
         "ReusedContext": {
            "attributes": {
               "token": {
                  "type": "Record",
                  "attributes": {
                     "scope": {
                        "type": "Set",
                        "element": {
                           "type": "String"
                        }
                     },
                     "client_id": {
                        "type": "String"
                     }
                  }
               }
            },
            "type": "Record"
         }
      }
   }
}

Para obter um exemplo de política que será validada em relação a esse esquema, consulte. Reflete os atributos do token de acesso do Amazon Cognito

Notação alternativa para declarações delimitadas por dois pontos do Amazon Cognito

No momento em que as Permissões verificadas foram lançadas, o esquema recomendado para o token do Amazon Cognito afirma ser cognito:groups semelhante custom:store e converteu essas cadeias de caracteres delimitadas por dois pontos para usar o caractere como delimitador de hierarquia. . Esse formato é chamado de notação de pontos. Por exemplo, uma referência a cognito:groups tornou-se principal.cognito.groups em suas políticas. Embora você possa continuar usando esse formato, recomendamos que você crie seu esquema e suas políticas com a notação de colchetes. Nesse formato, uma referência a se cognito:groups torna principal["cognito:groups"] em suas políticas. Os esquemas gerados automaticamente para tokens de ID do grupo de usuários do console de permissões verificadas usam a notação de colchetes.

Você pode continuar usando a notação de pontos em esquemas e políticas criados manualmente para fontes de identidade do Amazon Cognito. Você não pode usar a notação de pontos com : ou quaisquer outros caracteres não alfanuméricos no esquema ou nas políticas para qualquer outro tipo de IdP do OIDC.

Um esquema para notação de pontos agrupa cada instância de um : caractere como filha da frase custom inicial cognito ou da frase, conforme mostrado no exemplo a seguir:

"CognitoUser": {
   "shape": {
      "type": "Record",
      "attributes": {
         "cognito": {
            "type": "Record",
            "required": true,
            "attributes": {
               "username": {
                  "type": "String",
                  "required": true
               }
            }
         },
         "custom": {
            "type": "Record",
            "required": true,
            "attributes": {
               "employmentStoreCode": {
                  "type": "String",
                  "required": true
               }
            }
         },
         "email": {
            "type": "String"
         },
         "tenant": {
            "type": "String",
            "required": true
         }
      }
   }
}

Para obter um exemplo de política que validará esse esquema e usará a notação de pontos, consulte. Usa notação de pontos para referenciar atributos

Coisas que você deve saber sobre mapeamento de esquemas

O mapeamento de atributos difere entre os tipos de token

Na autorização do token de acesso, as permissões verificadas mapeiam as reivindicações de acordo com o contexto. Na autorização do token de ID, as Permissões verificadas mapeiam as reivindicações para os atributos principais. Para repositórios de políticas que você cria no console de Permissões Verificadas, somente repositórios de políticas vazios e de amostra deixam você sem fonte de identidade e exigem que você preencha seu esquema com atributos do grupo de usuários para autorização do token de ID. A autorização do token de acesso é baseada no controle de acesso baseado em funções (RBAC) com declarações de associação a grupos e não mapeia automaticamente outras reivindicações para o esquema do repositório de políticas.

Os atributos da fonte de identidade não são obrigatórios

Quando você cria uma fonte de identidade no console de Permissões verificadas, nenhum atributo é marcado como obrigatório. Isso evita que declarações perdidas causem erros de validação nas solicitações de autorização. Você pode definir atributos como obrigatórios conforme necessário, mas eles devem estar presentes em todas as solicitações de autorização.

O RBAC não exige atributos no esquema

Os esquemas para fontes de identidade dependem das associações de entidades que você faz ao adicionar sua fonte de identidade. Uma fonte de identidade mapeia uma afirmação para um tipo de entidade de usuário e uma afirmação para um tipo de entidade de grupo. Esses mapeamentos de entidades são o núcleo de uma configuração de origem de identidade. Com essas informações mínimas, você pode criar políticas que executem ações de autorização para usuários específicos e grupos específicos dos quais os usuários possam ser membros, em um modelo de controle de acesso baseado em função (RBAC). A adição de declarações de token ao esquema amplia o escopo de autorização do seu repositório de políticas. Os atributos de usuário dos tokens de ID têm informações sobre usuários que podem contribuir para a autorização do controle de acesso baseado em atributos (ABAC). Os atributos de contexto dos tokens de acesso têm informações como escopos OAuth 2.0 que podem contribuir com informações adicionais de controle de acesso do seu provedor, mas exigem modificações adicionais no esquema.

As opções Configurar com o API Gateway e um provedor de identidade e Configuração guiada no console de permissões verificadas atribuem reivindicações de token de ID ao esquema. Esse não é o caso das reivindicações de token de acesso. Para adicionar declarações de token de acesso que não sejam de grupo ao seu esquema, você deve editá-lo no modo JSON e adicionar atributos commonTypes. Para obter mais informações, consulte Mapeamento de tokens de acesso.

Escolha um tipo de token

A forma como seu repositório de políticas funciona com sua fonte de identidade depende de uma decisão importante na configuração da fonte de identidade: se você processará tokens de ID ou de acesso. Com um provedor de identidade do Amazon Cognito, você pode escolher o tipo de token ao criar um armazenamento de políticas vinculado à API. Ao criar um repositório de políticas vinculado à API, você deve escolher se deseja configurar a autorização para tokens de ID ou de acesso. Essas informações afetam os atributos do esquema que as Permissões Verificadas aplicam ao seu armazenamento de políticas e a sintaxe do autorizador Lambda para sua API do API Gateway. Especialmente se você quiser se beneficiar do mapeamento automático de declarações de token de ID para atributos no console de permissões verificadas, decida com antecedência sobre o tipo de token que você deseja processar antes de criar sua fonte de identidade. Alterar o tipo de token exige um esforço significativo para refatorar suas políticas e seu esquema. Os tópicos a seguir descrevem o uso de tokens de ID e acesso com repositórios de políticas.

O analisador Cedar requer colchetes para alguns caracteres

As políticas geralmente fazem referência aos atributos do esquema em um formato comoprincipal.username. No caso da maioria dos caracteres não alfanuméricos:, como, ou., / que podem aparecer nos nomes de reivindicações de token, as Permissões Verificadas não podem analisar um valor de condição como principal.cognito:username ou. context.ip-address Em vez disso, você deve formatar essas condições com a notação de colchetes no formato principal["cognito:username"] oucontext["ip-address"], respectivamente. O caractere sublinhado _ é um caractere válido nos nomes das reivindicações e a única exceção não alfanumérica a esse requisito.

Um exemplo parcial de esquema para um atributo principal desse tipo tem a seguinte aparência:

"User": {
   "shape": {
      "type": "Record",
      "attributes": {
         "cognito:username": {
            "type": "String",
            "required": true
         },
         "custom:employmentStoreCode": {
            "type": "String",
            "required": true,
         },
         "email": {
            "type": "String",
            "required": false
         }
      }
   }
}

Um exemplo parcial de esquema para um atributo de contexto desse tipo tem a seguinte aparência:

"GetOrder": {
   "memberOf": [],
   "appliesTo": {
      "resourceTypes": [
         "Order"
      ],
      "context": {
         "type": "Record",
         "attributes": {
            "ip-address": {
               "required": false,
               "type": "String"
            }
		 }
	  },
      "principalTypes": [
         "User"
      ]
   }
}

Para obter um exemplo de política que será validada em relação a esse esquema, consulte. Usa notação de colchetes para referenciar atributos de token