Personalizar tokens e códigos de autorização

Esta página aplica-se ao Apigee e ao Apigee Hybrid.

Veja a documentação do Apigee Edge.

Acerca dos metadados do código de autorização e do token

O Apigee gera tokens de acesso OAuth, tokens de atualização e códigos de autorização, e distribui-os a apps autenticadas. No momento da geração, o Apigee armazena esses tokens e códigos. Mais tarde, quando o Apigee recebe pedidos de API de entrada com estes tokens ou códigos, o Apigee usa as informações armazenadas para autorizar os pedidos.

Quando o Apigee gera estes artefactos OAuth, também anexa metadados ao token ou ao código. Por exemplo, um token de acesso está associado a pares de nomes/valores que definem o tempo de validade, a app e o programador associados, bem como outras informações.

A representação JSON de um token de acesso do Apigee tem o seguinte aspeto:

{
  "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 códigos de autorização e tokens OAuth

Por vezes, é útil anexar metadados personalizados a um token de acesso. Por exemplo, pode querer adicionar um nome de utilizador, associações a grupos ou funções para um utilizador, um ID de cliente, um identificador de sessão ou outras informações arbitrárias a um token. No Apigee, estes dados são denominados "atributos personalizados". Posteriormente, quando o token é validado no âmbito de um pedido de API, esses dados são disponibilizados ao proxy da API através de variáveis de contexto. Um proxy de API pode tomar decisões de autorização ou encaminhamento detalhadas com base nos dados personalizados anexados ao token.

Para anexar dados arbitrários a um token, use o elemento <Attributes> na política OAuthV2. Pode especificar o nome e o valor do atributo personalizado. Por exemplo, segue-se uma configuração de política que gera um token e anexa um atributo personalizado denominado "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>

Pode 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 está definido como true (predefinição), os atributos personalizados são devolvidos na resposta, onde podem ser visíveis para a app ou transmitidos ao utilizador final. Quando display está definido como false, os atributos personalizados são armazenados no arquivo de dados, mas não são devolvidos na mensagem de resposta. Em qualquer dos casos, os dados personalizados estão disponíveis para as políticas no proxy de API depois de o token ter sido validado.

Para mais informações acerca da opção display, consulte o artigo Apresentar ou ocultar atributos personalizados na resposta.

Obter atributos de tokens de acesso personalizados em tempo de execução

Quando existe uma chamada para OAuthV2/VerifyAccessToken, O Apigee valida o token ao procurá-lo na loja de tokens. Em seguida, o Apigee 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 //--in seconds
  • status
  • scope
  • apiproduct.name*

Se existirem atributos personalizados no token, esses atributos personalizados são disponibilizados numa variável de contexto com o nome accesstoken.{custom_attribute}. Por exemplo, suponha que é emitido um token a partir da política apresentada acima. Após a validação de um token deste tipo, existiria uma variável de contexto adicional denominada accesstoken.tenant_list, que contém o valor que foi armazenado no momento em que o token foi gerado.

As políticas ou as condições podem, então, referir-se a estas variáveis e modificar o comportamento com base nos valores armazenados nas mesmas.

Definir e atualizar atributos personalizados no tempo de execução

Em algumas situações, vai querer que o proxy de API atualize os metadados associados a um token de acesso em tempo de execução enquanto uma chamada de API está a ser processada no Apigee. Para ajudar com isto, o Apigee fornece políticas para obter e definir atributos de tokens. Para mais informações, consulte a política Get OAuth V2 Info e a política Set OAuth V2 Info.

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