> [!CAUTION]
> **Caution:** This documentation covers Edge for Private Cloud 4.50.00, which is no longer supported. Google does not provide security patches, bug fixes, or technical support for this version. The current supported version is 4.54.00. See the [Edge for Private Cloud documentation](https://docs.apigee.com/private-cloud/latest/overview) for the current version, or [All versions](https://docs.apigee.com/private-cloud/versions) to compare releases.

This document describes how to enable retrieval and revocation of OAuth 2.0 access tokens by
end user ID, app ID, or both.

App IDs are automatically added to an OAuth access token. Therefore, after you use the
procedure below to enable token access for an organization, you can access tokens by app ID.

To retrieve and revoke OAuth 2.0 access tokens by end user ID, an end user ID must be present
in the access token. The procedure below describes how add an end user ID to an existing token or
to new tokens.

By default, when Edge generates an OAuth 2.0 access token, the token has the format:

```
{
  "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"
}
```

Note the following:

- The `application_name` field contains the UUID of the app associated with the token. If you enable retrieval and revocation of OAuth 2.0 access tokens by app ID, this is the app ID you use.
- The `access_token` field contains the OAuth 2.0 access token value.

To enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, configure the
OAuth 2.0 policy to include the user ID in the token, as described in the procedure below.

The end user ID is the string that Edge uses as the developer ID, not the developer's email
address. You can determine the developer's ID from the developer's email address by using the Get
Developer API call.

After you configure Edge to include the end user ID in the token, it is included as the
app_enduser field, as shown below:

```
{
  "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 to retrieve and revoke
OAuth 2.0 access tokens by user ID and app ID

Use the following APIs to access OAuth tokens by user ID, app ID, or both:

- [Get OAuth 2.0
  Access Token by End User ID or App ID](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/oauth2/search)
- [Revoke OAuth 2.0
  Access Token by End User ID or App ID](https://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/oauth2/revoke)

## Procedure for enabling token access

Use the following procedure to enable retrieval and revocation of OAuth 2.0 access tokens by
end user ID and app ID.

### Step 1:
Enable token access support for an organization

You must enable token access for each organization separately. Call the PUT API below for each
organization on which you want to enable the retrieval and revocation of OAuth 2.0 access tokens
by end user ID or app ID.

The user making the following call must be in the role **orgadmin** or
`opsadmin` for the organization. Replace the <var translate="no">values</var> with your org-specific
values:

```
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
```

### Step
2: Set permissions for opsadmin role in the organization

Only the `orgadmin` and `opsadmin` roles in an organization
should be given permissions to retrieve (HTTP GET) and revoke (HTTP PUT) OAuth 2.0 tokens based
on user ID or app ID. To control access, set get and put permissions on the /oauth2 resource for
an organization. That resource has a URL in the form:

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

The `orgadmin` role should already have the necessary permissions. For the
`opsadmin` role for the /oauth2 resource, the permissions should look like
this:

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

You can use the [Get
Permission for a Single Resource API](https://docs.apigee.com/management/apis/get/organizations/%7Borg_name%7D/userroles/%7Brole_name%7D/permissions) call to see which roles have permissions for the
`/oauth2` resource.

Based on the response, you can use the [Add
Permissions for Resource to a Role](https://docs.apigee.com/management/apis/post/organizations/%7Borg_name%7D/userroles/%7Brole_name%7D/permissions) and [Delete Permission for Resource](https://docs.apigee.com/management/apis/delete/organizations/%7Borg_name%7D/userroles/%7Brole_name%7D/permissions/%7Bpermission%7D) API calls to make any necessary adjustments to the /oauth2
resource permissions.

Use the following `curl` command to give the `opsadmin` role
`get` and `put` permissions for the `/oauth2` resource. Replace
the <var translate="no">values</var> with your org-specific values:

```
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 the following `curl` command to revoke `get` and `put`
permissions for the `/oauth2` resource from roles other than
`orgadmin` and `opsadmin`. Replace the <var translate="no">values</var> with your
org-specific values:

```
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
```

### Step 3: Set
the oauth_max_search_limit property

Ensure that the `conf_keymanagement_oauth_max_search_limit`
property in `/opt/apigee/customer/application/management-server.properties`
file is set to 100:

```
conf_keymanagement_oauth_max_search_limit = 100
```

If this file does not exist, create it.

This property sets the page size used when fetching tokens. Apigee recommends a value of 100,
but you can set it as you see fit.

On a new installation, the property should be already set to 100. If you have to change the
value of this property, restart the Management Server and Message Processor by using the
commands:

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

### Step 4: Configure the OAuth 2.0 policy that generates tokens to include end user ID

> [!NOTE]
> **Note:** This task is optional. You only need to perform it if you want to retrieve and revoke OAuth 2.0 access tokens by end user ID.

Configure the OAuth 2.0 policy used to generate access tokens to include the end user ID in
the token. By including end user IDs in the access token, you can retrieve and revoke tokens by
ID.

To configure the policy to include an end user ID in an access token, the request that creates
the access token must include the end user ID and you must specify the input variable that
contains the end user ID.

The OAuth 2.0 policy below, named GenerateAccessTokenClient, generates an OAuth 2.0 access
token. Note the addition of the `<AppEndUser>` tag in bold that specifies
the variable containing the end user ID:

```
<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>
```

You can then use the following `curl` command to generate the OAuth 2.0 access
token, passing the user ID as the `appuserID` header:

```
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'
```

In this example, the `appuserID` is passed as a request header. You can pass
information as part of a request in many ways. For example, as an alternative, you can:

- Use a form parameter variable: `request.formparam.appuserID`
- Use a flow variable providing the end user ID