Ativar recuperação e revogação de tokens de acesso do OAuth 2.0 por ID do usuário final, ID do aplicativo ou ambos

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

Esta seção descreve como ativar a recuperação e a revogação de tokens de acesso do OAuth 2.0 por ID do usuário final, ID do aplicativo ou ambos. O recurso ID do usuário final requer uma configuração especial, conforme descrito neste tópico. O usuário final significa o usuário do aplicativo que está chamando a API.

Quando ativar o acesso ao ID do usuário final

Às vezes, é útil armazenar o ID do usuário em um token de acesso. Ative o recurso de acesso ao ID do usuário final somente se você tiver um bom caso de uso. Por exemplo:

  • Um recurso do seu site ou app em que os usuários podem ver quais apps de terceiros autorizaram e fornecer uma opção para revogar o acesso a esses apps.
  • Um recurso que permite que um usuário autorizado revogue todos os tokens de acesso associados a um app do desenvolvedor específico.

Sobre os tokens de acesso do OAuth

Os IDs de aplicativo são adicionados automaticamente a um token de acesso do OAuth. Portanto, depois de ativar o acesso ao token para uma organização, conforme descrito abaixo, é possível revogar os tokens de acesso pelo ID do aplicativo.

Para recuperar e revogar tokens de acesso do OAuth 2.0 pelo ID do usuário final, um ID do usuário final precisa estar presente nos tokens de acesso. O procedimento abaixo descreve como adicionar um ID de usuário final a um token atual.

Por padrão, quando o Edge gera um token de acesso OAuth 2.0, o token tem o formato mostrado abaixo:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Observe o seguinte:

  • O campo application_name contém o UUID do app associado ao token. Se você ativar a recuperação e revogação dos tokens de acesso do OAuth 2.0 por ID do aplicativo, este será o ID do aplicativo que você usa.
  • O campo access_token contém o valor do token de acesso do OAuth 2.0.

Não há nenhum campo para o ID do usuário final no token de acesso padrão do OAuth. Para ativar a recuperação e a revogação de tokens de acesso do OAuth 2.0 por ID do usuário final, configure a política do OAuth 2.0 de modo a incluir o ID do usuário no token, conforme descrito no procedimento abaixo. Se você quer apenas recuperar e revogar tokens de acesso do OAuth 2.0 por ID do aplicativo, não é necessário ativar o acesso pelo ID do usuário final.

Você transmite o ID do usuário final para o endpoint de criação do token. Você pode transmitir o ID do usuário final como parâmetro de consulta, parâmetro de formulário ou em um cabeçalho (conforme explicado posteriormente neste tópico). Depois de configurar o Edge para incluir o usuário final no token, ele será incluído como o campo app_enduser, conforme mostrado abaixo:

{
 "issued_at" : "1421847736581",
 "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
 "scope" : "READ",
 "app_enduser" : "6ZG094fgnjNf02EK",
 "status" : "approved",
 "api_product_list" : "[PremiumWeatherAPI]",
 "expires_in" : "3599", //--in seconds
 "developer.email" : "tesla@weathersample.com",
 "organization_id" : "0",
 "token_type" : "BearerToken",
 "client_id" : "k3nJyFJIA3p62DWOkLO6OJNi87GYXFmP",
 "access_token" : "7S22UqXGJDTuUADGzJzjXzXSaGJL",
 "organization_name" : "myorg",
 "refresh_token_expires_in" : "0", //--in seconds
 "refresh_count" : "0"
}

Para saber como fazer as chamadas de API que realizam essas recuperações e revogações, consulte Smart Docs:

Como ativar o acesso aos tokens OAuth 2.0 por ID do usuário e do aplicativo

A forma de ativação do acesso aos tokens OAuth 2.0 por ID do usuário e do app depende da implantação Borda:

  • Implantação baseada na nuvem

    Uma implantação baseada na nuvem do Edge significa que a maior parte da configuração é gerenciada pela Apigee. Você só é responsável por configurar a política do OAuth 2.0 para adicionar o ID do usuário ao token de acesso. Para mais informações, consulte o procedimento abaixo.

  • Edge para implantação de nuvem privada

    No Apigee Edge para nuvem privada (local), você é totalmente responsável configuração do Terraform. Para mais informações, consulte a página Operações e Configuração.

  • Apigee híbrida

    O acesso aos tokens OAuth 2.0 pelo ID do usuário é ativado por padrão. Você só é responsável por configurar a política do OAuth 2.0 para adicionar o ID do usuário ao token de acesso. Para mais informações, consulte a Etapa 5 do procedimento abaixo.

Como ativar o acesso na nuvem

Etapa 1: permitir que uma organização ofereça suporte a este recurso

Este recurso precisa ser ativado para cada organização em que você queira oferecer suporte a esse recurso.

Entre em contato com o suporte do Apigee Edge para atualizar sua organização.

Etapa 2: fornecer permissões de recurso do OAuth2 para papéis de opsadmin e orgadmin

Somente os papéis orgadmin e opsadmin podem receber permissões para fazer essas chamadas para recuperar (get) e revogar (put) ao oauth2 com base no ID do usuário final ou do aplicativo.

Você pode usar a chamada da API Receber permissão para um recurso para ver quais papéis têm as permissões get e put para o recurso oauth2.

Se você precisar adicionar ou remover permissões, entre em contato com o suporte do Apigee Edge para peça para ele fazer as atualizações.

Etapa 3: copiar os tokens de acesso do OAuth 2.0 atuais para os nós do Cassandra

Realizada pelo suporte da Apigee: nesta tarefa, as cópias dos tokens de acesso atuais do OAuth 2.0 nas organizações afetadas serão copiadas e armazenadas nos nós do Cassandra. Este procedimento será realizada nos nós do Cassandra para cada um dos pods do Apigee Edge. Com isso, será possível recuperar e revogar chamadas de API que sejam executadas em todos os tokens de acesso do OAuth 2.0, atuais e recém-gerados.

Etapa 4: adicionar a propriedade oauth_max_search_limit ao servidor de gerenciamento e ao processador de mensagens

Nesta tarefa, os arquivos keymanagement.properties do servidor de gerenciamento e do processador de mensagens serão atualizados para incluir essa propriedade: oauth_max_search_limit = 100. 100 é o valor recomendado pela Apigee, mas pode ser definido conforme adequado.

Entre em contato com o suporte do Apigee Edge para solicitar que eles façam essa adição.

Etapa 5: configurar uma política do OAuth 2.0 para gerar tokens de acesso que incluam IDs de usuário final

Configure a política do OAuth 2.0 usada para gerar tokens de acesso para incluir o ID do usuário final no token. Ao incluir IDs de usuário final nos tokens de acesso, você conseguirá executar recuperações e revogações por ID de usuário final.

Para configurar a política para incluir um ID de usuário final em um token de acesso, especifique a variável de entrada que contém o ID do usuário final. Use a tag <AppEndUser> para especificar a variável.

A política do OAuth 2.0 abaixo, chamada GenerateAccessTokenClient, gera um token de acesso do OAuth 2.0. Observe a inclusão da tag <AppEndUser> em negrito:

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GenerateAccessTokenClient">
  <DisplayName>OAuth 2.0.0 1</DisplayName>
  <ExternalAuthorization>false</ExternalAuthorization>
  <Operation>GenerateAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <GrantType>request.queryparam.grant_type</GrantType>
  <AppEndUser>request.header.appuserID</AppEndUser>
  <ExpiresIn>960000</ExpiresIn>
</OAuthV2>

Em seguida, use o seguinte comando cURL para gerar o token de acesso do OAuth 2.0, passando o ID do usuário como o cabeçalho appuserID:

curl -H "appuserID:6ZG094fgnjNf02EK" /
  https://myorg-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials /
  -X POST /
  -d 'client_id=k3nJyFJIA3p62TKIkLO6OJNi87GYXFmP&client_secret=gk58jK5lIp943AY4'

Neste exemplo, o appuserID é passado como um cabeçalho de solicitação. Há muitas maneiras de transmitir informações como parte de uma solicitação. Por exemplo, como alternativa, você pode:

  • Use uma variável de parâmetro de formulário: request.formparam.appuserID
  • Usar uma variável de fluxo que fornece o ID do usuário final