SAML 2.0 is an XMLan XML-based protocol. It uses security tokens tokens containing assertions assertions to pass information about an end-user between a SAML authority and a SAML consumer. A SAML authority is an is an identity provider provider (IDPIdP) and a SAML consumer is consumer is a service provider provider (SP).
Enterprise applications that have SAML2 based SSO infrastructures sometimes need to consume OAuth-protected resources through APIs. However, these apps prefer to use the existing trust relationship with the IDPIdP, even if the OAuth authorization server is entirely different from the IDPIdP. The API Cloud leverages this trust relationship by exchanging the SAML2.0 token to an OAuth token with the authorization server. It acts as the OAuth authorization server.
The diagram below depicts this scenario:
The steps of the above diagram are explained below:
Step [1]: User The user initiates a login call to an enterprise application.
Step [2]:
- As the application is a SAML SP, it redirects the user to the SAML2.0 IDP IdP to log in.
- The user provides credentials at the IDP IdP and is redirected back to the SP with a SAML2.0 token signed by the IDPIdP.
- 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.
...
Step [5]: The API Cloud returns OAuth2 access token to the application.
Step [6]: User The user does API invocations through the API Cloud by setting it as an Authorization header with the returned OAuth2 access token.Step
Step [7]:
...
The backend receives the API call together with the JWT token
...
and user information.
Let's configure the token exchange.
Configuring the token exchange
| Note |
|---|
Before you begin, make sure you have the following:
|
To configure the
...
identity provider:
- On the Configure menu, click External click External Users:.
In the Connect External Users to API Cloud screen, click 
- On the API Consumer Authentication tab, and then select the Connect your
- Authentication tab, click Connect Your IdP (SAML Grant) option:
- .
Provide the following values:
...
Public Certificate:
...
The certificate used to sign the SAML assertion.
...
Export the public certificate of WSO2 IS and import it here.
...
- SSO URL:
...
- Enter the
...
- IdP's SAML2 Web SSO URL value. E.g., https://localhost:9444/samlsso/ if you have offset the default port, which is 9443.
- IdP Entity ID: The SAML2 issuer name specified when generating the assertion token, which contains the unique identifier of the IdP.
- Click Submit Request.
Invoking the Token API to generate tokens
...
- Combine the consumer key and consumer secret keys as
consumer-key:consumer-secret. Encode the combined string using base64 ( http://base64encode.org). Here's an example consumer key and secret combination:wU62DjlyDBnq87GlBwplfqvmAbAa:ksdSdoefDDP7wpaElfqvmjDue. - 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://gateway.api.cloud.wso2.com:8243payload -
"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 consumer-key:consumer-secret>, Content-Type: application/x-www-form-urlencoded. Replace the<base64 encoded consumer-key:consumer-secret>as appropriate.
For example, the following Curl command is used to access the Token API. It 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=<Assertion_provided_by_client>&scope=PRODUCTION" -H "Authorization: Basic <Base64 encoded consumer key:consumer secret>, Content-Type: application/x-www-form-urlencoded" https://gateway.api.cloud.wso2.com:8243/token