Working with Access Tokens

When an Application Developer registers an Application on the API Store, the Application is given a consumer-key and a consumer-secret, which represents the credentials of the Application that is being registered. The consumer-key becomes the unique identifier of the Application, similar to a user's username, and is used to authenticate users. When an Access Token is issued for the Application, it is issued against the latter mentioned consumer-key.

API consumers generate access tokens and pass them in the incoming API requests. The API key (i.e., the generated access token) is a simple string that you need to pass as an HTTP header. For example, "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a." This works equally well for SOAP and REST calls.

Authorizing requests, which come to published APIs, using access tokens helps you prevent certain types of denial-of-service (DoS) attacks. If the token that is passed with a request is invalid, WSO2 API Manager (WSO2 API-M) discards that request in the first stage of processing itself.

WSO2 API Manager provides two types of access tokens for authentication:

• Application Access Tokens: Tokens to identify and authenticate an entire application. An application is a logical collection of many APIs. With a single application access token, you can invoke all of these APIs.
• User Access Tokens: Tokens to identify the final user of an application. For example, the final user of a mobile application deployed on different devices.
  
  

Let's take a look at how to generate and renew each type of access token.

• Generating application access tokens
• Generating user access tokens
• Generating access tokens per device
• Renewing application access tokens
• Renewing user access tokens

• Changing the default token expiration time

Generating application access tokens

Application access tokens are tokens that authenticate an application, which is a logical collection of APIs. You can access all APIs associated with an application using a single token, and also subscribe multiple times to a single API with different service level agreement (SLA) levels/tiers. Application access tokens leverage OAuth2 to provide simple key management.

The steps below describe how to generate/renew application access tokens:

1. Sign in to WSO2 API Store.
2. Click the Applications menu and open the application for which you want to generate an access token.

3. Click the Production Keys tab and click Generate Keys to create an application access token. You can use this token to invoke all APIs that you subscribe to using the same application.
   

   In the Access token validity period field, you can set an expiration period to determine the validity period of the token after generation. Set this to a negative value to ensure that the token never expires. Also see Changing the default token expiration time.

   Tip: When you generate access tokens to APIs protected by scope/s, you can select the scope/s and then generate the token for it.

Generating user access tokens

User access tokens are tokens that authenticate the final user of an API, and are valid for all APIs subscribed to a user via a particular application. User access tokens allow you to invoke an API even from a third-party application such as a mobile app. You generate/renew a user access token by calling the Login API through a REST client. For more information, see Token API.

<RemoveOAuthHeadersFromOutMessage>false</RemoveOAuthHeadersFromOutMessage>

Generating access tokens per device

WSO2 API Manager returns the same token repeatedly if a valid token exists for the requesting Application, on behalf of the user. However, the latter mentioned scenario becomes an issue if the same user is using the same Application in two devices (e.g., If you have two instances of the same Application running on your iPhone and iPad, and your iPhone already has a token on behalf of you, your iPad will get the same token if you requested for it within the same validity period. Therefore, if one of your devices revoke this token (e.g., revoke on logout), the token that you obtained for your other device becomes invalid as the devices use the identical tokens.

To overcome this problem, WSO2 API Manager provides a mechanism, with the use of OAuth2.0 Scopes, for obtaining a unique Access Token for each device that uses the same Application. Thereby, allowing users to request tokens for different scopes. You need to prefix the scope names with the string "device_". WSO2 API Manager uses special treatment for the scopes that are prefixed with the latter mentioned string by ignoring the usual validations it does when issuing tokens that are associated to scopes. The following is a sample cURL command that you can use to request a token with a "device_" scope.

curl -k -d "grant_type=password&username=<username>&password=<password>&scope=device_ipad" -H "Authorization :Basic base64encode(consumer-key:consumer-secret), Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

Each token request that is made with a different scope, results in a different access token being issued. For example if you received a token named abc as a result of the scope device_ipad, you will not receive abc when you request for the token with the scope device_iphone. Note that you can use device_ scopes in conjunction with other scopes as usual. 

Renewing application access tokens

When an application access token expires, consumers can refresh the token by signing into the API Store, opening the application, and clicking Re-generate that appears in the Production Keys tab.
You can also specify a token expiration time for the application access token. Set this to a negative value to ensure that the token never expires.

Renewing user access tokens

To renew a user token, issue a REST call to the WSO2 Login API through a REST client. For more information, see Token API.

Changing the default token expiration time

Access tokens have an expiration time, which is set to 60 minutes by default.

• To change the default expiration time of application access tokens,
  

  • Change the value of the <AccessTokenDefaultValidityPeriod> element in the <API-M_HOME>/repository/conf/identity/identity.xml file. Set this to a negative value to ensure that the token never expires. Changes to this value are applied only to the new applications that you create.

    Example

    <AccessTokenDefaultValidityPeriod>-3600</AccessTokenDefaultValidityPeriod>

  • Alternatively, you can set a default expiration time through the UI when generating/regenerating the application access token.
    This is explained in previous sections.

• Similarly, to change the default expiration time of user access tokens, edit the value of the <UserAccessTokenDefaultValidityPeriod> element in the <API-M_HOME>/repository/conf/identity/identity.xml file.

  Example

  <UserAccessTokenDefaultValidityPeriod>3800</UserAccessTokenDefaultValidityPeriod>

Also see Configuring Caching for several caching options available to optimize key validation.