Instructions for

Implement authorization by grant type

About the SAML 2.0 Assertion grant

The SAML 2.0 Assertion flow is intended for a client app that wants to use an existing trust relationship without a direct user approval step at the authorization server. It enables a client application to obtain an authorization from a valid, signed SAML assertion from the SAML Identity Provider. The client app can then exchange it for an OAuth access token from the OAuth authorization server. For example, this flow is useful when you want to fetch data from APIs that only support delegated permissions without prompting the user for credentials.

To use a SAML 2.0 Assertion as an authorization grant, the client makes a SAML request to the Identity Provider and the Identity Provider sends the SAML 2.0 Assertion back in the response. The client then makes a request for an access token with the urn:ietf:params:oauth:grant-type:saml2-bearer grant type and includes the assertion parameter. The value of the assertion parameter is the SAML 2.0 assertion that is Base64-encoded. You can send only one SAML assertion in that request.

Note: See our SAML concept page for more information on SAML.

See OAuth 2.0 overview for more information on the SAML 2.0 Assertion grant flow.

Grant-type flow

Identity Provider and Service Provider configuration

This section discusses the steps required to add an external SAML Identity Provider in Okta, and then how to get the SAML metadata required for the Service Provider configuration.

Configure a SAML Identity Provider

Use one of the following existing procedures to configure the SAML Identity Provider:

The following steps assume that you are using the Admin Console.

Obtain SAML metadata for the SAML Service Provider

After you complete the SAML Identity Provider configuration, if you haven't done it already, download the SAML metadata for use when you configure the SAML Service Provider.

On the Identity Providers page in the Admin Console, locate the SAML Identity Provider that you just added and click the arrow next to the name to expand.
Download the metadata by clicking Download metadata. The metadata URL is similar to this: https://{yourOktaDomain}/api/v1/idps/${idpId}/metadata.xml.

If your Service Provider doesn't support uploading metadata, save the Assertion Consumer Service URL (ACS URL) and the Audience URI values to enter manually.

Note: If you used the Identity Providers API to create the SAML Identity Provider in Okta, locate and copy the audience value within the credentials property of the protocol object. Then, locate and copy the acs link relation type value within the links object.

Upload the metadata

Follow the Service Provider's instructions on how to upload the metadata. If your Service Provider doesn't support uploading metadata, enter the ACS URL and Audience URI values manually.

Set up your app

Before you can implement authorization, you need to register your app in Okta by creating an app integration from the Admin Console.

In the Admin Console, go to Applications > Applications.
Click Create App Integration.
Select
OIDC - OpenID Connect
as the Sign-in method.

Select Native Application as the Application type, then click Next.
Enter a name for your app integration. In the Sign-in redirect URIs box, specify the callback location where Okta returns the browser (along with the token).
Click Save to create the app.
On the General tab that appears, scroll to the General Settings section and click Edit.
Select Refresh Token and SAML 2.0 Assertion as the Allowed grant types. These selections enable you to exchange an assertion for the access token and also request a refresh token.

Note: The refresh token lifetime depends on the assertion lifetime and the API Access Management policies. The lowest of both of these defined values is the refresh token max lifetime.
Click Save.
On the General tab, make note of the Client ID and Client secret listed in the Client Credentials section. You need these credentials in the SAML 2.0 Assertion flow specifics section.

Note: You can use either an existing OpenID Connect app integration or create a new one. In the previous instruction, we are creating a Native app using the Admin Console. You must use the Dynamic Client Registration API to create a SPA or Web client application for use with the SAML 2.0 Assertion grant type.

Configure the authorization server policy

Make sure that the SAML 2.0 Assertion grant type is enabled in the authorization server. You can update an existing rule or create a new rule. In this example, we are updating the Default Policy Rule.

In the Admin Console, go to Security > API.
On the Authorization Servers tab, select default from the Name column in the table. In this example, we are configuring the Default Policy Rule for the default custom authorization server.

Note: See Configure an access policy for information on creating an access policy in the Okta authorization server.
Select the Access Policies tab and then click the pencil for the Default Policy Rule to make changes.
In the Edit Rule window, select SAML 2.0 Assertion in the IF Grant type is section.
Click Update Rule.

Flow specifics

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

Note: The example request in the next section shows you the direct OIDC & OAuth 2.0 API call. Typically, you don't need to make direct calls to the API if you're using one of Okta's Authentication SDKs that support SAML 2.0 Assertion.

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 set up your app. 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
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"
}

Next steps

Edit This Page On GitHub