com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

User Tokens

Owned by Former user (Deleted)
Last updated: Mar 28, 2013Version comment
4 min read

User tokens are required to subscribe to and invoke APIs. This section contains the following information:

Generate User Tokens

There are two ways to generate a user token.

  • Using the API Manager console
  • Using the API Manager login API

Instructions to generate a user token and invoke APIs through the management console can be found in section Subscribing to an API. In addition to that, when users want to invoke an API in the API Gateway through a third-party application like a mobile app, they can do so by calling the API Manager login API which comes bundled with WSO2 API Manager by default, through a selected REST client. It provides the base64 encoded string of the comsumer-key:consumer-secret combination. 

Prerequisites

Before using the Login API to generate a user token, ensure the following requirements are satisfied.

  • A valid user account in the API Store. Refer to Signup to API Store.
  • A valid consumer key and consumer secret. Initially, these keys must be generated through the management console. Refer to Subscribing to an API for instructions. It shows how to generate the necessary keys by clicking the 'Generate' link on 'My Subscriptions' page.
  • A running API Gateway instance (typically an API Manager instance is running). For instruction on API Gateway, refer to section API Manager Components.

Invoking API Manager Login API to Generate User Tokens   

1. Combine the consumer key and consumer secret keys in the format 'consumer-key:consumer-secret' and encode the combined string using base64. Encoding to base64 can be done using the URL: http://base64encode.org.

An example consumer key and secret combination is as follows: wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue.

2. Access the Login API by using a REST client such as the WSO2 REST Client or Curl, with the following parameters.

  • Assuming that both the client and the API Gateway are run on the same server, the Login API url is https://localhost:8243/login.
  • payload - "grant_type=password&username=<username>&password=<password>&scope=PRODUCTION". Replace the <username> and <password> values as appropriate.
  • headers - Authorization :Basic <base64 encoded string>, Content-Type: application/x-www-form-urlencoded. Replace the <base64 encoded string> as appropriate.          

For example, the following cURL command can be used to access the Login API. It generates two tokens for the user as an access token and a refresh token. The refresh token can be used at the time a token is renewed as explained in the next section.

curl -k -d "grant_type=password&username=<username>&password=<password>&scope=PRODUCTION" -H "Authorization :Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh, Content-Type: application/x-www-form-urlencoded" https://localhost:8243/login

Renew User Tokens

After an access token is generated, users sometimes may have to refresh or renew the old token due to expiration or security concerns. This can be done by issuing a REST call to WSO2 Login API through a REST client such as the WSO2 REST Client or Curl, with the following parameters.

  • Assuming that both the client and the API Gateway are run on the same server, the Login API url is https://localhost:8243/login.
  • payload - "grant_type=refresh_token&refresh_token=<retoken>&scope=PRODUCTION". Replace the <retoken> value with the refresh token generated in the previous section.
  • headers - Authorization :Basic <base64 encoded string>, Content-Type: application/x-www-form-urlencoded. Replace the <base64 encoded string> as appropriate.          

For example, the following cURL command can be used to access the Login API.

curl -k -d "grant_type=refresh_token&refresh_token=<retoken>&scope=PRODUCTION" -H "Authorization :Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh, Content-Type: application/x-www-form-urlencoded" https://localhost:8243/login

The REST message will grant the user a renewed user token.

User Token Partitioning

WSO2 API Manager instances can be configured 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 configured in the system. For information on configuring multiple user stores, refer to section Multiple User Store Configuration.

To enable user token partitioning, the <EnableAssertions> and <AccessTokenPartitioning> elements need to be changed in $AM_HOME/repository/conf/api-manager.xml and $AM_HOME/repository/conf/identity.xml files.

<EnableAssertions>

Assertions are used to embed parameters into access tokens, so that a strong access token can be generated. Also, those parameters can be used later for further processing functionality. Currently we only have the UserName as assertion as follows.

<EnableAssertions>
        <UserName>false</UserName>
</EnableAssertions>

By default assertions are set to false. By setting <UserName> assertion to true, you can add a user name to an access token when generating the key. This can be verified by Base64 decoding the retrieved access token.

<AccessTokenPartitioning>

This parameter implies whether we need to store the keys in different tables or not. It can be used only if <UserName> assertion is enabled. Next, set <EnableAccessTokenPartitioning> to true to store the keys in different tables.

<EnableAccessTokenPartitioning>false</EnableAccessTokenPartitioning>

Also set the user store domain names and mappings to new table names. For example, if userId = foo.com/admin where  'foo.com' is the user store domain name, then a 'mapping:domain' combo can be defined as 'A:foo.com'. 'A' is the mapping for the table which stores tokens relevant to users coming from 'foo.com' user store. In this case, the actual table name is 'IDN_OAUTH2_ACCESS_TOKEN_A'. We use a mapping simply to prevent any issues caused by lengthy tables names when lengthy domain names are used.

You can provide multiple mappings separated by commas as follows:

<AccessTokenPartitioningDomains>A:foo.com, B:bar.com</AccessTokenPartitioningDomains>

According to the information given above, change the following section under <APIKeyManager> element in the api-manager.xml file.

api-manager.xml
<!-- Assertions can be used to embedd parameters into access token.-->
<EnableAssertions>
     <UserName>false</UserName>
</EnableAssertions>

<!-- This should be set to true when using multiple user stores and keys should saved into different tables according to the user store. By default all the application keys are saved in to the same table. UserName Assertion should be 'true' to use this.-->
<AccessTokenPartitioning>
     <EnableAccessTokenPartitioning>false</EnableAccessTokenPartitioning>
     <!-- user store domain names and mappings to new table names. eg: if you provide 'A:foo.com', foo.com should be the user store domain   
     name and 'A' represent the relavant mapping of token storing table, i.e. tokens relevant to the users comming from foo.com user store     
     will be added to a table called IDN_OAUTH2_ACCESS_TOKEN_A. --> 
     <AccessTokenPartitioningDomains><!-- A:foo.com, B:bar.com --></AccessTokenPartitioningDomains>
</AccessTokenPartitioning>

The sections under <OAuth> element in the identity.xml file should also be changed accordingly.

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.