Esta página foi traduzida pela API Cloud Translation.

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

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, 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 ao token para uma organização, será possível acessar os tokens por ID do aplicativo.

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

Por padrão, quando o Edge gera um token de acesso OAuth 2.0, o token 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 aplicativo associado ao token. Se você ativar a recuperação e a revogação dos tokens de acesso do OAuth 2.0 por ID do app, esse será o ID do app que será usado.
O campo access_token contém o valor do token de acesso do OAuth 2.0.

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 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. Você pode determinar o ID do desenvolvedor a partir do 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 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",
  "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 do app

Use as APIs abaixo para acessar os tokens OAuth por ID do usuário, 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 do app.

Etapa 1: ativar o suporte ao acesso a tokens para uma organização

Você precisa ativar o acesso ao 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 do app.

O usuário que faz a chamada a seguir precisa estar no papel orgadmin ou opsadmin da 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 OAuth 2.0 com base no ID do usuário ou do app. Para controlar o acesso, defina permissões get e put 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 terão esta aparência:

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

Use a chamada Receber permissão para a API Single Resource para saber quais papéis têm permissões no recurso /oauth2.

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

Use o seguinte comando curl para conceder ao papel opsadmin as permissões get e put para o recurso /oauth2. Substitua os values pelos valores específicos da sua 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 de get e put para o recurso /oauth2 de papéis diferentes de orgadmin e opsadmin. Substitua values pelos valores específicos da sua 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 o 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 você pode definir como achar melhor.

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 e 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 de OAuth 2.0 abaixo, chamada GenerateAccessTokenClient, gera um token de acesso do OAuth 2.0. Observe o acréscimo 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 do 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 de solicitação. Você pode transmitir informações como parte de uma solicitação de várias maneiras. Como alternativa, você pode fazer o seguinte:

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