Como personalizar tokens e códigos de autorização

Esta é a documentação do Apigee Edge.
Acesse Documentação da Apigee X. informações

Sobre os metadados do token

O Apigee Edge gera tokens de acesso OAuth, tokens de atualização e códigos de autorização e os distribui para apps autenticados. No momento da geração, o Edge armazena esses tokens e códigos. Depois que o Edge receber solicitações de API de entrada que tenham esses tokens ou códigos, o Edge usará as informações armazenadas para autorizar as solicitações.

Quando o Edge gera esses artefatos OAuth, ele também anexa metadados ao token ou código. Por exemplo, um token de acesso é associado a pares de nome/valor que definem o prazo de validade, o app e o desenvolvedor associados, entre outras informações.

A representação JSON de um token de acesso do Edge é a seguinte:

{
  "issued_at" : "1372170159093",
  "application_name" : "ccd1803b-b557-4520-bd62-ddd3abf8e501",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[Product1,Product2]",
  "api_product_list_json" : ["Product1", "Product2"],
  "expires_in" : "3599", //--in seconds
  "developer.email" : "joe@weathersample.com",
  "organization_id" : "0",
  "refresh_token" : "82XMXgDyHTpFyXOaApj8C2AGIPnN2IZe",
  "client_id" : "deAVedE0W9Z9U35PAMaAJYphBJCGdrND",
  "access_token" : "shTUmeI1geSKin0TODcGLXBNe9vp",
  "organization_name" : "apifactory",
  "refresh_count" : "0"
}

Como adicionar atributos personalizados aos tokens OAuth

Às vezes é útil anexar metadados personalizados a um token de acesso. Por exemplo, é possível adicionar um nome de usuário, associações a grupos ou papéis para um usuário, um ID de cliente, um identificador de sessão ou outras informações arbitrárias a um token. No Apigee Edge, esses dados são chamados de "atributos personalizados". Em seguida, quando o token é verificado no escopo de uma solicitação da API, esses dados são disponibilizados para o proxy da API por meio de variáveis de contexto. Um proxy de API pode tomar decisões refinadas de autorização ou roteamento com base nos dados personalizados anexados ao token.

Para anexar dados arbitrários a um token, use o elemento <Attributes> na política de OAuthV2. É possível especificar o nome do atributo personalizado e o valor necessário para ele. Por exemplo, veja uma configuração de política que gera um token e anexa um atributo personalizado chamado "tenant_list" ao token:

<OAuthV2 name="GenerateAccessToken">
  <Operation>GenerateAccessToken</Operation>
  <ExpiresIn>600000</ExpiresIn>
  <GenerateResponse />
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <Attributes> 
    <Attribute name="tenant_list" ref="tenant_list_retrieved_from_external_service" display="false"/>
  </Attributes>
</OAuthV2>

É possível especificar vários atributos personalizados e anexá-los implicitamente a um código de autorização (<Operation>GenerateAuthorizationCode</Operation>) ou a um token (<Operation>GenerateAccessToken</Operation>) no momento da geração.

Quando display é definido como true (padrão), os atributos personalizados são retornados na resposta, em que podem ser visualizados pelo aplicativo ou transmitidos para o usuário final. Quando display é definido como false, os atributos personalizados são armazenados no armazenamento de dados, mas não são retornados na mensagem de resposta. Em ambos os casos, os dados personalizados ficam disponíveis para as políticas no proxy da API, após a verificação do token.

Para mais informações sobre a opção display Como exibir ou ocultar atributos personalizados na resposta.

Como receber atributos personalizados no ambiente de execução

Quando há uma chamada para OAuthV2/VerifyAccessToken, o Apigee Edge verifica o token pesquisando-o no repositório. Em seguida, o Apigee Edge preenche um conjunto de variáveis de contexto que contém informações sobre o token. São eles:

• organization_name
• developer.id
• developer.app.name
• client_id
• grant_type
• token_type
• access_token
• issued_at
• expires_in //--in seconds
• status
• scope
• apiproduct.name*

Se houver atributos personalizados no token, esses atributos serão disponibilizados em uma variável de contexto com o nome accesstoken.{custom_attribute}. Por exemplo, suponha que um token seja emitido da política mostrada acima. Depois de verificar esse token, haveria uma variável de contexto adicional chamada accesstoken.tenant_list, contendo o valor que estava armazenado no momento em que o token foi gerado.

As políticas ou condições podem referir-se a essas variáveis e modificar o comportamento com base nos valores armazenados.

Como configurar e atualizar atributos personalizados no ambiente de execução

Em algumas situações, convém que o proxy de API atualize os metadados associados a um token de acesso no ambiente de execução enquanto uma chamada de API está sendo processada no Apigee Edge. Para ajudar com isso, a Apigee fornece políticas para receber e definir atributos do token. Para mais informações, consulte Receber a política de informações do OAuth V2 e Definir a política de informações do OAuth V2.

Também é possível usar APIs de Edge para atualizar os atributos personalizados vinculados a um token. Veja a documentação da API para o método Atualizar token de acesso do OAuth 2.0.