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

Mapeando tokens OIDC 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:

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.

Para usar um provedor de identidade (IdP) do OIDC 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.

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.

Trabalhar com tokens de ID de um provedor OIDC é praticamente o mesmo que trabalhar com tokens de ID do Amazon Cognito. A diferença está nas reivindicações. Seu IdP pode apresentar atributos padrão do OIDC ou ter um esquema personalizado. Ao criar um novo repositório de políticas no console de Permissões verificadas, você pode adicionar uma fonte de identidade do OIDC com um exemplo de token de ID ou mapear manualmente as declarações de token para os atributos do usuário. Como as Permissões Verificadas não conhecem o esquema de atributos do seu IdP, você deve fornecer essas informações.

Para obter mais informações, consulte Criação de armazenamentos de políticas do Verified Permissions.

Veja a seguir um exemplo de esquema para um repositório de políticas com uma fonte de identidade OIDC.

"User": {
   "shape": {
      "type": "Record",
      "attributes": {
         "email": {
            "type": "String"
         },
         "email_verified": {
            "type": "Boolean"
         },
         "name": {
            "type": "String",
            "required": true
         },
         "phone_number": {
            "type": "String"
         },
         "phone_number_verified": {
            "type": "Boolean"
         }
      }
   }
}

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

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.

A maioria dos tokens de acesso de provedores externos do OIDC se alinha estreitamente aos tokens de acesso do Amazon Cognito. Um token de acesso OIDC é mapeado para um objeto de contexto quando passado para Permissões verificadas. Os atributos do token de acesso podem ser referenciados por meio de context.token.attribute_name. O exemplo de token de acesso OIDC a seguir inclui exemplos de declarações básicas.

{
    "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e",
    "groups": [
        "Store-Owner-Role",
        "Customer"
    ],
    "iss": "https://auth.example.com",
    "client_id": "1example23456789",
    "aud": "https://myapplication.example.com"
    "scope": "MyAPI-Read",
    "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 OIDC

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.

Os grupos do OIDC afirmam que suporta vários formatos

Ao adicionar um provedor OIDC, você pode escolher o nome da reivindicação do grupo em ID ou tokens de acesso que deseja mapear para a associação de um usuário ao grupo em seu repositório de políticas. As permissões verificadas reconhecem as reivindicações de grupos nos seguintes formatos:

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 OIDC, você deve escolher um tipo de token ao adicionar a fonte de identidade. Você pode escolher ID ou token de acesso, e sua escolha exclui que o tipo de token não escolhido seja processado em seu repositório de políticas. 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 se parece com o seguinte:

"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