Ativar o acesso a tokens OAuth 2.0 por ID do usuário e ID do aplicativo

Edge para nuvem privada v4.19.01

Neste documento, descrevemos 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 app ou ambos.

Os IDs de aplicativo são adicionados automaticamente a um token de acesso do OAuth. Portanto, depois de usar o procedimento abaixo para ativar o acesso a tokens para uma organização, será possível acessar tokens por ID do app.

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

Por padrão, quando o Edge gera um token de acesso do OAuth 2.0, ele tem o seguinte formato:

{
  "issued_at" : "1421847736581",
  "application_name" : "a68d01f8-b15c-4be3-b800-ceae8c456f5a",
  "scope" : "READ",
  "status" : "approved",
  "api_product_list" : "[PremiumWeatherAPI]",
  "expires_in" : "3599",
  "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",
  "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 a revogação de tokens de acesso do OAuth 2.0 por ID do app, esse será o ID do app que você vai usar.
  • O campo access_token contém o valor do token de acesso do OAuth 2.0.

Para permitir 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 para incluir o ID do usuário no token, conforme descrito no procedimento abaixo.

O ID do usuário final é a string que o Edge usa como ID do desenvolvedor, não o endereço de e-mail do desenvolvedor. É possível determinar o ID do desenvolvedor pelo endereço de e-mail dele usando a chamada de API Get Developer.

Depois de configurar o Edge para incluir o ID do usuário final no token, ele é 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",
  "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",
  "refresh_count" : "0"
}

APIs para recuperar e revogar tokens de acesso do OAuth 2.0 por ID do usuário e ID do app

Use as APIs a seguir para acessar tokens OAuth por ID do usuário, ID do app ou ambos:

Procedimento para ativar o acesso ao token

Use o procedimento a seguir para ativar a recuperação e a revogação de tokens de acesso do OAuth 2.0 por ID do usuário final e ID do aplicativo.

Etapa 1: ativar o suporte ao acesso por token para uma organização

É necessário ativar o acesso por token para cada organização separadamente. Chame a API PUT abaixo para cada organização em que você quer ativar a recuperação e a revogação de tokens de acesso do OAuth 2.0 por ID do usuário final ou ID do app.

O usuário que faz a chamada a seguir precisa ter o papel orgadmin ou opsadmin na organização. Substitua values pelos valores específicos da sua organização:

curl -H "Content-type:text/xml" -X POST \
  https://management_server_IP;:8080/v1/organizations/org_name \
  -d '<Organization name="org_name">
      <Properties>
        <Property name="features.isOAuthRevokeEnabled">true</Property>
        <Property name="features.isOAuth2TokenSearchEnabled">true</Property>
      </Properties>
    </Organization>' \
  -u USER_EMAIL:PASSWORD

Etapa 2: definir permissões para o papel opsadmin na organização

Somente os papéis orgadmin e opsadmin em uma organização precisam receber permissões para recuperar (HTTP GET) e revogar (HTTP PUT) tokens do OAuth 2.0 com base no ID do usuário ou do app. Para controlar o acesso, defina as permissões de recebimento e envio no recurso /oauth2 de uma organização. Esse recurso tem um URL no formato:

https://management_server_IP:8080/v1/organizations/org_name/oauth2

O papel orgadmin já deve ter as permissões necessárias. Para o papel opsadmin do recurso /oauth2, as permissões precisam ser as seguintes:

<ResourcePermission path="/oauth2">
  <Permissions>
    <Permission>get</Permission>
    <Permission>put</Permission>
  </Permissions>
</ResourcePermission>

Use a chamada Get Permission for a Single Resource API para ver quais papéis têm permissões para o recurso /oauth2.

Com base na resposta, use as chamadas de API Adicionar permissões de recurso a um papel e Excluir permissão de recurso para fazer os ajustes necessários nas permissões do recurso /oauth2.

Use o seguinte comando curl para conceder ao papel opsadmin as permissões get e put para o recurso /oauth2. Substitua values pelos valores específicos da organização:

curl -X POST -H 'Content-type:application/xml' \
  http://management_server_IP:8080/v1/organizations/org_name/userroles/opsadmin/permissions \
  -d '<ResourcePermission path="/oauth2">
      <Permissions>
        <Permission>get</Permission>
        <Permission>put</Permission>
      </Permissions>
    </ResourcePermission>' \
  -u USEREMAIL:PASSWORD

Use o seguinte comando curl para revogar as permissões get e put para o recurso /oauth2 de papéis que não sejam orgadmin e opsadmin. Substitua values pelos valores específicos da organização:

curl -X DELETE -H 'Content-type:application/xml' \
  http://management_server_IP:8080/v1/organizations/org_name/userroles/roles/permissions \
  -d '<ResourcePermission path="/oauth2">
      <Permissions></Permissions>
    </ResourcePermission>' \
   -u USEREMAIL:PASSWORD

Etapa 3: definir a propriedade oauth_max_search_limit

Verifique se a propriedade conf_keymanagement_oauth_max_search_limit no arquivo /opt/apigee/customer/application/management-server.properties está definida como 100:

conf_keymanagement_oauth_max_search_limit = 100

Se esse arquivo não existir, crie-o.

Essa propriedade define o tamanho da página usado ao buscar tokens. A Apigee recomenda um valor de 100, mas é possível definir o valor que você quiser.

Em uma nova instalação, a propriedade já deve estar definida como 100. Se você precisar alterar o valor dessa propriedade, reinicie o servidor de gerenciamento e o processador de mensagens usando os comandos:

/opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Etapa 4: configurar a política do OAuth 2.0 que gera tokens para incluir o ID do 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 no token de acesso, é possível recuperar e revogar tokens por ID.

Para configurar a política para incluir um ID de usuário final em um token de acesso, a solicitação que cria o token de acesso precisa incluir o ID do usuário final, e você precisa especificar a variável de entrada que contém o ID do usuário final.

A política do OAuth 2.0 abaixo, chamada GenerateAccessTokenClient, gera um token de acesso do OAuth 2.0. Observe a adição da tag <AppEndUser> em negrito que especifica a variável que contém o ID do usuário final:

<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 OAuth 2.0, transmitindo 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=k3nJyFJIA3p62TKIkLO6OJNXFmP&client_secret=gk5K5lIp943AY4'

Neste exemplo, o appuserID é transmitido como um cabeçalho da solicitação. É possível transmitir informações como parte de uma solicitação de várias maneiras. 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