Política OAuthV2

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

Veja a documentação do Apigee Edge.

O quê

O OAuthV2 é uma política multifacetada para realizar operações do tipo de concessão OAuth 2.0. Esta é a política principal usada para configurar os pontos finais do OAuth 2.0 no Apigee.

Esta política é uma política extensível e a utilização desta política pode ter implicações de custo ou utilização, consoante a sua licença do Apigee. Para ver informações sobre os tipos de políticas e as implicações de utilização, consulte Tipos de políticas.

Para saber mais sobre o OAuth no Apigee, consulte a página inicial do OAuth. Inclui links para recursos, exemplos, vídeos e muito mais.

Exemplos

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

Veja também o artigo Codificar credenciais de autenticação básica.

Referência do elemento

A referência da política descreve os elementos e os atributos da política OAuthV2.

A política de exemplo apresentada abaixo é uma de muitas configurações possíveis. Este exemplo mostra uma política OAuthV2 configurada para a operação GenerateAccessToken. Inclui elementos obrigatórios e opcionais. Consulte as descrições dos elementos nesta secção para ver detalhes.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

Atributos <OAuthV2>

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

A tabela seguinte descreve os atributos comuns a todos os elementos principais de políticas:

Elemento <DisplayName>

Use em conjunto com o atributo name para etiquetar a política no editor de proxy da IU de gestão com um nome diferente em linguagem natural.

<DisplayName>Policy Display Name</DisplayName>

Elemento <AccessToken>

<AccessToken>request.header.access_token</AccessToken>

Por predefinição, quando o Operation é VerifyAccessToken, a política espera que o token de acesso seja enviado no cabeçalho Authorization como um token de portador, ou seja, com o prefixo "Bearer", seguido de um espaço em branco. Pode alterar essa predefinição através deste elemento, especificando o nome de uma variável que contém o token de acesso a validar. Quando usa este elemento, a política, por predefinição, não procura um prefixo no conteúdo da variável. Se quiser especificar que a política deve procurar um prefixo, use também o elemento AccessTokenPrefix.

Exemplos:

• Quando a configuração da política é:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.header.access_token</AccessToken>
    </OAuthV2>

  Para transmitir o token através do curl, pode usar:

    curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

• Quando a configuração da política é:

    <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
        <Operation>VerifyAccessToken</Operation>
        <AccessToken>request.queryparam.token</AccessToken>
    </OAuthV2>

  Para transmitir o token através do curl, pode usar:

    curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

Onde API_ENDPOINT é o domínio usado para aceder às suas APIs, conforme configurado no seu sistema Apigee.

Elemento <AccessTokenPrefix>

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

Por predefinição, quando o Operation é VerifyAccessToken, a política espera que o token de acesso seja enviado no cabeçalho Authorization como um token de portador, ou seja, com o prefixo "Bearer", seguido de um espaço em branco. Se usar o elemento AccessToken para especificar uma localização diferente para o token de acesso recebido, também pode usar este elemento, AccessTokenPrefix, para especificar um prefixo diferente e não padrão.

Por exemplo, se especificar:

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

Em seguida, a política extrai o token de acesso de entrada do cabeçalho do pedido token, desta forma: se o cabeçalho começar com a palavra "KEY" seguida de um espaço, a política remove esse prefixo e espaço e interpreta o valor restante como o token de acesso. Se o prefixo especificado não estiver presente no cabeçalho, a política gera uma falha.

Se especificar o elemento AccessToken e não especificar o elemento AccessTokenPrefix, a política interpreta todo o valor da variável especificada no elemento AccessToken como o token de acesso.

Este elemento só é eficaz quando o elemento AccessToken também é usado.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

Especifica o algoritmo de encriptação usado para assinar um token de acesso JWT. Os algoritmos RSA (RS*) usam um par de chaves pública/secreta, enquanto os algoritmos HMAC (HS*) usam um segredo partilhado. Este elemento é obrigatório para as operações GenerateJWTAccessToken, VerifyJWTAccessToken e RefreshJWTAccessToken.

Elemento <AppEndUser>

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

Nos casos em que o ID do utilizador final da app tem de ser enviado para o servidor de autorização, este elemento permite-lhe especificar onde o Apigee deve procurar o ID do utilizador final. Por exemplo, pode ser enviado como um parâmetro de consulta ou num cabeçalho HTTP.

Por exemplo, request.queryparam.app_enduser indica que o AppEndUser deve estar presente como um parâmetro de consulta, como, por exemplo, ?app_enduser=ntesla@theramin.com. Para exigir o AppEndUser num cabeçalho HTTP, por exemplo, defina este valor como request.header.app_enduser.

A disponibilização desta definição permite-lhe incluir um ID do utilizador final da app no token de acesso. Esta funcionalidade é útil se quiser poder obter ou revogar tokens de acesso OAuth 2.0 por ID do utilizador final. Para mais informações, consulte o artigo Ative a obtenção e a revogação de tokens de acesso OAuth 2.0 por ID do utilizador final, ID da app ou ambos.

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

Use este elemento para adicionar atributos personalizados a um token de acesso ou a um código de autorização. Por exemplo, pode querer incorporar um ID do utilizador ou um identificador de sessão num token de acesso que possa ser extraído e verificado no tempo de execução.

Este elemento permite especificar um valor numa variável de fluxo ou a partir de uma string literal. Se especificar uma variável e uma string, é usado o valor especificado na variável de fluxo. Se não for possível resolver a variável, a string é a predefinição.

Para mais informações sobre a utilização deste elemento, consulte o artigo Personalizar tokens e códigos de autorização.

Apresentar ou ocultar atributos personalizados na resposta

Tenha em atenção que, se definir o elemento GenerateResponse desta política como verdadeiro, a representação JSON completa do token é devolvida na resposta, incluindo quaisquer atributos personalizados que definir. Em alguns casos, pode querer ocultar alguns ou todos os seus atributos personalizados na resposta para que não fiquem visíveis para as apps cliente.

Por predefinição, os atributos personalizados aparecem na resposta. Se quiser ocultá-los, pode definir o parâmetro display como false. Por exemplo:

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

O valor do atributo display não é mantido. Suponhamos que gera um token de acesso com atributos personalizados que quer ocultar na resposta gerada. A definição de display=false cumpre esse objetivo. No entanto, se for gerada uma nova chave de acesso posteriormente através de uma chave de atualização, os atributos personalizados originais da chave de acesso são apresentados na resposta da chave de atualização. Isto acontece porque o Apigee não se lembra de que o atributo display foi originalmente definido como false na política de geração de tokens de acesso. O atributo personalizado faz simplesmente parte dos metadados do token de acesso.

Vai observar o mesmo comportamento se adicionar atributos personalizados a um código de autorização. Quando é gerado um token de acesso através desse código, esses atributos personalizados são apresentados na resposta do token de acesso. Mais uma vez, este pode não ser o comportamento pretendido.

Para ocultar atributos personalizados nestes casos, tem as seguintes opções:

• Reponha explicitamente os atributos personalizados na política de tokens de atualização e defina a respetiva apresentação como falsa. Neste caso, pode ter de obter os valores personalizados originais do token de acesso original através da política GetOAuthV2Info.
• Use uma política de JavaScript de pós-processamento para extrair manualmente quaisquer atributos personalizados que não queira ver na resposta.

Consulte também o artigo Personalizar tokens e códigos de autorização.

Elemento <CacheExpiryInSeconds>

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

Este elemento só pode ser usado com a operação VerifyAccessToken. Especifica o tempo de vida (TTL) na cache de tokens de acesso para a execução de políticas específica. A primeira vez que o Apigee valida uma chave de acesso OAuth 2, tem de obter a chave de acesso a partir de um armazenamento persistente. Esta é uma operação relativamente dispendiosa, pelo que o Apigee armazena em cache o resultado da pesquisa de tokens, incluindo o estado do token, a lista de produtos para os quais o token é válido e quaisquer atributos personalizados anexados ao token. As invocações subsequentes de OAuthV2/VerifyAccessToken até o TTL expirar vão ler o resultado em cache na memória, o que significa que a validação de tokens vai ser muito mais rápida.

O TTL predefinido para a cache de tokens de acesso é de 180 segundos. Este elemento permite-lhe reduzir o TTL, trocando assim o desempenho pela correção. Um cenário em que isto faria sentido é se, por vezes, revogar tokens e quiser reduzir o período durante o qual o Apigee continua a tratar os tokens revogados como válidos.

O intervalo suportado é entre 1 e 180 segundos. Pode fornecer uma variável de fluxo e um valor predefinido. Se fornecer uma variável de fluxo e esta contiver um valor numérico, tem precedência sobre o valor predefinido especificado.

Atributos

A tabela seguinte descreve os atributos do elemento <CacheExpiryInSeconds>

Elemento <ClientId>

<ClientId>request.formparam.client_id</ClientId>

Em vários casos, a app cliente tem de enviar o ID de cliente para o servidor de autorizações. Este elemento especifica que o Apigee deve procurar o ID do cliente na variável de fluxo request.formparam.client_id. A definição de ClientId para qualquer outra variável não é suportada. Consulte também o artigo Obtenha tokens OAuth 2.0.

Elemento <Code>

<Code>request.queryparam.code</Code>

No fluxo do tipo de concessão de autorização, o cliente tem de enviar um código de autorização para o servidor de autorização (Apigee). Este elemento permite-lhe especificar onde o Apigee deve procurar o código de autorização. Por exemplo, pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (predefinição).

A variável request.queryparam.auth_code indica que o código de autorização deve estar presente como um parâmetro de consulta, como, por exemplo, ?auth_code=AfGlvs9. Para exigir o código de autorização num cabeçalho HTTP, por exemplo, defina este valor como request.header.auth_code. Consulte também: Obtenha tokens OAuth 2.0.

Elemento<ExpiresIn>

<ExpiresIn>10000</ExpiresIn>

Aplica o tempo de validade das chaves de acesso e dos códigos de autorização em milissegundos. (Para tokens de atualização, use <RefreshTokenExpiresIn>.) O valor do tempo de expiração é um valor gerado pelo sistema mais o valor <ExpiresIn>. Se <ExpiresIn> não for especificado, o sistema aplica um valor predefinido configurado ao nível do sistema.

O tempo de expiração também pode ser definido no tempo de execução através de um valor predefinido codificado ou fazendo referência a uma variável de fluxo. Por exemplo, pode armazenar um valor de expiração do token num mapa de chave-valor, obtê-lo, atribuí-lo a uma variável e fazer referência ao mesmo na política. Por exemplo, kvm.oauth.expires_in.

O Apigee mantém as seguintes entidades na cache durante um mínimo de 180 segundos após o acesso às entidades.

• Tokens de acesso OAuth. Isto significa que o elemento ExpiresIn na política OAuth v2 não vai poder fazer expirar uma chave de acesso em menos de 180 segundos.
• Entidades do Key Management Service (KMS) (Apps, Developers, API Products).
• Atributos personalizados em tokens OAuth e entidades KMS.

A stanza seguinte especifica uma variável de fluxo e também um valor predefinido. Tenha em atenção que o valor da variável de fluxo tem precedência sobre o valor predefinido especificado.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

O Apigee não suporta uma forma de forçar a expiração de um token após a respetiva criação. Se precisar de forçar a expiração do token (por exemplo, com base numa condição), encontra uma possível solução descrita nesta publicação da comunidade do Apigee.

Por predefinição, os tokens de acesso expirados são removidos automaticamente do sistema Apigee Apigee 3 dias após a expiração. Veja também Limpar tokens de acesso

Elemento <ExternalAccessToken>

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

Indica ao Apigee onde encontrar um token de acesso externo (um token de acesso não gerado pelo Apigee).

A variável request.queryparam.external_access_token indica que o token de acesso externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_access_token=12345678. Para exigir o token de acesso externo num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_access_token. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <ExternalAuthorization>

<ExternalAuthorization>true</ExternalAuthorization>

Se este elemento for falso ou não estiver presente, o Apigee valida o client_id e o client_secret normalmente em relação ao arquivo de autorizações do Apigee. Use este elemento quando quiser trabalhar com tokens OAuth de terceiros. Para ver detalhes sobre a utilização deste elemento, consulte o artigo Usar tokens OAuth de terceiros.

Elemento <ExternalAuthorizationCode>

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Indica ao Apigee onde encontrar um código de autorização externo (um código de autorização não gerado pelo Apigee).

A variável request.queryparam.external_auth_code indica que o código de autorização externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_auth_code=12345678. Para exigir o código de autorização externa num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_auth_code. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <ExternalRefreshToken>

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Indica ao Apigee onde encontrar um símbolo de atualização externo (um símbolo de atualização não gerado pelo Apigee).

A variável request.queryparam.external_refresh_token indica que o token de atualização externo deve estar presente como um parâmetro de consulta, como, por exemplo, ?external_refresh_token=12345678. Para exigir o token de atualização externo num cabeçalho HTTP, por exemplo, defina este valor como request.header.external_refresh_token. Consulte também o artigo Usar tokens OAuth de terceiros.

Elemento <GenerateResponse>

<GenerateResponse enabled='true'/>

Se for definido como true ou se o atributo enabled for omitido, a política gera e devolve uma resposta. Por exemplo, para GenerateAccessToken, a resposta pode ser semelhante a:

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

Se for definido como false ou se o elemento <GenerateResponse> for omitido, não é enviada nenhuma resposta. Em alternativa, um conjunto de variáveis de fluxo é preenchido com valores relacionados com a função da política. Por exemplo, uma variável de fluxo denominada oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code é preenchida com o código de autorização recém-gerado. Tenha em atenção que expires_in é expresso em segundos na resposta.

Elemento <GenerateErrorResponse>

<GenerateErrorResponse enabled='true'/>

Se for definido como true, a política gera e devolve uma resposta se o atributo ContinueOnError estiver definido como verdadeiro. Se false (a predefinição), não é enviada nenhuma resposta. Em alternativa, um conjunto de variáveis de fluxo é preenchido com valores relacionados com a função da política.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

Indica à política onde encontrar o parâmetro de tipo de autorização transmitido num pedido. De acordo com a especificação OAuth 2.0, o tipo de autorização tem de ser fornecido com pedidos de chaves de acesso e códigos de autorização. A variável pode ser um cabeçalho, um parâmetro de consulta ou um parâmetro de formulário (predefinição).

Por exemplo, request.queryparam.grant_type indica que a palavra-passe deve estar presente como um parâmetro de consulta, como, por exemplo, ?grant_type=password. Para exigir o tipo de autorização num cabeçalho HTTP, por exemplo, defina este valor como request.header.grant_type. Consulte também o artigo Obtenha tokens OAuth 2.0.

Elemento <Operation>

<Operation>GenerateAuthorizationCode</Operation>

A operação OAuth 2.0 executada pela política.

Elemento <PassWord>

<PassWord>request.queryparam.password</PassWord>

Este elemento é usado apenas com o tipo de concessão de palavra-passe. Com o tipo de autorização de palavra-passe, as credenciais do utilizador (palavra-passe e nome de utilizador) têm de ser disponibilizadas à política OAuthV2. Os elementos <PassWord> e <UserName> são usados para especificar variáveis onde o Apigee pode encontrar estes valores. Se estes elementos não forem especificados, a política espera encontrar os valores (por predefinição) nos parâmetros do formulário denominados username e password. Se os valores não forem encontrados, a política gera um erro. Pode usar os elementos <PassWord> e <UserName> para fazer referência a qualquer variável de fluxo que contenha as credenciais.

Por exemplo, pode transmitir a palavra-passe num pedido de token através de um parâmetro de consulta e definir o elemento da seguinte forma: <PassWord>request.queryparam.password</PassWord>. Para exigir a palavra-passe num cabeçalho HTTP, defina este valor como request.header.password.

A política OAuthV2 não faz mais nada com estes valores de credenciais. O Apigee está simplesmente a verificar se estão presentes. É da responsabilidade do programador da API obter os valores pedidos e enviá-los a um fornecedor de identidade antes de a política de geração de tokens ser executada.

Consulte também o artigo Obtenha tokens OAuth 2.0.

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

Fornece a chave privada usada para validar ou assinar tokens de acesso formatados em JWT com um algoritmo RSA. Use o atributo ref para transmitir a chave numa variável de fluxo. Use apenas quando o valor do elemento Algorithm for um dos seguintes: RS256, RS384 ou RS512. Para mais informações, consulte o artigo Usar operações de tokens OAuth JWT.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

Especifica a chave pública ou o certificado público usado para validar a assinatura num token de acesso formatado em JWT assinado com um algoritmo RSA. Use o atributo ref para transmitir a chave/certificado numa variável de fluxo. Use apenas quando o valor do elemento Algorithm for um dos seguintes: RS256, RS384 ou RS512.

Elemento <RedirectUri>

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Especifica onde o Apigee deve procurar o parâmetro redirect_uri no pedido.

Acerca dos URIs de redirecionamento

Os URIs de redirecionamento são usados com os tipos de concessão implícita e de código de autorização. O URI de redirecionamento indica ao servidor de autorização (Apigee) para onde enviar um código de autorização (para o tipo de concessão com código de autorização) ou um token de acesso (para o tipo de concessão implícita). É importante compreender quando este parâmetro é obrigatório, quando é opcional e como é usado:

• (Obrigatório) Se um URL de retorno de chamada estiver registado na app de programador associada às chaves de cliente do pedido e se o redirect_uri estiver presente no pedido, os dois têm de corresponder exatamente. Se não corresponderem, é devolvido um erro. Para ver informações sobre o registo de apps de programadores no Apigee e a especificação de um URL de retorno de chamada, consulte o artigo Registe apps e faça a gestão das chaves da API.

• (Opcional) Se um URL de retorno de chamada estiver registado e o redirect_uri estiver em falta no pedido, o Apigee redireciona para o URL de retorno de chamada registado.
• (obrigatório) Se não estiver registado um URL de retorno de chamada, é obrigatório o redirect_uri. Tenha em atenção que, neste caso, o Apigee aceita QUALQUER URL. Esta situação pode apresentar um problema de segurança e, por isso, só deve ser usada com apps cliente fidedignas. Se as apps cliente não forem fidedignas, a prática recomendada é exigir sempre o registo de um URL de retorno de chamada.

Pode enviar este parâmetro num parâmetro de consulta ou num cabeçalho. A variável request.queryparam.redirect_uri indica que o RedirectUri deve estar presente como um parâmetro de consulta, como, por exemplo, ?redirect_uri=login.myapp.com. Para exigir o RedirectUri num cabeçalho HTTP, por exemplo, defina este valor como request.header.redirect_uri. Consulte também o artigo Obtenha tokens OAuth 2.0.

Elemento <RefreshToken>

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

Quando solicitar uma chave de acesso através de um símbolo de atualização, tem de fornecer o símbolo de atualização no pedido. Este elemento permite especificar onde o Apigee deve procurar o token de atualização. Por exemplo, pode ser enviado como um parâmetro de consulta, um cabeçalho HTTP ou um parâmetro de formulário (a predefinição).

A variável request.queryparam.refreshtoken indica que o token de atualização deve estar presente como um parâmetro de consulta, como, por exemplo, ?refresh_token=login.myapp.com. Para exigir o RefreshToken num cabeçalho HTTP, por exemplo, defina este valor como request.header.refresh_token. Consulte também o artigo Obtenha tokens OAuth 2.0.

Elemento <RefreshTokenExpiresIn>

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

Impõe o tempo de validade dos tokens de atualização em milissegundos. O valor do tempo de expiração é um valor gerado pelo sistema mais o valor de <RefreshTokenExpiresIn>. Se <RefreshTokenExpiresIn> não for especificado, o sistema aplica o valor predefinido.

O tempo de expiração também pode ser definido no tempo de execução através de um valor predefinido codificado ou fazendo referência a uma variável de fluxo. Por exemplo, pode armazenar um valor de expiração do token num mapa de chave-valor, obtê-lo, atribuí-lo a uma variável e fazer referência ao mesmo na política. Por exemplo, kvm.oauth.expires_in.

A stanza seguinte especifica uma variável de fluxo e também um valor predefinido. Tenha em atenção que o valor da variável do fluxo tem precedência sobre o valor predefinido especificado.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

Elemento <ResponseType>

<ResponseType>request.queryparam.response_type</ResponseType>

Este elemento informa o Apigee sobre o tipo de autorização que a app cliente está a pedir. É usado apenas com os fluxos do tipo de concessão implícita e de código de autorização.

Por predefinição, o Apigee procura o valor do tipo de resposta num parâmetro de consulta response_type. Se quiser substituir este comportamento predefinido, use o elemento <ResponseType> para configurar uma variável de fluxo que contenha o valor do tipo de resposta. Por exemplo, se definir este elemento como request.header.response_type, o Apigee procura o tipo de resposta a ser transmitido no cabeçalho do pedido. Consulte também o artigo Obtenha tokens OAuth 2.0.

Elemento <ReuseRefreshToken>

<ReuseRefreshToken>true</ReuseRefreshToken>

Quando definido como true, o token de atualização existente é reutilizado até expirar. Se false, o Apigee emite um novo token de atualização quando é apresentado um token de atualização válido.

Elemento <RFCCompliantRequestResponse>

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

Quando true, a política está em conformidade com as normas RFC6749 e permite os seguintes comportamentos em conformidade:

• As respostas de erro e sem erro vão incluir o campo do cabeçalho de resposta HTTP Cache-Control para agir em conformidade com a RFC2616 (Hypertext Transfer Protocol – HTTP/1.1), com um valor de no-store em qualquer resposta que contenha tokens, credenciais ou outras informações confidenciais, bem como o campo do cabeçalho de resposta Pragma com um valor de no-cache.
• A propriedade expires_in está no formato alfanumérico. Para consistência, o refresh_token_expires_in também vai ser alfanumérico.
• As respostas OAuthV2 para a geração de tokens vão incluir o campo de cabeçalho Bearer em conformidade com a RFC em vez de BearerToken.
• As mensagens de erro nos payloads de resposta vão ter o formato: {"error" : "xxx", "error_description" :"yyy"} para erros de token de atualização.

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

Fornece a chave secreta usada para validar ou assinar tokens de acesso formatados em JWT com um algoritmo HMAC. Use apenas quando o algoritmo for um de HS256, HS384 ou HS512. Use o atributo ref para transmitir a chave numa variável de fluxo. Para mais informações, consulte o artigo Usar operações de tokens OAuth JWT.

O Apigee aplica uma intensidade mínima da chave para os algoritmos HS256/HS384/HS512. O comprimento mínimo da chave para HS256 é de 32 bytes, para HS384 é de 48 bytes e para HS512 é de 64 bytes. A utilização de uma chave de menor intensidade provoca um erro de tempo de execução.

Elemento <Scope>

<Scope>request.queryparam.scope</Scope>

Se este elemento estiver presente numa das políticas GenerateAccessToken ou GenerateAuthorizationCode, é usado para especificar os âmbitos a conceder ao token ou ao código. Normalmente, estes valores são transmitidos para a política no pedido de uma app cliente. Pode configurar o elemento para receber uma variável de fluxo, o que lhe dá a opção de escolher como os âmbitos são transmitidos num pedido. No exemplo seguinte, request.queryparam.scope indica que o âmbito deve estar presente como um parâmetro de consulta, como, por exemplo, ?scope=READ. Para exigir o âmbito num cabeçalho HTTP, por exemplo, defina este valor como request.header.scope.

Se este elemento aparecer numa política "VerifyAccessToken", é usado para especificar os âmbitos que a política deve aplicar. Neste tipo de política, o valor tem de ser um nome de âmbito "codificado". Não pode usar variáveis. Por exemplo:

<Scope>A B</Scope>

Consulte também os artigos Trabalhar com âmbitos do OAuth2 e Obter tokens do OAuth 2.0.

Elemento <State>

<State>request.queryparam.state</State>

Nos casos em que a app cliente tem de enviar as informações de estado para o servidor de autorização, este elemento permite-lhe especificar onde o Apigee deve procurar os valores de estado. Por exemplo, pode ser enviado como um parâmetro de consulta ou num cabeçalho HTTP. Normalmente, o valor do estado é usado como uma medida de segurança para evitar ataques CSRF.

Por exemplo, request.queryparam.state indica que o estado deve estar presente como um parâmetro de consulta, como, por exemplo, ?state=HjoiuKJH32. Para exigir o estado num cabeçalho HTTP, por exemplo, defina este valor como request.header.state. Consulte também Obtenha tokens OAuth 2.0.

Elemento <StoreToken>

 <StoreToken>true</StoreToken>

Defina este elemento como true quando o elemento <ExternalAuthorization> for true. O elemento <StoreToken> indica ao Apigee que deve armazenar o token de acesso externo. Caso contrário, não é mantido.

<SupportedGrantTypes>/<GrantType> element

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Especifica os tipos de concessão suportados por um ponto final de token OAuth no Apigee. Um ponto final pode suportar vários tipos de concessão (ou seja, um único ponto final pode ser configurado para distribuir tokens de acesso para vários tipos de concessão). Para mais informações sobre os pontos finais, consulte o artigo Compreender os pontos finais de OAuth. O tipo de autorização é transmitido em pedidos de tokens num parâmetro grant_type

Se não forem especificados tipos de concessão suportados, os únicos tipos de concessão permitidos são authorization_code e implicit. Consulte também o elemento <GrantType> (que é um elemento de nível superior usado para especificar onde o Apigee deve procurar o parâmetro grant_type transmitido num pedido do cliente. O Apigee garante que o valor do parâmetro grant_type corresponde a um dos tipos de concessão suportados.

Elemento <Tokens>/<Token>

Usado com as operações ValidateToken e InvalidateToken. Consulte também o artigo Aprovar e revogar tokens de acesso. O elemento <Token> identifica a variável de fluxo que define a origem do token a ser revogado. Se os programadores tiverem de enviar tokens de acesso como parâmetros de consulta denominados access_token, por exemplo, use request.queryparam.access_token.

Elemento <UserName>

<UserName>request.queryparam.user_name</UserName>

Este elemento é usado apenas com o tipo de concessão de palavra-passe. Com o tipo de autorização de palavra-passe, as credenciais do utilizador (palavra-passe e nome de utilizador) têm de ser disponibilizadas à política OAuthV2. Os elementos <PassWord> e <UserName> são usados para especificar variáveis onde o Apigee pode encontrar estes valores. Se estes elementos não forem especificados, a política espera encontrar os valores (por predefinição) nos parâmetros do formulário denominados username e password. Se os valores não forem encontrados, a política gera um erro. Pode usar os elementos <PassWord> e <UserName> para fazer referência a qualquer variável de fluxo que contenha as credenciais.

Por exemplo, pode transmitir o nome de utilizador num parâmetro de consulta e definir o elemento <UserName> da seguinte forma: <UserName>request.queryparam.username</UserName>.para exigir o nome de utilizador num cabeçalho HTTP, defina este valor como request.header.username.

A política OAuthV2 não faz mais nada com estes valores de credenciais. O Apigee está simplesmente a verificar se estão presentes. É da responsabilidade do programador da API obter os valores pedidos e enviá-los a um fornecedor de identidade antes de a política de geração de tokens ser executada.

Consulte também o artigo Obtenha tokens OAuth 2.0.

Validar tokens de acesso

Assim que um ponto final de token é configurado para um proxy de API, é anexada uma política OAuthV2 correspondente que especifica a operação VerifyAccessToken ao fluxo que expõe o recurso protegido.

Por exemplo, para garantir que todos os pedidos a uma API estão autorizados, a seguinte política impõe a validação do token de acesso:

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

A política está anexada ao recurso da API a proteger. Para garantir que todos os pedidos a uma API são validados, anexe a política ao PreFlow do pedido ProxyEndpoint, da seguinte forma:

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

Os seguintes elementos opcionais podem ser usados para substituir as predefinições da operação VerifyAccessToken.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

Consulte também Validar tokens de acesso e Obter tokens OAuth 2.0.

Especificar localizações de variáveis de pedidos

Para cada tipo de concessão, a política faz suposições sobre a localização ou as informações necessárias nas mensagens de solicitação. Estas suposições baseiam-se na especificação OAuth 2.0. Se as suas apps precisarem de se desviar da especificação OAuth 2.0, pode especificar as localizações esperadas para cada parâmetro. Por exemplo, ao processar um código de autorização, pode especificar a localização do código de autorização, o ID de cliente, o URI de redirecionamento e o âmbito. Estes podem ser especificados como cabeçalhos HTTP, parâmetros de consulta ou parâmetros de formulário.

O exemplo abaixo demonstra como pode especificar a localização dos parâmetros do código de autorização necessários como cabeçalhos HTTP:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

Em alternativa, se for necessário para suportar a base de apps de cliente, pode combinar cabeçalhos e parâmetros de consulta:

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

Só é possível configurar uma localização por parâmetro.

Variáveis de fluxo

As variáveis de fluxo definidas nesta tabela são preenchidas quando as respetivas políticas OAuth são executadas e, por isso, estão disponíveis para outras políticas ou aplicações que são executadas no fluxo do proxy de API.

Operação VerifyAccessToken

Quando a operação VerifyAccessToken é executada, um grande número de variáveis de fluxo é preenchido no contexto de execução do proxy. Estas variáveis dão-lhe propriedades relacionadas com o token de acesso, a app do programador e o programador. Pode usar uma política AssignMessage ou JavaScript, por exemplo, para ler qualquer uma destas variáveis e usá-las conforme necessário mais tarde no fluxo. Estas variáveis também podem ser úteis para fins de depuração.

Variáveis específicas do token

Variáveis específicas da app

Estas variáveis estão relacionadas com a app de programador associada ao token.

Variáveis específicas do grupo de apps

As seguintes variáveis de fluxo contêm informações sobre o AppGroup para o token e são preenchidas pela política. Estes atributos AppGroup são preenchidos apenas se verifyapikey.{policy_name}.app.appType for "AppGroup".

Variáveis específicas do programador

Se o app.appType for "Programador", os atributos de programador são preenchidos.

Operação GenerateAuthorizationCode

Estas variáveis são definidas quando a operação GenerateAuthorizationCode é executada com êxito:

Prefixo: oauthv2authcode.{policy_name}.{variable_name}

Exemplo: oauthv2authcode.GenerateCodePolicy.code

Operações GenerateAccessToken e RefreshAccessToken

Estas variáveis são definidas quando as operações GenerateAccessToken e RefreshAccessToken são executadas com êxito. Tenha em atenção que as variáveis do token de atualização não se aplicam ao fluxo do tipo de concessão de credenciais de cliente.

Prefixo: oauthv2accesstoken.{policy_name}.{variable_name}

Exemplo: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

Estas variáveis são definidas quando a operação GenerateAccessTokenImplicit é executada com êxito para o fluxo do tipo de autorização implícito.

Prefixo: oauthv2accesstoken.{policy_name}.{variable_name}

Exemplo: oauthv2accesstoken.RefreshTokenPolicy.access_token

Referência de erros

Esta seção descreve os códigos de falha e as mensagens de erro que são retornadas e as variáveis de falha definidas pela Apigee quando essa política aciona um erro. Essas informações são importantes para saber se você está desenvolvendo regras de falha para lidar com falhas. Para saber mais, consulte O que você precisa saber sobre erros de política e Como lidar com falhas.

Erros de execução

Esses erros podem ocorrer quando a política é executada.

Erros de ambiente de execução específicos do token JWT

Os códigos de erro do ambiente de execução e as descrições dos fluxos de token de autenticação do JWT dependem do contexto do fluxo OAuth2:

• Se o contexto de fluxo for geração ou atualização de token, consulte Códigos de erro para fluxos de geração e atualização de tokens JWT abaixo.
• Para o fluxo de verificação de token, consulte Códigos de erro para fluxos de verificação de token abaixo.

Códigos de erro para fluxos de geração e atualização de tokens JWT

Para fluxos do OAuth2 que geram ou atualizam tokens JWT, as respostas de erro obedecem às respostas de erro especificadas em RFC6749. Para mais detalhes, consulte a Seção 5.2 Erro de resposta.

Códigos de erro para o fluxo de verificação de token

Os códigos de erro listados na tabela a seguir se aplicam apenas à operação VerifyAccessToken.

Erros na implantação

Esses erros podem ocorrer quando você implanta um proxy que contém esta política.

Erros de implantação específicos do token JWT

Esses erros de implantação são específicos às políticas que usam operações de token JWT.

Variáveis de falha

Essas variáveis são definidas quando essa política aciona um erro no ambiente de execução.

Exemplo de resposta de erro

Essas respostas serão enviadas de volta ao cliente se o elemento <GenerateResponse> for true.

Se <GenerateResponse> for true, a política retornará erros nesse formato para operações que geram tokens e códigos. Para uma lista completa, consulte a Referência de resposta de erro HTTP do OAuth.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

Se <GenerateResponse> for true, a política retornará erros nesse formato para verificar e validar operações. Para uma lista completa, consulte a Referência de resposta de erro HTTP do OAuth.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

Exemplo de regra de falha

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

Os tokens no armazenamento são hash

Se estiver a usar o Apigee hybrid ou o Apigee, os tokens de acesso OAuthV2 e os tokens de atualização são aplicados por predefinição quando armazenados na base de dados Cassandra de tempo de execução. A aplicação de hash impede a utilização dos tokens se a base de dados for comprometida.

Trabalhar com a configuração OAuth predefinida

Cada organização (mesmo uma organização de avaliação gratuita) no Apigee é aprovisionada com um ponto final do token OAuth. O ponto final está pré-configurado com políticas no proxy de API denominado oauth. Pode começar a usar o ponto final do token assim que criar uma conta no Apigee. Para mais detalhes, consulte o artigo Compreender os pontos finais do OAuth.

Limpar tokens de acesso

Por predefinição, as chaves OAuth2 são eliminadas do sistema Apigee 3 dias (259 200 segundos) após a expiração da chave de acesso e da chave de atualização (se existir).

Comportamento não conforme com a RFC

Por predefinição, a política OAuthV2, com a operação GenerateAccessToken, devolve uma resposta de token que contém determinadas propriedades não em conformidade com a RFC. A tabela seguinte mostra as propriedades não conformes devolvidas pela política OAuthV2 e as propriedades conformes correspondentes.

Além disso, a resposta de erro para um token de atualização expirado quando grant_type = refresh_token é:

{"ErrorCode" : "InvalidRequest", "Error" :"Refresh Token expired"}

No entanto, a resposta em conformidade com a RFC é:

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

Tópicos relacionados

• Introdução ao OAuth 2.0