This documentation is for WSO2 API Manager 1.5.0 View documentation for the latest release.
Page Comparison - Token APIs (v.29 vs v.48) - API Manager 1.5.0 - WSO2 Documentation

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

You can use the Token API to invoke an API through a third-party application like a mobile app. The 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 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.

...

  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 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 is https://localhost:8243/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 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/token
    Note

    The Token API endpoint is specified in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file (note that _LoginAPI_.xml is the deprecated API).

    When running the server with ports different to the default (i.e., 9443), you must update the endpoints defined inside the default APIs accordingly (_TokenAPI_.xml, _LoginAPI_.xml etc.). See Changing the Default Ports with Offset.

    Info
    iconfalse

    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

...

You can use the /authorize endpoint for the authorization code grant type of OAuth2.0. 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.

...

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 Token API through a REST client such as the WSO2 REST Client or Curl, with the following parameters.

...

Code Block
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/token

...

Parameters required to invoke 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 SAML 2 SAML2 bearer tokens with OAuth2

SAML 2.0 is an XML 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).

...

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

To exchange with an OAuth 2.0 token from WSO2 API Manager, an application [end user] should have a signed SAML2.0 token [encoded SAML2.0 assertion value] which is retrieved after trying authenticate against a SAML2.0 Identity Provider [For example WSO2 Identity Server 4.5.0].When generating such a SAML2.0 signed token from an IDP,the end user need to pass some attributes like SAML2.0 issuer name,the restricted audience,etc with the SAML2.0 authenticate request. Additionally those attributes as SAML2.0 issuer name,the restricted audience,token endpoint needed to be pre-defined under the section of <SAML2Grant> configuration element in the identity.xml of the location <APIM_Home>/repository/conf.For example ;

<SAML2Grant>
<Issuers>

...

  • 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,

...

 </Issuers>
<TokenEndPoint>https://localhost:9444/oauth2endpoints/token</TokenEndPoint>
<TokenEndPointAliases>tokenEP</TokenEndPointAliases>
<Audience>https://localhost:9444/oauth2endpoints/token</Audience>
 </SAML2Grant>

...

iconfalse

From the above configuration;

...

    • 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 SeeSigning - 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 Access Tokens to Invoke APIs. For more information, see Working with Access Tokens.
  • A running API Gateway instance (typically an API Manager instance should be running). For instruction . See information on API Gateway , refer to section 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 in the format as consumer-key:consumer-secret and 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 Token API by using a REST client such as the the WSO2 REST Client or Curl, with the following parameters.. The parameters are explained below:

    • 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=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 . It generates two tokens as an access token and a refresh token. You can use the refresh token at the time atoken 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
    Notewarning

    The Token API endpoint is specified in the <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.