Working with Access Tokens

Access tokens are used to authenticate users to invoke an API. Access tokens are generated by API consumers and need to be passed in the incoming API requests. The API key (i.e., the generated access token) is a simple string that is passed as an HTTP header. For example, "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a." It works equally well for SOAP and REST calls.

Authorizing requests coming to published APIs using access tokens helps you prevent DoS attacks. If the token passed with a request is invalid, the API Manager discards that requests 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 in detail.

• Generating application access tokens
• Restricting access to specific domains
• Generating user access tokens
• Renewing application access tokens
• Renewing user access tokens

• Changing the default token expiration time

Generating application access tokens

Application access tokens are generated at the application level and valid for all APIs associated with an application. This allows you to access multiple APIs with a single token and also subscribe multiple times to a single API with different SLA levels. It leverages OAuth2 to provide a simple, easy-to-use key management mechanism. Following steps describe how to generate application access tokens.

1. Log in to the API Store (https://<hostname>:9443/store).
2. Click My Subscriptions from the menu bar at the top of the screen. The Subscriptions page opens with the following options:
   
   Generate button: Use the Generate button associated with each type of key to generate an access token. It generates an application key and also a consumer key and a consumer secret. For testing purposes, you also can create a sandbox key.
   
   Allowed Domains Text Area: Allows you to associate a set of domains, as a comma separated list, to a token. API Gateway allows requests to the APIs from those domains only. Others will be restricted. Leave this field blank to allow all domains.

   With this allowed domains feature, a client from a different domain cannot access an API even if an application key is stolen (when the key is placed in client side JS code). Whenever an API call happens, the Gateway checks if the request originated from an allowed list of domains. This is the same solution done in Google Maps.
   
   

   When the client makes a request to an API that is only allowed to some domains, the request message must have an HTTP header to specify its domain name. APIM admin can configure this header name using <ClientDomainHeader> element under the <APIGateway> element in <APIM_HOME>/repository/conf/api-manager.xml. For example, if the file contains <ClientDomainHeader>domain</ClientDomainHeader>, then the API invocation request must contain an HTTP header called domain with values as shown in the example below:
   curl -v -H "Authorization: Bearer xxx" -H "domain: wso2.com" http://localhost:8280/twitter/1.0.0/search.atom?q=cat
   
   Sending this header is mandatory only if the API is restricted to certain domains.
   
   Token Validity Text Area: Set a period in which the token will be expired after generation. Set to a negative value to ensure that the token never expires. Also see Changing the default token expiration time.

Generating user access tokens

User access tokens are generated at user-level and valid for all APIs subscribed to a user. User-level tokens allow users to invoke an API even from a third-party application like a mobile app. You can generate a user-level token by calling the API Manager Login API through a REST client. For more information on generating user-level tokens, refer to Token APIs.

After an access token is generated, users sometimes want to renew the old token due to expiration or security concerns. API Consumers can re-generate/refresh access tokens in the following ways.

Renewing application access tokens

When an application access token expires, consumers can refresh the token by logging into API Store, selecting the My Subscriptions link at the top of the screen, and clicking Re-generate. You can also specify a token expiration time for the application access token or change its allowed domains. Set to a negative value to ensure that the token never expires.

Renewing user access token

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

Changing the default token expiration time

Access Tokens have a expiration time, which is set to 60 minutes by default.

• To change the default expiration time of application access tokens,
  
  • Change the value of <ApplicationAccessTokenDefaultValidityPeriod> element in <APIM_HOME>/repository/conf/identity.xml file. Set to a negative value to ensure that the token never expires.
  • 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 <UserAccessTokenDefaultValidityPeriod> element in identity.xml file.

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

After subscribing to an API and generating a key to access it, the next step is to invoke the API through the Gateway using the steps given in section Invoking APIs.