Esta página foi traduzida pela API Cloud Translation.

Como usar tokens do OAuth de terceiros

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. informações

Neste tópico, discutiremos como importar tokens de acesso gerados externamente, tokens de atualização ou códigos de autenticação no armazenamento de tokens do Edge. Use essa técnica se quiser configurar o Apigee Edge para validar tokens gerados fora do Apigee Edge.

No caso usual, o Apigee Edge gerará e armazenará um token OAuth e o retornará ao aplicativo que fez a chamada. Em seguida, o aplicativo de chamada apresenta o token de volta ao Apigee Edge ao solicitar serviço. O Apigee Edge, por meio da política OAuthV2 com operação = VerifyAccessToken, verificará se o token é válido. Este tópico descreve como configurar o Apigee Edge para armazenar um token OAuth que foi gerado em outro lugar, mantendo a parte de verificação de token igual à mesma forma como o token foi gerado pelo Edge.

Exemplo

Se você quiser ver um exemplo funcional que ilustra a técnica descrita neste tópico, consulte o exemplo de gerenciamento de token delegado da Apigee.

O que é isso?

Suponha que você já tenha um sistema de autorização e queira usar os valores de token ou código gerados pelo sistema no lugar do token OAuth2 ou dos valores de código que o Edge gera. Você pode fazer solicitações seguras de proxy de API com o token ou o código substituído, e o Edge as validará como se fossem geradas pelo Edge.

Algum plano de fundo

No caso habitual, o Apigee Edge gera um token produzindo uma string aleatória de letras e números. O Apigee Edge associa a esse token, outros dados, como a hora em que o token foi emitido, a expiração, a lista de produtos da API cujo token é válido e o escopo. Todas essas informações podem ser retornadas em uma resposta gerada automaticamente pela política OAuthV2 configurada com Operation = GenerateAccessToken. A resposta será assim:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "zBC90HhCGmGlaMBWeZAai2s3za5j",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

O valor do atributo access_token é efetivamente a chave de pesquisa dos dados de resposta. Um app pode fazer uma solicitação para um proxy de API hospedado no Edge, com o token do portador zBC90HhCGmGlaMBWeZAai2s3za5j, e o Edge, com a política OAuthV2 com a operação = VerifyAccessToken, procurará o token, recuperará todas as informações e usará essas informações para determinar se o token é válido ou não para o proxy de API solicitado. Isso é chamado de validação de token. Todas as informações acima abrangem o token. O valor access_token é apenas a maneira de procurar essas informações.

Por outro lado, seguindo as etapas descritas aqui, você pode configurar o Edge para armazenar um token para que o valor de access_token seja gerado por um serviço externo. Todos os outros metadados podem ser iguais. Por exemplo, suponha que você tenha um sistema externo ao Apigee Edge que gera tokens no formato "TOKEN-<16 random numbers>" . Nesse caso, os metadados completos do token armazenados pelo Apigee Edge podem ser:

{
  "issued_at": "1469735625687",
  "application_name": "06947a86-919e-4ca3-ac72-036723b18231",
  "scope": "urn://example.com/read",
  "status": "approved",
  "api_product_list": "[implicit-test]",
  "api_product_list_json": ["implicit-test"],
  "expires_in": "1799", //--in seconds
  "developer.email": "joe@weathersample.com",
  "token_type": "BearerToken",
  "client_id": "U9AC66e9YFyI1yqaXgUF8H6b9wUN1TLk",
  "access_token": "TOKEN-1092837373654221",
  "organization_name": "wwitman",
  "refresh_token_expires_in": "0", //--in seconds
  "refresh_count": "0"
}

Nesse caso, um aplicativo pode fazer uma solicitação para um proxy da API hospedado no Edge, passando o token do portador TOKEN-1092837373654221 e o Edge, por meio da política OAuthV2 com operação = VerifyAccessToken - poderá validar. Você pode aplicar um padrão de importação semelhante aos códigos de autorização e aos tokens de atualização.

Vamos falar sobre como validar credenciais de cliente

Um pré-requisito para gerar um token é validar o cliente solicitante. Por padrão, a política OAuthV2/GenerateAccessToken no Apigee Edge verifica implicitamente as credenciais do cliente. Normalmente, em uma solicitação de um token OAuthV2, o client_id e client_secret são passados no cabeçalho de autorização, codificados por meio de autorização básica HTTP (com a concatenação de dois pontos e, então, codificada em base64). A política OAuthV2/GenerateAccessToken no Apigee Edge decodifica esse cabeçalho e procura o client_id e verifica se o client_secret transmitido é válido para esse client_id. Isso funciona se as credenciais forem conhecidas pelo Apigee Edge. Em outras palavras, há um aplicativo de desenvolvedor armazenado no Apigee Edge que contém uma credencial, que contém o client_id e o client_secret.

Caso as credenciais do cliente não sejam validadas pelo Apigee Edge, é necessário projetar o proxy da API antes que ele gere um token para validar explicitamente o cliente por outros meios. Geralmente, isso é feito por meio de uma política ServiceCallout que se conecta a um endpoint remoto na sua rede.

De uma forma ou de outra, implícita ou explicitamente, você precisa garantir que o proxy da API que gera tokens valide primeiro as credenciais do cliente. A validação do cliente é independente de gerar o token de acesso. É possível configurar o Apigee Edge para realizar essas ações ou fazer uma delas ou outra.

Se você quiser que a política OAuthV2/GenerateAccessToken no Apigee Edge valide as credenciais do cliente no armazenamento de borda, defina o elemento <ExternalAuthorization> como false dentro da configuração da política ou omita-o por completo. Se você quiser usar um serviço de autorização externo para validar explicitamente as credenciais do cliente, defina <ExternalAuthorization> como true.

O Apigee Edge pode não validar as credenciais do cliente, mas ainda é necessário que o client_id seja conhecido e gerenciado pelo Apigee Edge. Cada access_token no Apigee Edge, seja ele gerado por um sistema externo ou importado para o Apigee Edge, precisa estar associado a um aplicativo cliente, indicado pelo client_id. Portanto, mesmo quando a política OAuthV2/GenerateAccessToken no Apigee Edge não validará o client_id e o client_secret, a política validará que o client_id é válido, presente e não foi revogado. Portanto, como uma etapa de configuração de pré-requisito, talvez seja necessário importar o client_id por meio da API administrativa Edge.

Fluxo de política para OAuth de terceiros na Apigee

Para usar tokens de sistemas OAuth de terceiros no Apigee Edge, o fluxo para gerar tokens de acesso precisa seguir um dos seguintes padrões.

Validação externa de credenciais de cliente

ServiceCallout para verificar as credenciais de entrada do cliente e adquirir um token externo.
ExtractVariables ou uma etapa JavaScript para extrair o token gerado externamente da resposta.
AssignMessage para definir a variável especial conhecida chamada oauth_external_authorization_status. O valor precisa ser true para indicar que as credenciais do cliente são válidas.
OAuthV2/GenerateAccessToken com o elemento <ExternalAuthorization> definido como true e pelo menos um de <ExternalAccessToken>, <ExternalRefreshToken> ou <ExternalAuthorizationCode>.

Validação interna de credenciais de cliente

ServiceCallout para adquirir um token externo.
ExtractVariables ou uma etapa JavaScript para extrair o token gerado externamente da resposta.
OAuthV2/GenerateAccessToken com o elemento <ExternalAuthorization> definido como false e pelo menos um de <ExternalAccessToken>, <ExternalRefreshToken> ou <ExternalAuthorizationCode>.

Observações sobre a configuração de fluxo e política

Caso queira usar um sistema externo para validar as credenciais do cliente, cabe a você desenvolver um fluxo de política que faça o que é necessário. Normalmente, você usaria uma política ServiceCalling para enviar as credenciais reconhecidas externamente para o serviço de autenticação externo. O serviço de autenticação externo normalmente retorna uma resposta e, se as credenciais forem válidas, também será um token de acesso.
Após a ServiceCallout, o proxy da API precisa analisar a resposta para extrair o status de validade, bem como o access_token gerado externamente, e possivelmente o refresh_token.
Na política OAuthV2/GenerateAccessToken, defina o elemento <StoreToken> como true e o elemento <ExternalAuthorization> como true ou false conforme apropriado.

Quando a política OAuthV2/GenerateAccessToken é executada, ela lê a variável oauth_external_authorization_status. Se a variável for definida e o valor for verdadeiro, o Apigee Edge não tentará validar as credenciais do cliente. Se a variável não estiver definida ou o valor não for verdadeiro, o Apigee Edge tentará validar as credenciais do cliente.
Há três elementos para a política OAuthV2 que permite especificar os dados externos a serem importados: <ExternalAccessToken>, <ExternalRefreshToken> e <ExternalAuthorizationCode>. Cada um desses elementos aceita uma variável de fluxo. A política do Edge lerá essa variável para encontrar o token de acesso gerado manualmente, o token de atualização ou o código de autorização. Cabe a você implementar políticas e lógica para colocar os tokens ou códigos externos nas variáveis apropriadas.

Por exemplo, a configuração a seguir na política OAuthV2 instrui o Edge a procurar o token em uma variável de contexto chamada external_token.
```
<ExternalAccessToken>external_token</ExternalAccessToken>
```
Você também precisa ter uma etapa anterior que defina essa variável.
Com relação à configuração da variável oauth_external_authorization_status, uma técnica comum para definir essa variável é usar uma política AssignMessage com o elemento AssignVariable, da seguinte forma:
```
<AssignMessage name="AssignMessage-SetVariable">
    <DisplayName>Assign Message - Set Variable</DisplayName>
    <AssignVariable>
        <Name>oauth_external_authorization_status</Name>
        <Value>true</Value>
    </AssignVariable>
    <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
</AssignMessage>
```
Lembre-se de que essa política precisa estar antes da política OAuthV2 com Operation = GenerateAccessToken.

Exemplo de política do OAuthV2

A política OAuthV2 a seguir gera um token de acesso do Apigee Edge, considerando que o Edge encontra um valor de token na variável de fluxo external_access_token.

<OAuthV2 name="OAuth-v20-Store-External-Token">
    <ExternalAccessToken>external_access_token</ExternalAccessToken>
    <ExternalAuthorization>true</ExternalAuthorization>
    <Operation>GenerateAccessToken</Operation>
    <GenerateResponse enabled="true">
        <Format>FORM_PARAM</Format>
    </GenerateResponse>
    <ReuseRefreshToken>false</ReuseRefreshToken>
    <StoreToken>true</StoreToken>
    <SupportedGrantTypes>
        <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <ExpiresIn ref='flow.variable'>2400000</ExpiresIn>
</OAuthV2>

Normalmente, com o tipo de concessão das credenciais do cliente, é necessário fornecer um cabeçalho de autenticação básica com o ID e a chave secreta do cliente codificados. No entanto, nesse caso, você não precisa fornecer esse cabeçalho. A política ainda espera que client_id esteja presente na solicitação para que a política o valide. O Edge espera que o client_id seja enviado como parte dos dados do formulário de solicitação, por exemplo, em request.formparam.client_id.

Teoricamente, você pode aplicar esse padrão com qualquer serviço de autorização OAuth2 de terceiros.