Page History

Token APIs can be used to generate and renew user access tokens. Users need access tokens to identify and invoke APIs subscribed under an application. User tokens are passed in the HTTP header when invoking APIs. Let's take a look at how to generate, authorize and renew access tokens.

• Generate user tokens
• Generate authorization code
• Renew user tokens
• Revoke access tokens

...

Generating user tokens

Anchor
Generating Generating

You can use the Login Token API to invoke an API through a third-party application like a mobile app. The Login Token API comes bundled with the API Manager by default. It provides the base64 requires the base64 encoded string of the comsumerconsumer-key:consumer-secret combination. 

For instructions to generate an application-level access token from the API Store, see Generating Working with Access Tokens to Invoke APIs.

Prerequisites

You need the following before using the Login Token API to generate a user token.

• A valid user account in the API Store. See Signing - up to API Store.
  
• A valid consumer key and consumer secret. Initially, these keys must be generated through the management console by clicking the Generate link on My Subscriptions page. You can find more details in Generating Working with Access Tokens to Invoke APIs.
  
• A running API Gateway instance (typically an API Manager instance should be running). For instruction on API Gateway, refer to section Architecture Components.
  

Invoking

...

Token API to generate user tokens 

Anchor
GenerateToken GenerateToken

 

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.
   Here's an example consumer key and secret combination : wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue.
2. Access the Login Token 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 token API url is https://localhost:8243/login.token
   • 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, use the following cURL command to access the Login Token API. It generates two tokens as an access token and a refresh token. You can use the refresh token at the time a token is renewed .

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

   Note

   The Login Token API endpoint is specified in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_LoginAPITokenAPI_.xml and _TokenAPI file (note that _LoginAPI_.xml files is the deprecated API). When running the server with ports different port offsets from to the default port (i.e., 9443), you need to must update the endpoints defined inside the default APIs accordingly (_LoginAPITokenAPI_.xml and , _TokenAPILoginAPI_.xml files with that offset etc.). See Changing the Default Ports with Offset.

   Info
   icon false
   User access tokens have a fixed expiration time, which is set to 60 minutes by default. Before deploying the API manager to users, extend the default expiration time by editing the <AccessTokenDefaultValidityPeriod> tag in <PRODUCT_HOME>/repository/conf/identity.xml. When a user access token expires, the user can try regenerating the token as explained in the Renew user tokens section.

    

...

Generating authorization code

Use You can use the /authorize endpoint to utilize the Authorization Code for the authorization code grant type of OAuth2.0. Since As this is a redirection-based flow, the client must be capable of interacting with the resource owner's user-agent (typically a Web browser) and receiving incoming requests (via redirection) from the authorization server.

The client initiates the flow by directing the resource owner's user-agent to the authorization endpoint. It includes the client identifier, response_type, requested scope, and a redirection URI to which the authorization server sends the user-agent back after granting access. The authorization server authenticates the resource owner (via the user-agent) and establishes whether the resource owner granted or denied the client's access request. Assuming the resource owner grants access, the authorization server then redirects the user-agent back to the client using the redirection URI provided earlier. The redirection URI includes an authorization code.

...

The /token endpoint responds in the same way like in password grant type.

...

Renewing user tokens

Anchor
Renewing Renewing

After an access token is generated, users sometimes may you might have to refresh or renew the old token due to expiration or security concerns. This can be done by issuing a REST call to the Login Token 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 Token API URL is https://localhost:8243/logintoken.
• 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 <base64 encoded string> as appropriate.          

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

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

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

...

Revoking access tokens

After issuing an accesstokenaccess token, a user or an admin may need to revoke the token because of a theft or any other reasons. This can be done calling an REST API endpoint.(ie: Revoke API)  User can use the Curl utility to do a REST call. Revoke endpoint URL is, can revoke it in case of theft or a security violation. You can do this by calling Revoke API using a utility like cURL. The Revoke API's endpoint URL is http://localhost:8280/revoke.

Parameters which are needed required to invoke the revoke api are;this API are as follows:

• The token to be revoked
• Consumer key and consumer secret key

...

• . Must be encoded using Base64 algorithm

...

...

For example, curl -k -d "token=<ACCESS_TOKEN_TO_BE_REVOKED>" -H "Authorization: Basic Base64Encoded(Consumer key:consumer secret)" http://localhost:8280/revoke

Exchanging SAML2 bearer tokens with OAuth2

SAML 2.0 is an XML-based protocol . It uses security tokens containing assertions to pass information about an enduser between a SAML authority and a SAML consumer. A SAML authority is an identity provider (IDP) and a SAML consumer is a service provider (SP).

A lot of enterprise applications use SAML2 to engage a third-party identity provider to grant access to systems that are only authenticated against the enterprise application. These enterprise applications might need to consume OAuth-protected resources through APIs, after validating them against an OAuth2.0 authentication server. However, an enterprise application that already has a working SAML2.0 based SSO infrastructure between itself and the IDP prefers to use the existing trust relationship, even if the OAuth authorization server is entirely different from the IDP. The SAML2 Bearer Assertion Profile for OAuth2.0 helps leverage this existing trust relationship by presenting the SAML2.0 token to the authorization server and exchanging it to an OAuth2.0 access token.

WSO2 API Manager provides SAML2 Bearer Assertion Profile Support with the OAuth 2.0 feature. WSO2 Identity Server (version 4.5.0 onwards) or any other SAML2 Identity provider can act as an identity service provider for the systems enabled with SSO. WSO2 API Manager acts as the OAuth authorization server. This way, an enterprise application can exchange the SAML2.0 bearer token that it retrieves when authenticating against an IDP (e.g., WSO2 Identity Server) with an OAuth2.0 access token from an OAuth authorization server (e.g., WSO2 API Manager). It can then use the OAuth2 token in API invocations.

The diagram below depicts this scenario:

Image Added   
The scenarios of the above diagram are explained below:

Scenario [1]: User initiates login call to an enterprise application .

Scenario [2]:

• As the application is a SAML SP, it redirects the user to the SAML2.0 IDP to log in.
  
• The user provides credentials at the IDP and is redirected back to SP with a SAML2.0 token signed by the IDP.
  
• The SP verifies the token and logs the user to the application.
  
• The SAML 2.0 token is stored in the user's session by the SP.  

Scenario [3]:

• The enterprise application (SP) wants to access an OAuth2 protected API resource through WSO2 API Manager.
• The application makes a request to the API Manager to exchange the SAML2 bearer token for an OAuth2.0 access token.
• The API Manager validates the assertion and returns the access token.

Scenario [4]: User does API invocations through the API Manager by setting it as an Authorization header with the returned OAuth2 access token.

Let's see how to configure the token exchange.

Prerequisites

• A signed SAML2 token (encoded assertion value), which you retrieve when authenticating against a SAML2 IDP. With the authentication request, you must pass attributes such as SAML2 issuer name, token endpoint and the restricted audience. To specify those attributes,

  • Log in to the management console (https://localhost:9443/carbon) using admin/admin credentials and select Trusted  Identity Providers sub menu from the Configure menu.
    

  • Provide the following values in the page that opens:
    
    • Identity Provider Name: Enter a unique name for idP
    • Identity Provider Issuer : The SAML2 issuer name specified when generating assertion token, which contains the unique identifier of the IDP
    • Identity Provider Url : OAuth endpoint URL to which SAML2.0 assertion is delivered. It is defined with SAML2 SubjectConfirmationData when generating SAML2.0 assertion token.
    • Identity Provider Public Certificate:  Upload Identity Provider public certificate
    • Identity Provider Audience : The audience to which the SAML2 assertion is restricted. Its URI is used when generating SAML2.0 assertion token

• A valid user account in the API Store. See Signing up to API Store. 
  
• A valid consumer key and consumer secret. Initially, these keys must be generated through the management console by clicking the Generate link on My Subscriptions page. For more information, see Working with Access Tokens.
  
• A running API Gateway instance. See information on API Gateway in Architecture Components.

Invoking Token API to generate user tokens

Anchor
GenerateToken GenerateToken

  

Follow the steps below to invoke Token API to generate user tokens from SAML2 assertions.

1. Combine the consumer key and consumer secret keys as consumer-key:consumer-secret and encode the combined string using base64 using http://base64encode.org. Here's an example consumer key and secret combination: wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue.
2. Access the Token API using a REST client such as the WSO2 REST Client or Curl. The parameters are explained below:
   
   
   • Assuming that both the client and the API Gateway run on the same server, the Token API URL is https://localhost:8243/token.
   • payload - "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=<SAML2_Encoded_Assertion_Token> &scope=PRODUCTION". Replace the <SAML2_Encoded_Assertion_Token> value as appropriate.
   • headers - Authorization :Basic <base64 encoded string>, Content-Type: application/x-www-form-urlencoded. Replace the <base64 encoded string> as appropriate.

   For example, use the following cURL command used to access the Token API generates an access token and a refresh token. You can use the refresh token at the time a token is renewed.
   

   Code Block
   curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion=<SAML2_Encoded Assertion>&scope=PRODUCTION" -H "Authorization: Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh" -H "Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

   Warning
   The Token API endpoint is specified in <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file. When running the server with ports different to the default (i.e., 9443), you must update the endpoints defined inside the _TokenAPI_.xml file accordingly. See Changing the Default Ports with Offset.