Use the SAML 2.0 Assertion flow

On This Page

Before you can begin this flow, you must collect the SAML assertion from the Identity Provider and make sure that it is Base64-encoded (opens new window). You can then use the assertion in the API call to the Authorization Server's /token endpoint.

Request example

If you are using the default Custom Authorization Server, then your request would look something like this:

curl --location --request POST 'https://${yourOktaDomain}/oauth2/default/v1/token' \
--header 'Accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic MG9hb....' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:saml2-bearer' \
--data-urlencode 'scope=openid offline_access' \
--data-urlencode 'assertion=<Base64-encoded assertion>'

Note: The call to your authorization server's /token endpoint requires authentication. In this case, it is a Basic Auth digest of the Client ID and secret. You made note of these during app setup. See Client Authentication Methods.

Note the parameters that are being passed:

  • grant_type: urn:ietf:params:oauth:grant-type:saml2-bearer
  • assertion: A single SAML 2.0 assertion that is Base64-encoded (opens new window)
  • scope: openid and offline_access. The openid scope is required. Include offline_access if you want a refresh token included. You can also request additional scopes. See the Create Scopes section of the Create an Authorization Server guide.

Response example

Note: The tokens are truncated for brevity.

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQiOiJ3UHdvd.....gkJktHWp4YeLBGRxInAP2n4OpK6g1LmtNsEZw",
    "scope": "offline_access openid",
    "refresh_token": "rHXv2mvdmkfp3MwqYjNzrhyuvlVGZF2WgKsYXfTq3Mk",
    "id_token": "eyJraWQ.....h7BYbgCzQ"
}