Build a Single Sign-On (SSO) integration

This guide teaches you how to integrate your federated SSO application with Okta. This guide assumes that you intend to make this app integration public by publishing it in the Okta Integration Network (OIN).

---

Learning outcomes

Create and test an SSO app integration for OIN submission.

What you need

• Okta Developer Edition organization (opens new window)
• An app to integrate SSO with Okta

---

Overview

Single Sign-On (SSO) is an authentication method that enables end users to sign in to multiple applications (apps) with one set of credentials. If you have customers that use Okta as an Identity Provider, you want to publish your SSO app integration to the OIN. By having your integration in the OIN catalog, your customers can easily configure SSO for your app. See Overview of Single Sign-On in the OIN for all the benefits of having your integration in the OIN catalog.

To create an SSO integration for the OIN, first sign up for a free Okta developer-edition org (opens new window). Next, select the type of SSO protocol that you want to implement. Okta supports two SSO standards for your integration:

• OpenID Connect (OIDC) (preferred)
• Security Assertion Markup Language (SAML)

Okta recommends using OIDC for new SSO integrations.

Note: Not all Okta SSO features are supported in the OIN. See OIN limitations.

Deployment models

After you've decided on a protocol, select a deployment model. Okta offers redirect or embedded authentication deploy models. Redirect authentication uses the Okta Sign-In Widget (opens new window) and is the easiest, most secure way to integrate with Okta.

Okta recommends the redirect authentication deployment model if your situation meets the requirements. For more information on deployment models and other authentication considerations, see:

• Okta deployment models—redirect vs. embedded
• Redirect authentication guides
• Embedded authentication guides

Prepare your integration

If you haven't built the OIDC service in your app yet, review the OAuth 2.0 and OpenID Connect Overview.

For OIDC integrations that you want to publish in the OIN catalog, review the following implementation topics:

1. Determine a suitable OAuth 2.0 flow to use based on your app type.

2. Determine the scopes that you require for your OIDC client (your app).

3. Consider how your app stores customer client credentials.

4. Understand how to validate tokens in your OIDC client.

   Note: You can't use the Okta SDKs to validate access tokens for apps in the OIN. This is due to the OIN restriction of using an org authorization server and the Authorization Code flow.

5. Implement credential rotation in your app.

   Your app must support automatic credential rotation. See key rotation.

6. Determine the sign-in redirect URIs for your app.

   A redirect URI is where Okta sends the authentication response and ID token during the sign-in flow. You can specify more than one URI if required.

7. Consider rate limits when you build your integration.

Build your integration with these guidances.

Note: Quickstarts and example links are provided in the Determine the OAuth 2.0 flow to use section. These links provide example OIDC implementations outside of the OIN.

After you've built your integration, test your SSO integration with an Okta app integration instance. See Create your integration in Okta.

OIDC customer org credentials

Okta uses a multi-tenant local credential system for OIDC integrations. When your customer adds your integration in their Okta org, they obtain a unique set of OIDC credentials. Each instance of your app integration inside a customer org has a separate set of OIDC client credentials that are used to access your application.

This multi-tenant approach differs from other IdPs that use a global credential system, where a given application has the same customer credentials across all orgs.

See the OIN multi-tenancy requirement.

You must track client credentials for each app integration instance for your app. For example, consider a scenario where your app integration is added to 10 separate customer orgs. Seven of those customers create a single instance of your app integration. However, the other three customers each create two separate instances of your app integration so they can use different configuration options. This scenario creates a total of 13 sets of client credentials for your application that you need to track.

Determine the OAuth 2.0 flow to use

Select the OAuth 2.0 flow to use based on your app:

• For web apps:

  Okta recommends the Authorization Code flow. This flow is used for apps with a dedicated server-side backend capable of securely storing a client secret. The app integration can also exchange information with an authorization server through trusted back-channel connections.

• For single-page apps (SPA):

  Okta recommends the Authorization Code flow with a Proof Key for Code Exchange (PKCE) to control access between your SPA app and a resource server.

Note: Native and mobile app integrations aren't accepted as OIDC app integrations in the OIN. Set up your app to use an authentication flow that allows your client app to talk to your SaaS backend. Your SaaS backend can then securely communicate with Okta through trusted back-channel connections.

Follow these guides to implement the OAuth 2.0 flows:

• Implement Authorization Code flow
• Implement Authorization Code flow with PKCE

Note: You can also review these sample app integration quickstarts that use the Okta CLI:

• Sign in to SPA
• Sign in to web application

When you follow these guides, one caveat is the use of the authorization server. Most of the examples show you how to make an /authorize or /token request using a custom authorization server. To support the potentially large number of Okta orgs accessing it through the OIN, an OIDC integration can't use a custom authorization server. This includes the default server. You can only use the org authorization server.

For example, the following are the various /authorize request URLs for the different authorization servers:

custom authorization server: https://${customerOktaDomain}/oauth2/${authorizationServerId}/v1/authorize?client_id=${clientId}&response_type=code&scope=openid&redirect_uri=${redirectURI}&state=${state}

default custom authorization server(${authorizationServerId}=default): https://${customerOktaDomain}/oauth2/default/v1/authorize?client_id=${clientId}&response_type=code&scope=openid&redirect_uri=${redirectURI}&state=${state}

org authorization server:https://${customerOktaDomain}/oauth2/v1/authorize?client_id=${clientId}&response_type=code&scope=openid&redirect_uri=${redirectURI}&state=${state}

Make sure you only use the org authorization server URL.

Note: The refresh_token option isn't supported for apps published in OIN.

Scopes

Your OIDC client needs to use scope values to define the access privileges being requested with individual access tokens. The scopes associated with access tokens determine what resources are available when the tokens are used to access the protected endpoints. You can use scopes to request that specific sets of values be available as claim information about the end user.

The only scope that you must declare is openid. When the authentication request is sent to Okta, the openid scope identifies the request as being an OIDC request.

Other optional scopes available (these are returned from the /userinfo endpoint):

• profile: The end user's default profile claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at

• email: Requests access to the email and email_verified claims

  Note: Don't rely on the email_verified scope-dependent claim returned by an OIDC integration to evaluate whether a user has verified ownership of the email address associated with their profile.

• address: Requests access to the address claim

• phone: Requests access to the phone_number and phone_number_verified claims

Note: The following scopes aren't supported for integrations published in the OIN:

• offline_access scope (since refresh tokens aren't supported)
• Custom scopes (such as the groups scope). You can only request the OIDC scopes. You can't configure custom scopes.

Okta uses access policies to decide whether to grant scopes. If any of the requested scopes are rejected by the access policies, Okta rejects the request.

Uniform Resource Identifier (URI)

There are three URIs that you need to consider when creating an OIDC app for the OIN:

1. Sign-in redirect URIs: After the user is successfully authorized by Okta, this is the callback location where the user is directed along with the authorization code. This URI must exactly match at least one of the redirect URI values that are pre-registered in the Okta app integration settings.
2. Optional. Initiate login URI: This URI is used if the app is launched from the Okta dashboard (known as an IdP-initiated flow), and you want your Okta integration to handle redirecting your users to your app to start the sign-in request. When end users click your app in their Okta dashboard, they are redirected to the initiate_login_uri of the client app, which constructs the authentication request and redirects the end user back to the authorization server. This URI must exactly match the Initiate URI value that is pre-registered in the Okta app integration settings.
3. Optional. Sign-out redirect URIs: A location to send the user after a sign-out operation is performed and their session is terminated. Otherwise, the user is redirected back to the sign-in page.

Token validation

For checking access tokens, the /introspect endpoint takes your token as a URL query parameter and then returns a simple JSON response with the boolean active property.

As OIN app integrations can't use custom authorization servers, you must use remote token validation (through the Introspection API endpoint) for access tokens and local validation for ID tokens.

This remote validation incurs a network cost, but you can use it when you want to guarantee that the access token hasn't been revoked.

Note: You can't use the Okta SDKs for OIN app integration development if you need to validate access tokens with the org authorization server. This is due to the OIN restriction of using an org authorization server and the Authorization Code flow.

Key rotation

The standard behavior in identity and access management is to rotate the keys used to sign tokens. Okta changes these keys typically four times a year (every 90 days), but that rotation schedule can change without notice. Okta automatically rotates the keys for your authorization server on a regular basis.

Your OIDC client should periodically query the /keys endpoint and retrieve the JSON Web Key Set. This key set contains the public keys used to verify the signatures of the tokens received from Okta. You can cache the keys to improve performance, but be aware that verification fails when Okta automatically rotates the keys.

See key rotation or the /keys API endpoint for specific details on handling queries and responses.

Rate limit considerations

When you construct your SSO application, be aware of the limits on requests to Okta APIs. For information on the categories and cumulative rate limits, see the Rate limits overview. Okta provides three headers in each response to report on both concurrent and org-wide rate limits.

For org-wide rate limits, the following three headers are provided:

• X-Rate-Limit-Limit: The rate limit ceiling that applies to the current request
• X-Rate-Limit-Remaining: The amount of requests left for the current rate-limit window
• X-Rate-Limit-Reset: The time when the rate limit resets, specified in UTC epoch time

To monitor org-wide rate limits, include code in your app to check the relevant headers in the response.

For concurrent rate limits, the three headers behave a little differently:

• When the number of unfinished requests is below the concurrent rate limit, request headers only report org-wide rate limits.
• After you exceed a concurrent rate limit, the headers report that the limit has been exceeded.
• When you drop back down below the concurrent rate limit, the headers switch back to reporting the time-based rate limits.
• The first two header values are always 0 for concurrent rate limit errors. The third header reports an estimated time interval when the concurrent rate limit may be resolved.
• The X-Rate-Limit-Reset time for concurrent rate limits is only a suggested value. There's no guarantee that enough requests can complete for the requests to go below the concurrent rate limit at the time indicated.

The error condition resolves itself when there's another concurrent thread available. Normally no intervention is required. You may be exceeding the concurrent rate limit if you notice frequent bursts of HTTP 429 errors. Examine the activities in the log before the burst of HTTP 429 errors appeared. If you can't identify what is causing you to exceed the limit, contact Okta Support.

You can request a temporary rate limit increase if you anticipate a large number of requests over a specified time period. Contact Okta Support to open a ticket to permit the exception. See How to Request a Temporary Rate Limit Increase (opens new window).

Note: The following public metadata endpoints aren't subjected to rate limits:

• /oauth2/v1/keys
• /.well-known/openid-configuration
• /.well-known/oauth-authorization-server

Create your integration in Okta

This section assumes that you've built the SSO integration in your app.

After you've built your SSO integration, you can use the Application Integration Wizard (AIW) in the Admin Console to create your app integration instance. This instance provides you with client credentials or metadata for you to test your SSO flows.

Note: Creating your app integration instance doesn't automatically make it available in the OIN (opens new window). After you've tested your integration, you need to submit it to the OIN team for verification and publication.

1. Sign in to your developer-edition Okta org as a user with administrative privileges.
2. Go to Applications > Applications in the Admin Console.
3. Click Create App Integration.

4. On the Create a new app integration page, select OpenID Connect in the Sign-in method section.
5. Choose either Web Application or Single-Page Application as the Application type for your integration. The OIN only publishes cloud-based SaaS apps, either traditional Web applications with a back-end or a modern browser-based SPA.
6. Click Next.
7. In General Settings, enter a name for your integration and (optionally) upload a logo.
8. Add your Sign-in redirect URIs and optional Sign-out redirect URIs. These URIs must be absolute URIs, and you can specify more than one.
9. In Assignments, assign a group or leave the Everyone default. Be sure to verify that the users you want to have access are assigned to the group that you select. For instructions on how to assign the app integration to individual users and groups, see the Assign app integrations (opens new window) topic in the Okta product documentation.
10. Click Save.

Specify your integration settings

This portion of the guide takes you through the steps for configuring your specific SSO integration using the Okta Admin Console.

After you create your integration instance in the Create your integration in Okta section, the main settings page appears for your new integration in the Admin Console. Specify General Settings and Sign On options, and assign the integration to users in your org. Click Edit if you need to change any of the options, and Save when you've made your changes.

Specify OIDC settings

• On the General tab, select the grant type for your OAuth 2.0 flow based on your app type:

  • Web app:

    • Authorization Code (mandatory for web platform applications)
    • Refresh token (not supported for OIN app integrations)
    • Implicit (Hybrid) (optional)

  • SPA:

    • Authorization Code
    • Implicit (Hybrid)—choose:
      • Allow ID Token with implicit grant type
      • Allow Access Token with implicit grant type

    Note: For SPA app integrations, the Authorization Code grant type always uses PKCE to verify the client. Also, the Client acting on behalf of itself grant type isn't supported in OIN app integrations.

• If you only want to support direct SSO to your application (so the integration isn't launched from the Okta End-User Dashboard), then:

  1. Enter one or more Sign-in redirect URIs values where Okta sends the OAuth responses.
  2. Set the Sign-in initiated by dropdown box to App Only.
  3. Leave the remaining default values.

• If you want to support launching your application from the Okta dashboard:

  1. Enter one or more Sign-in redirect URIs values where Okta sends the OAuth responses.
  2. (Optional) Enter the Sign-out redirect URIs where Okta redirects the browser after it receives the sign-out request from the relying party and terminates the end user's session. See Configure Single Logout in app integrations (opens new window) or the /logout API endpoint.
  3. Change the Login initiated by field to Either Okta or App to give your integration an Okta tile.

     Note: When you select this option, an App Embed Link section appears at the bottom of the page. The URL that the user can use to sign in to the OIDC client from outside of Okta is provided.

  4. Select Display application icon to users.
  5. Select the Login flow option. For OIN app integrations, you must select Redirect to app to initiate login (OIDC Compliant).
  6. Enter or change the URI used to initiate the sign-in request.
  7. Click Save to commit your changes.

• If required, you can generate a new client secret. In the Client Credentials section, click Edit, then Generate New Client Secret.

Note: If you generate a new set of client credentials, update your app to include the new credentials for your SSO integration.

Test your integration

This portion of the guide takes you through the steps required to test your integration.

Assign users

First, you must assign your integration to one or more test users in your org:

1. Click the Assignments tab.
2. Click Assign and then select either Assign to People or Assign to Groups.
3. Enter the appropriate people or groups that you want to have Single Sign-On into your application, and then click Assign for each.
4. Verify the user-specific attributes for any people that you add, and then select Save and Go Back.
5. Click Done.

Test Single Sign-On

1. Sign out of your Okta org. Click Sign out in the upper-right corner of the Admin Console.

2. Sign in to the Okta End-User Dashboard as the regular user that was assigned the integration.

   Note: If you sign in as a non-admin user to your Okta org from a browser, the End-User Dashboard appears. To access the End-User Dashboard from a mobile device, see Okta End-User-Dashboard (opens new window).

3. Click the Okta tile for the integration and confirm that the user is signed in to your app.

Test Application-initiated sign-in flow

1. Sign out of your administrator account in your development org and also sign out of your application.
2. In your browser, begin the sign-in process to your application, either through your application's sign-in button or directly by pasting one of the Sign-in redirect URIs into your web browser address bar. Regardless of which method you choose, your browser must end up at the Okta-hosted sign-in page.
3. Sign in to your regular user account on the Okta-hosted sign-in page.
4. Confirm that Okta successfully redirects back into your application.

Troubleshoot issues

If you run into issues with your sign-in process, you can try the following to troubleshoot the issues:

• In the Admin Console of your Okta development org, go to Reports > System Log and examine any failure messages reported.
• Open the Admin Console in your web browser and examine any status messages related to your authentication request. The console errors have status codes in the 4XX range. Investigate and resolve any error messages generated by your sign-in request.
• Post your questions on either the Okta Developer Forum (opens new window) or on Stack Overflow (opens new window).

Next steps

After you complete testing your app integration, you can start the submission process to have your app integration included in the Okta Integration Network (opens new window) catalog:

• Review the OIN submission requirements before starting the submission process.
• Review the Publish an OIN integration overview to understand the submission process for publishing an integration.
• Follow the Submit an SSO integration guide to submit your SSO integration.

See also

• Okta SAML FAQs
• Okta Developer Forum: OIDC (opens new window)
• Stack Overflow: Okta OIDC (opens new window)
• Okta Developer Forum: SAML (opens new window)
• Stack Overflow: Okta SAML (opens new window)