Como solicitar tokens de acesso e códigos de autorização

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

Neste tópico, mostramos como solicitar tokens de acesso e códigos de autorização, configurar endpoints do OAuth 2.0 e definir políticas para cada tipo de concessão compatível.

Código de amostra

Para sua conveniência, as políticas e os endpoints discutidos neste tópico estão disponíveis no GitHub no projeto oauth-doc-examples no repositório api-platform-samples da Apigee. É possível implantar o código de amostra e testar as solicitações de amostra mostradas neste tópico. Consulte o README do projeto para mais detalhes.

Solicitação de um token de acesso: tipo de concessão do código de autorização

Nesta seção, explicamos como solicitar um token de acesso usando o fluxo de tipo de concessão do código de autorização. Para ver uma introdução aos tipos de concessão do OAuth 2.0, consulte Introdução ao OAuth 2.0.

Exemplo de solicitação

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

Parâmetros obrigatórios

Por padrão, esses parâmetros precisam ser x-www-form-urlencoded e especificados no corpo da solicitação (como mostrado no exemplo acima). No entanto, é possível alterar esse padrão configurando os elementos <GrantType>, <Code> e <RedirectUri> na política OAuthV2 anexada a este /accesstoken ponto de extremidade. Para detalhes, consulte Política do OAuthV2.

  • grant_type: precisa ser definido como o valor authorization_code.
  • code: o código de autorização recebido do endpoint /authorize (ou o nome que você escolher para o arquivo). Para solicitar um token de acesso no fluxo de concessão do código de autorização, primeiro você precisa conseguir um código de autorização. Veja abaixo Como solicitar códigos de autorização. Consulte também Como implementar o tipo de concessão de código de autorização.
  • redirect_uri: será preciso fornecer esse parâmetro se o parâmetro redirect_uri tiver sido incluído na solicitação de código de autorização anterior. Se o parâmetro redirect_uri não tiver sido incluído na solicitação do código de autorização e, se você não fornecer esse parâmetro, essa política usará o valor do URL de callback fornecido quando o desenvolvedor aplicativo foi registrado.

Parâmetros opcionais

  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Autenticação

Passe o ID e a chave secreta do cliente como um cabeçalho de autenticação básica (codificado em Base64) ou como parâmetros de formulário client_id e client_secret. É possível conseguir esses valores de um aplicativo de desenvolvedor registrado. Consulte também "Como codificar credenciais de autenticação básicas".

Endpoint de amostra

Veja um exemplo de configuração de endpoint para gerar um token de acesso. Ele executará a política GenerateAccessToken, que precisa ser configurada para aceitar o tipo de autorização authorization_code.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemplo de política

Essa é uma política GenerateAccessToken básica configurada para aceitar o tipo de concessão authorization_code. Para mais informações sobre elementos de configuração opcionais que podem ser configurados com essa política, consulte a Política do OAuthV2 (em inglês).

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Retorna

Com o <GenerateResponse> ativado, a política retorna uma resposta JSON que inclui o token de acesso, conforme mostrado abaixo. O tipo de concessão authorization_code cria um token de acesso e um token de atualização. Assim, uma resposta pode ter a seguinte aparência:

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

Se <GenerateResponse> for definido como falso, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de fluxo com dados relativos à concessão do token de acesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Solicitação de um token de acesso: tipo de concessão da credencial do cliente

Nesta seção, explicamos como solicitar um token de acesso usando o fluxo de tipos de concessão de credenciais do cliente. Para ver uma introdução aos tipos de concessão do OAuth 2.0, consulte Introdução ao OAuth 2.0.

Exemplo de solicitação

Para informações sobre como codificar o cabeçalho de autenticação básica na chamada a seguir, consulte "Como codificar credenciais de autenticação básica".

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Parâmetros obrigatórios

Por padrão, o parâmetro concessão_type necessário precisa ser x-www-form-urlencoded e especificado no corpo da solicitação (conforme mostrado na amostra acima). No entanto, é possível alterar esse padrão configurando o elemento <GrantType> na política OAuthV2 anexada a este ponto de extremidade /accesstoken. Por exemplo, é possível optar por passar o parâmetro em um parâmetro de consulta. Veja mais detalhes em Política do OAuthV2.

  • grant_type: precisa ser definido como o valor client_credentials.

Parâmetros opcionais

  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Autenticação

Passe o ID e a chave secreta do cliente como um cabeçalho de autenticação básica (codificado em Base64) ou como parâmetros de formulário client_id e client_secret. Você recebe esses valores do aplicativo do desenvolvedor registrado associado à solicitação. Consulte também "Como codificar credenciais de autenticação básica".

Endpoint de amostra

Veja um exemplo de configuração de endpoint para gerar um token de acesso. Ele executará a política GenerateAccessToken, que precisa ser configurada para aceitar o tipo de autorização client_credentials.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemplo de política

Essa é uma política GenerateAccessToken básica configurada para aceitar o tipo de concessão client_credentials. Para mais informações sobre elementos de configuração opcionais que podem ser configurados com essa política, consulte a Política do OAuthV2 (em inglês).

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Retorna

Com <GenerateResponse> ativado, a política retorna uma resposta JSON. Observe que, com o tipo de concessão client_credentials, os tokens de atualização não são compatíveis. Somente um token de acesso é criado. Exemplo:

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

Se <GenerateResponse> for definido como falso, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de fluxo com dados relativos à concessão do token de acesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

Exemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

Solicitar um token de acesso: tipo de concessão de senha

Nesta seção, explicamos como solicitar um token de acesso usando o fluxo de tipo de concessão da senha do proprietário do recurso (senha). Para uma introdução aos tipos de concessão do OAuth 2.0, consulte Introdução ao OAuth 2.0.

Para mais detalhes sobre o tipo de concessão de senha, incluindo um vídeo de quatro minutos que mostra como implementá-lo, consulte Como implementar o tipo de concessão de senha.

Exemplo de solicitação

Para informações sobre como codificar o cabeçalho de autenticação básica na chamada a seguir, consulte "Como codificar credenciais de autenticação básica".

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

Parâmetros obrigatórios

Por padrão, esses parâmetros precisam ser x-www-form-urlencoded e especificados no corpo da solicitação (como mostrado no exemplo acima). No entanto, é possível alterar esse padrão configurando os elementos <GrantType>, <Username> e <Password> na política OAuthV2 anexada a este /token ponto de extremidade. Para detalhes, consulte a Política do OAuthV2 (em inglês).

As credenciais de usuário normalmente são validadas em um armazenamento de credenciais usando uma política de LDAP ou JavaScript.

  • grant_type: precisa ser definido como o valor password.
  • username: nome do usuário do proprietário do recurso
  • password: a senha do proprietário do recurso.

Parâmetros opcionais

  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Autenticação

Passe o ID e a chave secreta do cliente como um cabeçalho de autenticação básica (codificado em Base64) ou como parâmetros de formulário client_id e client_secret. Você recebe esses valores do aplicativo do desenvolvedor registrado associado à solicitação. Consulte também "Como codificar credenciais de autenticação básica".

Endpoint de amostra

Veja um exemplo de configuração de endpoint para gerar um token de acesso. Ele executará a política GenerateAccessToken, que precisa ser configurada para aceitar o tipo de concessão de senha.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemplo de política

Esta é uma política GenerateAccessToken configurada básica para aceitar o tipo de concessão da senha. Para mais informações sobre elementos de configuração opcionais que podem ser configurados com essa política, consulte a Política do OAuthV2.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Retorna

Com <GenerateResponse> ativado, a política retorna uma resposta JSON. Observe que tanto os tokens de acesso como os de atualização são criados com o tipo de concessão de senha. Por exemplo:

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

Se <GenerateResponse> for definido como falso, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de fluxo com dados relativos à concessão do token de acesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

Como solicitar um token de acesso: tipo de concessão implícito

Nesta seção, explicamos como solicitar um token de acesso usando o fluxo implícito do tipo de concessão. Para uma introdução aos tipos de concessão do OAuth 2.0, consulte Introdução ao OAuth 2.0.

Exemplo de solicitação

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

Parâmetros obrigatórios

Por padrão, esses parâmetros precisam ser parâmetros de consulta (conforme mostrado no exemplo acima). No entanto, é possível alterar esse padrão configurando os elementos <ResponseType>, <ClientId> e <RedirectUri> na política OAuthV2 anexada a esse endpoint /token. Veja mais detalhes em Política do OAuthV2.

As credenciais de usuário geralmente são validadas em relação a um armazenamento de credenciais usando uma chamada de serviço LDAP ou uma política JavaScript.

  • response_type: precisa ser definido como o valor token.
  • client_id: o ID do cliente de um aplicativo do desenvolvedor registrado.
  • redirect_uri: este parâmetro será obrigatório se um URI de callback não tiver sido fornecido quando o app desenvolvedor do cliente tiver sido registrado. Se um URL de retorno de chamada foi fornecido no registro do cliente, ele será comparado a esse valor e precisará corresponder exatamente.

Parâmetros opcionais

  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Autenticação

A concessão implícita não requer autenticação básica. Você precisa passar um ID do cliente como um parâmetro de solicitação, conforme explicado aqui.

Endpoint de amostra

Veja um exemplo de configuração de endpoint para gerar um token de acesso. Ele executará a política GenerateAccessTokenImplicitGrant.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

Exemplo de política

Trata-se de uma política básica de GenerateAccessTokenExplicitGrant que processa solicitações de token para o fluxo de tipo de concessão implícito. Para mais informações sobre elementos de configuração opcionais que podem ser configurados com essa política, consulte a Política do OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Retorna

Com <GenerateResponse> ativado, a política retorna um redirecionamento 302 no cabeçalho da resposta. O redirecionamento aponta para o URL especificado no parâmetro redirect_uri e é anexado ao token de acesso e ao prazo de validade do token. Observe que o tipo de concessão implícito não é compatível com tokens de atualização. Exemplo:

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

Se <GenerateResponse> for definido como falso, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de fluxo com dados relativos à concessão do token de acesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

Exemplo:

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

Como solicitar um código de autorização

Se você estiver usando o fluxo de concessão de código de autorização, será necessário conseguir um código de autorização antes de solicitar um token de acesso.

Exemplo de solicitação

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

em que uma política OAuthGenerate GenerateAuthorizationCode é anexada ao endpoint de proxy /oauth/authorize (consulte o exemplo de endpoint abaixo).

Parâmetros obrigatórios

Por padrão, esses parâmetros precisam ser parâmetros de consulta (conforme mostrado no exemplo acima). No entanto, é possível alterar esse padrão configurando os elementos <ResponseType>, <ClientId> e <RedirectUri> na política OAuthV2 anexada a esse endpoint /authorize. Veja mais detalhes em Política do OAuthV2.

  • response_type: precisa ser definido como o valor code.
  • client_id: o ID do cliente de um aplicativo do desenvolvedor registrado.

Parâmetros opcionais

  • redirect_uri: se um URI de callback completo (não parcial) for especificado no app cliente registrado, esse parâmetro será opcional. caso contrário, será obrigatório. O callback é o URL em que o Edge envia o código de autenticação recém-criado. Consulte também Registrar apps e gerenciar chaves de API.
  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Authentication

Não requer autenticação básica, no entanto, o ID do cliente do app cliente registrado precisa ser fornecido na solicitação.

Endpoint de amostra

Veja um exemplo de configuração de endpoint para gerar um código de autorização:


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

Exemplo de política

Esta é uma política geral de GenerateAuthorizationCode. Para mais informações sobre elementos de configuração opcionais que podem ser configurados com essa política, consulte a política do OAuthV2.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

Retorna

Com <GenerateResponse> ativado, a política retorna o parâmetro de consulta ?code para o local redirect_uri (URI de callback) com o código de autorização anexado. Ele é enviado por meio de um redirecionamento 302 do navegador com o URL no cabeçalho de localização da resposta. Exemplo: ?code=123456.

Se <GenerateResponse> estiver definido como false, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de fluxo com dados relacionados ao código de autorização.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

Exemplo:

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

Atualização do token de acesso

Um token de atualização é uma credencial que você usa para conseguir um token de acesso, geralmente depois que o token de acesso expirou ou se torna inválido. Um token de atualização é retornado na resposta quando você recebe um token de acesso.

Para solicitar um novo token de acesso com um token de atualização:

Exemplo de solicitação

Para informações sobre como codificar o cabeçalho de autenticação básica na chamada a seguir, consulte "Como codificar credenciais de autenticação básica".

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

Parâmetros obrigatórios

  • grant_type: precisa ser definido como o valor refresh_token.
  • refresh_token: o token de atualização associado ao token de acesso que você quer renovar.

Por padrão, a política procura esses parâmetros como x-www-form-urlencoded especificados no corpo da solicitação, como mostrado no exemplo acima. Para configurar um local alternativo para essas entradas, use os elementos <GrantType> e <RefreshToken> na política OAuthV2. Para detalhes, consulte a Política do OAuthV2 (em inglês).

Parâmetros opcionais

  • state: uma string que será enviada de volta com a resposta. Usado normalmente para evitar ataques de falsificação de solicitação entre sites.
  • scope: permite filtrar a lista de produtos da API com que o token criado pode ser usado. Para informações detalhadas sobre escopo, consulte Como trabalhar com escopos do OAuth2.

Authentication

  • client_id
  • client_secret

Passe o ID e a chave secreta do cliente como um cabeçalho de autenticação básica (codificado em Base64) ou como parâmetros de formulário client_id e client_secret. Consulte também "Como codificar credenciais de autenticação básicas".

Ao atualizar um token de acesso, não há uma nova autenticação do usuário.

Veja um exemplo de configuração de endpoint para gerar um token de acesso usando um token de atualização. Ele executará a política RefreshAccessToken.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

Exemplo de política

Esta é uma política RefreshAccessToken básica configurada para aceitar o tipo de concessão refresh_token. Para mais informações sobre os elementos de configuração opcionais que podem ser configurados com essa política, consulte a política do OAuthV2.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

Retorna

Com <GenerateResponse> ativado, a política retorna uma resposta JSON que contém o novo token de acesso. O tipo de concessão refresh_token é compatível com a redução de acessos e novos tokens de atualização. Exemplo:

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

Você precisa saber que, depois que um novo token de atualização é criado, o original não é mais válido.

A resposta acima é o que você receberá se <GenerateResponse> estiver definido como verdadeiro. Se <GenerateResponse> for definido como falso, a política não retornará uma resposta. Em vez disso, ele preenche o seguinte conjunto de variáveis de contexto (fluxo) com dados relacionados à concessão do token de acesso.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

Exemplo:

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

Como codificar credenciais de autenticação básica

Quando você faz uma chamada de API para solicitar um token ou código de autenticação, é recomendado pela especificação OAuth 2.0 passar os valores client_id e client_secret como um cabeçalho HTTP-Basic Authentication, conforme descrito em IETF RFC 2617. Para fazer isso, é preciso codificar o resultado em base64 com dois valores separados por dois pontos.

Em pseudocódigo:

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

Neste exemplo, ns4fQc14Zg4hKFCNaSzArVuwszX95X é o client_id e ZIjFyTsNgQNyxI é a chave secreta do cliente.

Independentemente da linguagem de programação usada para calcular o valor codificado em base64, o resultado codificado em base64 é: bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

Em seguida, é possível fazer a solicitação de token da seguinte maneira:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

O utilitário curl criará o cabeçalho HTTP básico para você, se você usar a opção -u. O seguinte é equivalente ao seguinte:

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

Outros ambientes de programação podem ter atalhos semelhantes que geram automaticamente o cabeçalho codificado em base64.

Tokens de hash no banco de dados

Para proteger os tokens de acesso e atualização do OAuth no caso de uma violação de segurança do banco de dados, ative o hash automático de tokens na sua organização do Edge. Quando o recurso está ativado, o Edge cria automaticamente uma versão com hash dos tokens de atualização e de acesso OAuth gerados recentemente usando o algoritmo que você especificar. (Informações sobre hash em massa de tokens existentes a seguir.) Os tokens sem hash são usados em chamadas de API, e o Edge os valida nas versões com hash do banco de dados.

As seguintes propriedades no nível da organização controlam o hash de token OAuth.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Se você tiver tokens com hash existentes e quiser mantê-los até que eles expirem, defina as seguintes propriedades na sua organização, em que o algoritmo de hash corresponde ao algoritmo existente (por exemplo, SHA1, o antigo padrão do Edge). Se os tokens não tiverem hash, use PLAIN.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Se você for um cliente do Edge Cloud, entre em contato com o suporte do Apigee Edge para definir estas propriedades na sua organização e, opcionalmente, gerar hash de tokens existentes.

Temas relacionados