Page Comparison

You use the Token API to generate and renew user and application access tokens, which are required to invoke APIs subscribed under an application. Let's see how to generate/renew access tokens and authorize them. We support the four most common authorization grant types and you can also define additional types such as SAML.

...

1. Combine the consumer key and consumer secret keys in the format consumer-key:consumer-secret and encode the combined string using base64 using the URL: http://base64encode.org.
   Here's an example consumer key and secret combination : wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue.
2. Invoke the 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 token API url URL is https://localhost:8243/token
   • payload - "grant_type=password&username=<username>&password=<password>&scope=<scope>". Replace the <username> and <password> values as appropriate. <scope> is optional, you can leave it off if necessary
   • 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 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>" -H "Authorization: Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh, Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

   Code Block
   title CuRL command with Scopes
   curl -k -d "grant_type=password&username=<username>&password=<password>&scope<scope1> <scope2>" -H "Authorization: Basic SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh, Content-Type: application/x-www-form-urlencoded" https://localhost:8243/token

   Info
   title A note about scopes
   When defining an API, the API creator is able to specify a scope for an API Resource. This is so that the API Resource resource. The resource can only be accessed through a token that had has been issued for at least the scope belonging to the API Resourceresource. For example, if a Resource had resource has been defined for a scope named 'update' and if the token had been issued for the scopes 'read' and 'update', the token will be allowed to access the resource. If the token had been issued for a scope named 'read', the request bearing the particular token will be blocked.

   Warning
   The Token API endpoint is specified in <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file. When running the server on a different port from the default (i.e., 9443), or if your Key Manager is running on a different machine from your API Gateway, you must update the endpoint inside the _TokenAPI_.xml file as described in the prerequisites.

   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 .

Instead of using the Token API, you can generate access tokens from the API Store UI. See Generate Access Tokens to Authenticate APIs for information.

...

Exchanging SAML2 bearer tokens with OAuth2 (SAML extension grant type)

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 5.0.0 is used here but you can use any version from 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 Modified   
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 the 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,

• 1. Log in to the management console (https://localhost:9443/carbon) using admin/admin credentials and select Add under Identity Providers menu in the Main menu.
     
     

  2. Provide the following values in the page that opens:
     
     • Under Basic Information
       
       • Identity Provider Name: Enter a unique name for IDP
       • Identity Provider Public Certificate: Upload Identity Provider public certificate
       • Alias: Give the name of the alias if the Identity Provider identifies this token endpoint by an alias

     • Under Federated Authenticators -> SAML2 Web SSO Configuration

       • Identity Provider Entity Id: The SAML2 issuer name specified when generating assertion token, which contains the unique identifier of the IDP 

       • Service Provider Entity Id: 
       • SSO URL: Enter the IDP's SAML2 Web SSO URL value
         
       
       

• 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 Generate Access Tokens to Authenticate APIs.
  
• A running API Gateway instance. See information on API Gateway in Architecture.
• If you have multiple Carbon servers (such as WSO2 API Manager and WSO2 Application Server) running on the same machine, you must change the port offset and update the token API endpoint. Additionally, if the key server is on a different server from the API Gateway, you must update the token API endpoint to use the correct host and port. For more information, see this prerequisite in the previous section.
  

Invoking Token API to generate tokens

Anchor
GenerateToken GenerateToken

  

...

• 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