This documentation is for WSO2 API Manager 1.9.1. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

Access tokens are used to authenticate users. They and 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.

In WSO2 API Manager the access token must be unique for the following combinations - CONSUMER_KEY, AUTHZ_USER, USER_TYPE, ?TOKEN_STATE, TOKEN_STATE_ID and TOKEN_SCOPE. The latter mentioned constraint is defined in the IDN_OAUTH2_ACCESS_TOKEN table. Therefore, it is not possible to have more than one Access Token for any of the above combinations.

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

Generating application access tokens

Tokens to authenticate an application, which is a logical collection of APIs. You to access all APIs associated with an application using a single token, and also subscribe multiple times to a single API with different SLA levels. Application access tokens leverage OAuth2 to provide simple key management.

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

  1. Log in to the API Store.
  2. Click the My Subscriptions menu, select the application from the drop-down list and click the Generate or Regenerate buttons to create and renew access tokens.

    Whenever an API call happens, the Gateway checks if the request originated from an allowed domain and grants access accordingly. You can specify these domains in the  Allowed Domains text box. This ensures that clients from a restricted domain cannot access an API even if an application key is stolen (when the key is placed in client-side JS code).

    Tip: 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. Sending this header is mandatory only if the API is restricted to certain domains. An 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:" http://localhost:8280/twitter/1.0.0/search.atom?q=cat

    In the Token Validity Text Area, you 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.

    Tip: When you generate access tokens to APIs protected by scope/s, a Select Scopes button is displayed in the My Subscriptions page for you to select the scope/s first and then generate the token to it.

Generating user access tokens

Tokens to 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 like 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.

Tip: By default, access tokens, consumer keys and consumer secrets are not encrypted in the database. An admin can enable encryption as follows.

  • Set the value of the <EncryptPersistedTokens> to true inside the <APIKeyValidator> section of the <APIM_HOME>/repository/conf/api-manager.xml file.

  • Change the <TokenPersistenceProcessor> toorg.wso2.carbon.identity.oauth.tokenprocessor.EncryptionDecryptionPersistenceProcessor in the <APIM_HOME>/repository/conf/identity.xml file.

You can configure the keypair for the RSA certificate. In <APIM_HOME>/repository/conf/carbon.xml, the Keystore is used for encryption and decryption purposes, which contains a pair of a public and private key.

See Configuring Keystores in WSO2 Products for more details.

Tip: If you want to keep authorization headers in massages that are going out from the API Gateway, an admin can go to <API Gateway Node>/repository/conf/api-manager.xml file, uncomment the <RemoveOAuthHeadersFromOutMessage> element, set its value to false and then restart the server to apply the changes.

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, refer to Renew User Tokens.

You can configure the API Manager instances to store access tokens in different tables according to their user store domain. This is referred to as user token partitioning and it ensures better security when there are multiple user stores in the system. For configuration details, see user token partitioning.

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 <ApplicationAccessTokenDefaultValidityPeriod> element in <APIM_HOME>/repository/conf/identity.xml file. Set 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.
    • 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.

  • No labels