You're viewing Apigee Edge documentation.
View Apigee X documentation.
This section describes how to enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, app ID, or both. The end user ID feature requires special setup as described in this topic. By end user, we mean the user of the app that is calling the API.
When to enable end user ID access
Sometimes, it is useful to store the user id in an access token. Enable the end user ID access feature only if you have a good use case for it. For example:
- A feature for your website or app where users can see which third-party apps they have authorized, and to provide an option to revoke access to those apps.
- A feature that allows an authorized user to revoke all access tokens associated with a specific Developer App.
About OAuth access tokens
App IDs are automatically added to an OAuth access token. Therefore, after you enable token access for an organization as described below, you can revoke 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 tokens. The procedure below describes how add an end user ID to an existing token.
By default, when Edge generates an OAuth 2.0 access token, the token has the format shown below:
{
"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"
}
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, then this is the app ID you use.
- The access_token field contains the OAuth 2.0 access token value.
There is no field for end user ID in the default OAuth access token. To enable retrieval and revocation of OAuth 2.0 access tokens by end user ID, you have to configure the OAuth 2.0 policy to include the user ID in the token, as described in the procedure below. Note that if you only want to retrieve and revoke OAuth 2.0 access tokens by app ID, then there is no need to enable access by end user ID.
You pass in the end user ID to the token creation endpoint. You can pass the end user's ID as a query parameter, form parameter, or in a header (as explained later in this topic). 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", //--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"
}
To learn how to make the API calls that perform these retrievals and revocations, see following Smart Docs:
Enabling access to OAuth 2.0 tokens by user ID and app ID
How you enable access to OAuth 2.0 tokens by user ID and app ID depends on how you deployed Edge:
Cloud-based deployment
A cloud-based deployment of Edge means that most of the configuration is handled by Apigee. You are only responsible for configuring the OAuth 2.0 policy to add the user ID to the access token. For more, see the procedure below.
Edge for Private Cloud deployment
In Apigee Edge for Private Cloud (on-premises), you are completely responsible for configuration. For more, see the Operations and Configuration.
Apigee hybrid
Access to OAuth 2.0 tokens by user ID is enabled by default. You are only responsible for configuring the OAuth 2.0 policy to add the user ID to the access token. For more, see Step 5 of the procedure below.
Enabling access in the cloud
Step 1: Enable an org to support this feature
This feature must be enabled for each org that you want to support this feature.
Contact Apigee Support to have them update your org.
Step 2: Provide oauth2 Resource Permissions to opsadmin and orgadmin Roles
Only your orgadmin and opsadmin roles should be given
permissions to make these retrieve (get) and revoke (put) calls to the
oauth2 resource based on end user ID or app ID.
You can use the Get Permission
for a Resource API call to see which roles have get and put
permissions for the oauth2 resource.
If you need to add or remove any permissions, contact Apigee Support to have them perform the updates.
Step 3: Copy existing OAuth 2.0 access tokens to your Cassandra nodes
Performed by Apigee Support: In this task, copies of existing OAuth 2.0 access tokens in impacted orgs will be copied and stored in your Cassandra nodes. This procedure will be performed on the Cassandra nodes for each of your Apigee Edge pods. This will allow the retrieve and revoke API calls to run against all of your OAuth 2.0 access tokens, existing and newly generated.
Step 4: Add the oauth_max_search_limit property to your management server and message processor
In this task, the keymanagement.properties files for your management server and
message processor will be updated to include this property: oauth_max_search_limit =
100. 100 is Apigee's recommended value, but can be set as you see fit.
Contact Apigee Support to have them make this addition.
Step 5: Configure an OAuth 2.0 policy to generate access tokens that include end user IDs
Configure the OAuth 2.0 policy used to generate access tokens to include end user ID in the token. By including end user IDs in access tokens, you will then be able to perform retrievals and revokes by end user ID.
To configure the policy to include an end user ID in an access token, you must specify the input variable that contains the end user ID. Use the <AppEndUser> tag to specify the variable.
The OAuth 2.0 policy below, named GenerateAccessTokenClient, generates an OAuth 2.0 access token. Note the addition of the <AppEndUser> tag in bold:
<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=k3nJyFJIA3p62TKIkLO6OJNi87GYXFmP&client_secret=gk58jK5lIp943AY4'
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