This documentation is for WSO2 API Manager 1.5.0 View documentation for the latest release.
Token APIs - API Manager 1.5.0 - WSO2 Documentation
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 20 Next »

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.

Generating user tokens

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 encoded string of the comsumer-key:consumer-secret combination. 

For instructions to generate an application-level access token from the API Store, see Generating 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 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   

  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 .

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

    The Token API endpoint is specified in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file [where _LoginAPI_.xml is the deprecated API]. When running the server with different port offsets from the default port (i.e., 9443), you need to update the endpoints defined inside the _TokenAPI_.xml and _LoginAPI_.xml files with that offset. See Configuring Port Offset.

    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 the /authorize endpoint to utilize the Authorization Code grant type of OAuth2.0. Since 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 client then requests an access token from the authorization server's /token endpoint by including the authorization code received in the previous step. When making the request, the client authenticates with the authorization server. It then includes the redirection URI used to obtain the authorization code for verification. The authorization server authenticates the client, validates the authorization code, and ensures that the redirection URI matches the URI used to redirect the client from the /authorize endpoint in the previous response. If valid, the authorization server responds back with an access token and, optionally, a refresh token.

Assuming that both the client and the API Gateway are run on the same server, the Authorization API url is https://localhost:8243/authorize.

  • query component - response_type=code&client_id=<consumer_key>&scope=PRODUCTION&redirect_uri=<application_callback_url>
  • headers - Content-Type: application/x-www-form-urlencoded

For example, the client directs the user-agent to make the following HTTP request using TLS.

GET
/authorize?response_type=code&client_id=wU62DjlyDBnq87GlBwplfqvmAbAa&scope=PRODUCTION&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb
HTTP/1.1 
Host: server.example.com 
Content-Type:
application/x-www-form-urlencoded 

The authorization server redirects the user-agent by sending the following HTTP response:

HTTP/1.1 302 Found 
Location:
https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA

Now the client makes the following HTTP request using TLS to the /token endpoint.

POST /token HTTP/1.1 
Host: server.example.com 
Authorization: Basic
SVpzSWk2SERiQjVlOFZLZFpBblVpX2ZaM2Y4YTpHbTBiSjZvV1Y4ZkM1T1FMTGxDNmpzbEFDVzhh
Content-Type:
application/x-www-form-urlencoded 
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

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

Renewing 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 the 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 Token API URL is https://localhost:8243/token.
  • 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 Token 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/token

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

Revoking access tokens

After issuing an access token, a user or an admin 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 required to invoke this API are as follows:

  1. The token to be revoked
  2. 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.0 bearer assertion tokens with OAuth2.0 access tokens

Many existing enterprise applications that have implemented SOA  are relying  on SAML2.0 . [SAML 2.0 is an XML-based protocol that uses security tokens containing assertions to pass information about a end user between a SAML authority, that is an identity provider[IDP], and a SAML consumer, that is a service provider].Such enterprise applications use SAML2 in a manner,where they can engage a third-party identity provider to grant access to multiple systems by only authenticate against the enterprise application.Now that enterprise application could face a situation where they now need to consume OAuth protected resources through APIs from inside the application by validate against an OAuth2.0 Authentication Server.

An enterprise application that has already got a working SAML2.0 based Single Sign On infrastructure between itself and the Identity Provider (IDP) would prefer to use the existing trust relationship between the Identity Provider (IDP) and the Service Provider(SP), even if the OAuth Authorization Server is entirely different from the IDP.

The SAML2 Bearer Assertion Profile for OAuth2.0 is the answer to the question of how to leverage on the existing trust relationship between the SP and the IDP, by presenting the SAML2.0 token to the authorization server and exchanging it directly to an OAuth2.0 access token.

WSO2 API Manager 1.5.0 provides SAML2 Bearer Assertion Profile Support with OAuth 2.0 feature. WSO2 Identity Server [4.5.0 onwards] or any other SAML2 Identity provider can act as an identity service provider of the systems enabled with single sign-on, while WSO2 API Manager can use as the OAuth Authorization server.Using this feature, an enterprise application can exchange the SAML2.0 bearer token which retrieves while authenticate against IDP[WSO2 Identity Server] with OAuth2.0 access token from OAuth Authorization server [WSO2 API Manager]  to use with API invocations.

The below component diagram will illustrate the above mentioned flow clearly.

 
 
  
 

[1] A user initialize the flow with a login call to an enterprise application 

[2] The application being a SAML SP redirects the user to the SAML2.0 IDP for login.The user enters his 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 log the user to the application.The SAML 2.0 token will be stored in the user's session by the SP. 

[3] The enterprise application[SP] wanted to access an OAuth2 protected API resource through WSO2 API Manager and application makes a request to WSO2 API Manager to exchange the SAML2 bearer token for an OAuth2.0 access token.The WSO2 APIManager validates the assertion and return the access token.

Then with the returned OAuth2 access token to the application,by setting it as an Authorization header,user can do further API invocations through WSO2 API Manager.

 

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>
<Issuer trustEntityId="wso2carbon">https://localhost:9443/samlsso</Issuer>
 </Issuers>
<TokenEndPoint>https://localhost:9444/oauth2endpoints/token</TokenEndPoint>
<TokenEndPointAliases>tokenEP</TokenEndPointAliases>
<Audience>https://localhost:9444/oauth2endpoints/token</Audience>
 </SAML2Grant>

From the above configuration;

  • Issuer -The SAML2 issuer name specified when generating SAML2.0 assertion token [which contains the unique identifier of the identity provider] .
  • TokenEndPoint-This is defined with SAML2 SubjectConfirmationData when generating SAML2.0 assertion token [Define the OAuth endpoint URL to which SAML2.0 assertion delivered].
  • Audience- The audience URI specified when generating SAML2.0 assertion token. [The intended audience that the SAML2 assertion is restricted].

You need the following before using the Token API to generate a user token from a SAML 2.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. You can find more details in Generating 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 from SAML 2.0 assertion    

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

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

    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 different port offsets from the default port (i.e., 9443), you need to update the endpoint defined inside the _TokenAPI_.xml file with that offset. See Configuring Port Offset.




  • No labels