Exchanging SAML2 bearer tokens with OAuth2 tokens in WSO2 API Manager

To get access to a a managed API of WSO2 API Manager,a user has to pass an oauth token.From APIM 1.5.0 onwards a user can exchange his SAML2 token to obtain an OAuth2 token.This feature will be useful,in the following use-case :

Most 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 Single Sign On 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 and then use that OAuth token to get access to APIs.

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.

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

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

[2]: 

• As the application is a SAML Service Provider[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.  

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

[4]:       With the above returned oauth access token in step [3],API invocation through the API Manager will be happened successfully

Steps

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

           To try out saml2 token grant type token generation with WSO2 IS/WSO2 APIM itself as               IDP,you can use the saml2 client included in here and execute that java client with the               command mentioned in it. 

• Then it need to register a Trusted Identity Provider entry against above used IDP in WSO2 APIM,in-order to use the above generated saml2 token. Log in to the APIM management console (https://ip:port/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 [Your SAML2 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 assertion recipient when generating SAML2.0 assertion token.
  • Identity Provider Public Certificate:  Upload Identity Provider public certificate.You can generate this by keytool command as follow: 
• keytool -export -alias {alias} -file {fcertificateFileNameToBeCreated} -keystore {jks_file_name}
• Identity Provider Audience : The audience to which the SAML2 assertion is restricted. This URI is used when generating SAML2.0 assertion token.For example ,in this use-case,since saml2 token will be used by APIM,audience value can be added as https://{ip_apim:port_apim}/oauth2/token

• A valid subscriber account in the API Store has to be created. See Signing up to API Store. 

• A valid consumer key and consumer secret need to be generated. Initially, these keys must be generated through APIStore by clicking the Generate link on My Subscriptions page. For more information, see Working with Access Tokens. 

Invoking Token API to generate user tokens   

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. 
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= {generated_saml2_token};scope=PRODUCTION". Replace the  value as appropriate.
   • headers - Authorization :Basic  Replace the  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. 
   curl -k -d "grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer&assertion={generated_saml2_token}&scope=PRODUCTION" -H "Authorization: Basic {base64encoded consumer key:secret}" https://ip_apim:port_apim/token