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

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Sobre metadados de token e código de autorização

A Apigee 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, a Apigee armazena esses tokens e códigos. Depois de receber solicitações de API de entrada que têm esses tokens ou códigos, a Apigee usa as informações armazenadas para autorizar as solicitações.

Quando gera esses artefatos OAuth, a Apigee 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 da Apigee é:

{
  "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"
}

Adicionar atributos personalizados a tokens OAuth e códigos de autorização

À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. Na Apigee, 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 e o valor do atributo personalizado. 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, consulte Como exibir ou ocultar atributos personalizados na resposta.

Como receber atributos de token de acesso personalizados no ambiente de execução

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

  • organization_name
  • developer.id
  • developer.app.name
  • client_id
  • grant_type
  • token_type
  • access_token
  • issued_at
  • expires_in //--em segundos
  • 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 na Apigee. 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.

Em cada uma dessas políticas, o elemento AccessToken precisa se referir a uma variável que contém o token de acesso.