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 in exchange for the SAML 2.0 Assertion, and uses the access token to request resources from the resource server.

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’re 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 (opens new window) 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.

Open the Admin Console for your org.
Choose Applications > Applications to view the current app integrations.
Click Create App Integration.
Select
OIDC - OpenID Connect
as the Sign-in method.

Select Native Application for Application type, then click Next.
Enter an App integration name.
Select Refresh Token in the Grant type section, and then click Advanced and select SAML 2.0 Assertion. These selections enable you to exchange an assertion for the access token and also request a refresh token.

Note: If you're using Okta Classic Engine, select Refresh Token and SAML 2.0 Assertion in the Grant type section.
Enter the callback location in the Sign-in redirect URIs box. This is where Okta returns the browser (along with the token).
Fill in the remaining details for your app integration, then click Save.
Locate the General Settings section on the General tab, and then click Edit.

Note: The refresh token lifetime depends on the assertion lifetime and the API Access Management policies. The assertion lifetime is based on the incoming assertion. The lowest of these defined values is the refresh token max lifetime. For example, the SAML assertion expiry is set to 30 days, and the refresh token expiry in your access policies is set to 180 days. This results in a refresh token lifetime of 30 days.
Click Save.

Save the generated Client ID and Client secret values to implement your authorization flow.

Note: You can either create an OIDC app integration or use an existing one. In the previous instructions, you're creating a native (mobile) app integration using the Admin Console. Use the Dynamic Client Registration API (opens new window) 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 create a rule or update an existing one. In this example, you're 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, you're 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 access the Edit Rule dialog.
Click Advanced in the IF Grant type is section, and then select SAML 2.0 Assertion.

Note: If you're using Classic Engine, 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’s 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 displays a direct OIDC & OAuth 2.0 API (opens new window) call. You don't usually need to make direct calls when you use an Okta authentication SDK that supports the SAML 2.0 Assertion flow.

Request example

If you’re using the org authorization server, then your request would look something like this:

curl --location --request POST 'https://{yourOktaDomain}/oauth2/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’s a Basic Authentication digest of the client ID and secret. You made note of these when you set up your app. See Client Authentication Methods (opens new window).

Note the parameters that are being passed:

grant_type: The value is urn:ietf:params:oauth:grant-type:saml2-bearer
assertion: A single SAML 2.0 assertion that is Base64-encoded
scope: The values are openid and offline_access. The openid scope is required. Include offline_access if you want a refresh token included. You can also request other 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