Child pages
  • Generate Access Tokens to Authenticate APIs
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Next »

An access token is a simple string that is passed as an HTTP header of a request. For example, "Authorization: Bearer NtBQkXoKElu0H1a1fQ0DWfo6IX4a." Access tokens authenticate API users and applications, and ensure better security (e.g., prevent DoS attacks). If a token that is passed with a request is invalid, the request is discarded in the first stage of processing. Access tokens work equally well for SOAP and REST calls.

There are two types of access tokens:

  • 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.
  • User Access Tokens : Tokens to authenticate the final user of an API, such as the final user of a mobile application deployed on different devices.

The sections below show how to generate and renew each type of access token:

Generating application access tokens

The steps below describe how to generate application access tokens:

  1. Log in to the API Store.
  2. Click My Subscriptions from the menu bar at the top of the screen. The Subscriptions page opens, using which you can generate a production key and/or a sandbox key for testing purpose.

    The two inputs mean the following:

    Allowed DomainsIf you associate a set of domains in a comma separated list, only requests from those domains will be allowed. Others will be restricted. Whenever an API call happens, the Gateway checks if the request originated from an allowed domain and grants access accordingly. This ensures that clients 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). Leave this field blank or put All to allow all domains.

    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. 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

    Sending this header is mandatory only if the API is restricted to certain domains.
    Token Validity Text AreaSet a period in which the token will be expired after generation. Set to a negative value to ensure that the token never expires.

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.

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 <APIKeyManager> section of the <APIM_HOME>/repository/conf/api-manager.xml file.

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

If you want to keep authorization headers in massages that are going out of 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, see 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 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.

  • No labels