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
- Revoke OAuth 2.0 Access Token by End User ID or App ID
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 values 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 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 and Delete Permission for Resource 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 values 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 values 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
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