From 41a60b66c6367b64b727f0a57f0d20e39d17cdc5 Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 15 May 2026 14:36:59 -0400 Subject: [PATCH 1/3] Update conductor, navbar, links, and move and remove content --- packages/@okta/vuepress-site/conductor.yml | 42 +++-- .../docs/concepts/multi-tenancy/index.md | 16 +- .../docs/concepts/sso-overview/index.md | 17 +- .../build-sso-integration/main/index.md | 103 +++++++++++++ .../main/openidconnect/prep.md | 145 ++++++++++++++++++ .../create-an-app-integration/main/index.md | 2 +- .../@okta/vuepress-site/docs/guides/index.md | 2 +- .../docs/guides/oin-sso-overview/index.md | 102 ------------ .../guides/submit-app-prereq/main/index.md | 2 +- .../main/openidconnect/protocol-supported.md | 2 + 10 files changed, 308 insertions(+), 125 deletions(-) create mode 100644 packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/index.md create mode 100644 packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/openidconnect/prep.md diff --git a/packages/@okta/vuepress-site/conductor.yml b/packages/@okta/vuepress-site/conductor.yml index 93cf66e962c..4f5f5a9ce61 100644 --- a/packages/@okta/vuepress-site/conductor.yml +++ b/packages/@okta/vuepress-site/conductor.yml @@ -4626,47 +4626,57 @@ redirects: - from: /docs/guides/style-the-widget/next-steps/index.html to: /docs/guides/custom-widget/main/#see-also - from: /docs/guides/oin-oidc-guide/overview - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/background - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/protocol-level-requirements to: /docs/guides/build-sso-integration/openidconnect/main/#build-your-integration - from: /docs/guides/oin-oidc-guide/multi-tenancy - to: /docs/guides/oin-sso-overview/#okta-organization-and-multi-tenancy + to: /docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy - from: /docs/guides/oin-oidc-guide/integration-best-practices - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/next-steps - to: /docs/guides/oin-sso-overview/#next-steps + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/overview/index.html - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/background/index.html - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/protocol-level-requirements/index.html to: /docs/guides/build-sso-integration/openidconnect/main/ - from: /docs/guides/oin-oidc-guide/multi-tenancy/index.html - to: /docs/guides/oin-sso-overview/#okta-organization-and-multi-tenancy + to: /docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy - from: /docs/guides/oin-oidc-guide/integration-best-practices/index.html - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-guide/next-steps/index.html - to: /docs/guides/oin-sso-overview/#next-steps + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-best-practices/main - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-best-practices/main/index.html - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-best-practices/main/#rate-restrictions to: /docs/guides/build-sso-integration/openidconnect/main/#rate-limit-considerations - from: /docs/guides/oin-oidc-multi-tenancy/main - to: /docs/guides/oin-sso-overview/#okta-organization-and-multi-tenancy + to: /docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy - from: /docs/guides/oin-oidc-multi-tenancy/main/index.html - to: /docs/guides/oin-sso-overview/#okta-organization-and-multi-tenancy + to: /docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy - from: /docs/guides/oin-oidc-protocols/main to: /docs/guides/build-sso-integration/openidconnect/main/ - from: /docs/guides/oin-oidc-protocols/main/index.html to: /docs/guides/build-sso-integration/openidconnect/main/ - from: /docs/guides/oin-oidc-overview/main - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ - from: /docs/guides/oin-oidc-overview/main/index.html - to: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ + - from: /docs/guides/oin-sso-overview/ + to: /docs/concepts/sso-overview/ + - from: /docs/guides/oin-sso-overview/index.html + to: /docs/concepts/sso-overview/ + - from: /docs/guides/oin-sso-overview/#choose-your-sso-protocol + to: /docs/concepts/sso-overview/#choose-your-sso-protocol + - from: /docs/guides/oin-sso-overview/#okta-organization-and-multi-tenancy + to: /docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy + - from: /docs/guides/oin-sso-overview/#tenants-in-okta + to: /docs/concepts/multi-tenancy/#tenants-in-okta - from: /docs/guides/third-party-risk-integration/overview to: /docs/guides/third-party-risk-integration/ - from: /docs/guides/third-party-risk-integration/overview/index.html diff --git a/packages/@okta/vuepress-site/docs/concepts/multi-tenancy/index.md b/packages/@okta/vuepress-site/docs/concepts/multi-tenancy/index.md index d1f73729c83..26bdf9caa1b 100644 --- a/packages/@okta/vuepress-site/docs/concepts/multi-tenancy/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/multi-tenancy/index.md @@ -42,6 +42,20 @@ different types of data is shown below: +### Tenants in Okta + +In Okta, a tenant is represented as an Okta org. Each org is an isolated container that manages its own users, groups, and apps independently. Identity in Okta is scoped to the org, not globally unique across all of Okta. + +As an example, the same email address can exist as separate users in multiple orgs. For example, `alice.doe@example.com` can be a registered user in both `https://company1.okta.com` and `https://company2.okta.com` with different profile data in each. When building an app that serves multiple tenants, track which org authenticated a given user. You can't assume that profile data is consistent across orgs. + +Okta orgs host their interfaces through individual subdomains and each org is assigned a separate URL. The typical org URL is the tenant name (the subdomain) followed by the domain name. However, you can customize the domain name for your own domain and add individual aliases for each of your tenants. + +## SSO app integrations and multi-tenancy + +SSO app integrations are multi-tenant by design. Each customer (the organization deploying the SSO app) operates through a separate Okta org, and each org is a distinct tenant. The org serves as the identity provider (IdP) for that customer's users. For OpenID Connect (OIDC) integrations, the org acts as the authorization server. For SAML integrations, the org acts as the IdP. + +Because each org manages its own users, policies, and application access independently, a single app integration can serve multiple customers without their data or configurations affecting one another. + ## Why would you want more than one tenant An organization can create a tenant for various reasons. For example @@ -107,7 +121,7 @@ platform is ultimately decided by the customer. Okta offers four main configurations for multi-tenancy. They are: * [Configuration 1: Host tenants in a single org using Universal Directory (UD)](#configuration-1) -* [Configuration 2: Host tenants in separate orgs (for example, hub-and-spoke](#configuration-2) +* [Configuration 2: Host tenants in separate orgs (for example, hub-and-spoke)](#configuration-2) * [Configuration 3: Mixed. Host tenants in both single and separate orgs](#configuration-3) * [Configuration 4: Host tenants in a single org not using UD](#configuration-4) diff --git a/packages/@okta/vuepress-site/docs/concepts/sso-overview/index.md b/packages/@okta/vuepress-site/docs/concepts/sso-overview/index.md index 1196d3b39e1..48e83dfb27b 100644 --- a/packages/@okta/vuepress-site/docs/concepts/sso-overview/index.md +++ b/packages/@okta/vuepress-site/docs/concepts/sso-overview/index.md @@ -28,7 +28,7 @@ When you implement SSO, you let a central IdP handle authentication for you. SSO ## How Okta supports SSO -Okta is a cloud-based identity and access management (IAM) platform that acts as the centralized IdP for your users. Okta provides SSO integrations for thousands of cloud, on-premises, and mobile apps. The platform uses standard protocols such as OIDC, SAML, and SWA to maintain these integrations. +Okta is a cloud-based identity and access management (IAM) platform that acts as the centralized IdP for your users. Okta provides SSO integrations for thousands of cloud, on-premises, and mobile apps. The platform uses standard protocols such as OIDC, SAML, and SWA to maintain these integrations. Okta also handles user verification, multifactor authentication (MFA), and lifecycle management, providing a robust and secure foundation for your app. A user's SSO experience with Okta can happen in a few different ways: @@ -41,6 +41,18 @@ A user's SSO experience with Okta can happen in a few different ways: In these scenarios, the user only has to remember a single credential, which is managed securely by Okta. +## Choose your SSO protocol + +Okta supports two protocols for handling federated SSO: OpenID Connect (OIDC) and Security Assertion Markup Language (SAML). The SSO protocol that you choose to implement your app integration with is based on your app and use case. For new app integrations, OIDC is recommended. + +|   | ![OIDC](/img/idp-logos/oidc.png) OIDC | ![SAML](/img/idp-logos/saml.png) SAML | +| ------ | :------------------- | :----------------------- | +| **Description** | [OpenID Connect](/docs/concepts/oauth-openid/#openid-connect) extends OAuth 2.0 to provide an ID token that can be used to verify a user’s identity and sign them in to a cloud-based app. It's quickly becoming the new standard for SSO. | [Security Assertion Markup Language (SAML)](/docs/concepts/saml) is a traditional enterprise protocol for SSO in web apps. Okta supports SAML 2.0. | +| **Benefits** | | | +| **Technology** | | | +| **Resources** | | | +| **Get started** | | | + ## SSO, Single Logout (SLO), and Universal Login With SSO in Okta, a user authenticates once with Okta (the IdP) and can seamlessly access multiple apps, using federation protocols like SAML, OIDC, or WS-Fed. [​Single Logout (SLO)](/docs/guides/single-logout/saml2/main/) extends this by allowing a sign-out action from one app to propagate back to the IdP and, in turn, notify other connected apps to terminate their sessions. However, as SLO relies on each app’s protocol support, the sign-out experience can be inconsistent. @@ -51,5 +63,4 @@ Universal Logout addresses these inconsistencies by creating a more reliable, ce The Okta Integration Network (OIN) is a catalog of pre-built integrations with thousands of apps. You can easily integrate Okta SSO to apps with a guided experience that still supports the most secure configuration options. -For information on SSO integrations in the Okta Integration Network (OIN), see [Overview of Single Sign-On in the OIN](https://developer.okta.com/docs/guides/oin-sso-overview/). - +For information on SSO integrations in the Okta Integration Network (OIN), see [Publish an OIN integration](/docs/guides/submit-app-overview/). diff --git a/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/index.md b/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/index.md new file mode 100644 index 00000000000..f1b7f72ecb6 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/index.md @@ -0,0 +1,103 @@ +--- +title: Build a Single Sign-On (SSO) integration +excerpt: Create an app integration using Security Assertion Markup Language (SAML) or OpenID Connect (OIDC). +meta: + - name: description + content: Use this guide to learn how to integrate federated Single Sign-On with Okta for your app. +layout: Guides +--- + +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 outcome + +Create and test an SSO app integration for OIN submission. + +#### What you need + +* [Okta Integrator Free Plan org](https://developer.okta.com/signup/) +* 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 [What is Single Sign-On (SSO)?](/docs/concepts/sso-overview/). + +To create an SSO integration for the OIN, first sign up for a free [Integrator Free Plan org](https://developer.okta.com/signup/). 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](/docs/guides/submit-app-prereq/main/#oin-limitations). + +### Deployment models + +After you've decided on a protocol, select a deployment model. Okta offers [redirect](/docs/concepts/redirect-vs-embedded/#redirect-authentication) or [embedded](/docs/concepts/redirect-vs-embedded/#embedded-authentication) authentication deploy models. Redirect authentication uses the [Okta Sign-In Widget](https://github.com/okta/okta-signin-widget#okta-sign-in-widget) and is the easiest, most secure way to integrate with Okta. + +Okta recommends the redirect authentication deployment model if your situation meets the [requirements](/docs/concepts/redirect-vs-embedded/#redirect-okta-hosted-vs-embedded-self-hosted). For more information on deployment models, see [Okta deployment models—redirect vs. embedded](/docs/concepts/redirect-vs-embedded/). + +## Build your integration + + + +## Create your integration in Okta + +> **Note**: This section assumes that you already built the SSO integration in your app. + +Instructions for adding your SSO integration into Okta depend on if you want to provide a public or private integration: + +
+ +![Public or private integration decision](/img/oin/publicOrPrivateIntegration.png) + +
+ + + +### Submit an OIN integration + +If you want to publish your integration in the Okta Integration Network (OIN), follow the instructions in [OIN Wizard: Submit an SSO integration](/docs/guides/submit-oin-app/). This guide shows you how to use the OIN Wizard to: + +* Add required integration artifacts and metadata. +* Create an app integration instance for testing. +* Test your SSO flows. +* Submit your integration for OIN verification. + +Having your SSO integration public in the OIN catalog provides you with exposure to all Okta customers. + +> **Notes:** +> * Creating an app integration instance doesn't automatically make it available in the [OIN](https://www.okta.com/integrations/). After you test your integration, [submit it](/docs/guides/submit-oin-app/-/main/#submit-your-integration) to the OIN team for verification and publication. +> * The OIN Wizard doesn't support new SSO integrations with more than three app instance variables or advanced SAML features. + +### Add a private integration + +If you want your integration to exist only in your Okta org, follow the instructions in [Add a private SSO integration](/docs/guides/add-private-app/). This guide shows you how to use the Application Integration Wizard (AIW) in the Admin Console to: + +* Create your app integration instance. +* Test your SSO flows. + +Your org users can access your app after SSO is configured. + +The following are common use cases for adding a private SSO integration: + +* I want to test my SSO integration in my Integrator Free Plan org. I have no immediate plans to have it publicly available. +* I want my SSO integration to only be available in the org I'm using. +* I have a SAML integration with more than three instance variables and advanced SAML features that aren't included in the OIN Wizard. + +## Next steps + +If you want to publish your integration, start the submission process to have your SSO integration included in the OIN: + +* Review the [Publish an OIN integration](/docs/guides/submit-app-overview/) overview to understand the submission process for publishing an integration. +* Follow the [OIN Wizard: Submit an SSO integration](/docs/guides/submit-oin-app/) guide to submit your SSO integration. + +## See also + + diff --git a/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/openidconnect/prep.md b/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/openidconnect/prep.md new file mode 100644 index 00000000000..819af764798 --- /dev/null +++ b/packages/@okta/vuepress-site/docs/guides/build-sso-integration/main/openidconnect/prep.md @@ -0,0 +1,145 @@ +If you haven't built the OIDC service in your app yet, review the [OAuth 2.0 and OpenID Connect Overview](/docs/concepts/oauth-openid/). + +For OIDC integrations that you want to publish in the OIN catalog, review the following implementation topics: + +1. Use the Authorization Code flow with client secrets for your app. Select **Web Application** as the OIDC app type when you create your app integration in your Okta org. +1. [Determine the scopes](#scopes) that you require for your OIDC client (your app). +1. Consider how your app stores [customer client credentials](#oidc-customer-org-credentials). +1. Understand how to [validate tokens](#token-validation) 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. + +1. Implement credential rotation in your app. + + Your app must support automatic credential rotation. See [key rotation](#key-rotation). +1. 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. + +1. [Consider rate limits](#rate-limit-considerations) when you build your integration. + +After you've built the SSO integration in your app with the previous guidance list, test it with an Okta app integration instance. See [Create your integration in Okta](#create-your-integration-in-okta). + +### OIDC customer org credentials + +Okta uses a [multi-tenant](/docs/concepts/multi-tenancy/#sso-app-integrations-and-multi-tenancy) 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 app. + +This multi-tenant approach differs from other IdPs that use a global credential system, where a given app has the same customer credentials across all orgs. + +See the [OIN multi-tenancy](/docs/guides/submit-app-prereq/main/#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 app that you need to track. + +### Determine the OAuth 2.0 flow to use + +> **Note:** Quickstarts and example links provided in this section may use features not supported in the OIN. For example, the use of a custom authorization server isn't supported. + +Select the OAuth 2.0 flow to use based on your app: + +* For web apps: + + Okta mandates the [Authorization Code flow](/docs/guides/implement-grant-type/authcode/main/). 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. + > **Note:** The implicit flow is extremely challenging to implement securely. Therefore, Okta doesn’t recommend its use for token exchange in web apps. If your use case requires the use of an implicit flow for token exchange, contact [Okta Support](https://support.okta.com). + +* For single-page apps (SPA) and mobile apps: + + The OIN doesn’t support direct authentication from SPAs or native mobile apps. Instead, your backend systems must handle authentication. + +In this architecture, your SPA or mobile app shouldn’t manage tokens directly. Instead, use an intermediary system, such as an API gateway or a backend-for-frontend service, to facilitate communication between your client app and the resource server. Okta recommends implementing the authorization code flow for secure authentication and token exchange. + +> **Notes:** +> * Ensure that you select **Web Application** as the OIDC app type when you create your app integration in your Okta org. +> * Native and mobile app integrations aren't accepted as OIDC app integrations in the OIN unless they use server-side authentication patterns. 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. See [Implement the authorization code flow](/docs/guides/implement-grant-type/authcode/main/) to implement the OAuth 2.0 flow + +When you follow these guides, be aware of the authorization server used. Most of the examples show you how to make an `/authorize` or `/token` request using a [custom authorization server](/docs/concepts/auth-servers/#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). Therefore, for OIN OIDC apps, you can only use the [org authorization server](/docs/concepts/auth-servers/#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. + +> **Notes:** +> * When you use the org authorization server, the issuer URL is `https://{yourOktaDomain}`. +> * The `refresh_token` option isn't supported for apps published in the 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](https://developer.okta.com/docs/api/openapi/okta-oauth/guides/overview/#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 End-User 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 users click your app in their End-User Dashboard, they’re 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](https://developer.okta.com/docs/api/openapi/okta-oauth/oauth/tag/CustomAS/#tag/CustomAS/operation/introspectCustomAS) 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](/docs/concepts/key-rotation/) or the `/keys` [API endpoint](https://developer.okta.com/docs/api/openapi/okta-oauth/oauth/tag/CustomAS/#tag/CustomAS/operation/oauthKeysCustomAS) for specific details on handling queries and responses. + +### Rate limit considerations + +When you construct your SSO app, be aware of the limits on requests to Okta APIs. For information on the rate-limit categories, see the [Rate limits overview](/docs/reference/rate-limits/). 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](https://support.okta.com). + +You can request a temporary rate limit increase if you anticipate a large number of requests over a specified time period. Contact [Okta Support](https://support.okta.com) to open a ticket to permit the exception. See [How to Request a Temporary Rate Limit Increase](https://support.okta.com/help/s/article/How-can-we-request-to-have-the-rate-limit-for-our-org-temporarily-increased?language=en_US). + +> **Note:** The following public metadata endpoints aren't subjected to rate limits: +> * `/oauth2/v1/keys` +> * `/.well-known/openid-configuration` +> * `/.well-known/oauth-authorization-server` diff --git a/packages/@okta/vuepress-site/docs/guides/create-an-app-integration/main/index.md b/packages/@okta/vuepress-site/docs/guides/create-an-app-integration/main/index.md index 527047de9ed..e3fd11d9816 100644 --- a/packages/@okta/vuepress-site/docs/guides/create-an-app-integration/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/create-an-app-integration/main/index.md @@ -52,7 +52,7 @@ The following table summarizes the key differences: ### Supported protocols -Okta app integrations support standard protocols for both [SSO](https://developer.okta.com/docs/guides/oin-sso-overview/) and automated user provisioning: +Okta app integrations support standard protocols for both [SSO](/docs/concepts/sso-overview/) and automated user provisioning: * [OpenID Connect (OIDC)](https://developer.okta.com/docs/concepts/oauth-openid/): Authentication protocol based on OAuth 2.0, which enables secure SSO and supports advanced security features. * [Security Assertion Markup Language (SAML)](https://developer.okta.com/docs/concepts/saml/): An XML-based protocol for exchanging authentication and authorization data between Okta and external apps. diff --git a/packages/@okta/vuepress-site/docs/guides/index.md b/packages/@okta/vuepress-site/docs/guides/index.md index 4b1c3ad1f38..11a9f99008c 100644 --- a/packages/@okta/vuepress-site/docs/guides/index.md +++ b/packages/@okta/vuepress-site/docs/guides/index.md @@ -295,7 +295,7 @@ You can publish your integration in the Okta Integration Network (OIN) catalog t If you're creating an Okta integration for the first time, Okta recommends the following sequence of guides: 1. [OIN landing](/docs/guides/okta-integration-network/) -1. [Overview of Single Sign-On in the OIN](/docs/guides/oin-sso-overview/) +1. [What is Single Sign-On (SSO)?](/docs/concepts/sso-overview/) 1. [Overview of lifecycle management in the OIN](/docs/guides/oin-lifecycle-mgmt-overview/) 1. [Overview of API service apps in the OIN](/docs/guides/oin-api-service-overview/) 1. [OIN submission requirements](/docs/guides/submit-app-prereq/) diff --git a/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md b/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md index 0c5fd3125d0..c1fa20f2f43 100644 --- a/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md +++ b/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md @@ -4,105 +4,3 @@ meta: - name: description content: Provides a high level overview of Single Sign-On app integrations for the Okta Integration Network. --- - -The Okta Integration Network (OIN) is a collection of over 7000 pre-built app integrations to connect and exchange secure authentication between users, devices, and apps. Customers can easily integrate Okta Single Sign-On (SSO) to apps with a guided experience that still supports the most secure configuration options. - -To get your app integration into the OIN: - -1. [Build an app integration](/docs/guides/sign-in-overview/main/) using a free [Okta Integrator Free Plan org](https://developer.okta.com/signup/) and any of the wide array of [languages and libraries](/code/) supported by Okta. -1. [Submit your app](/docs/guides/submit-app-overview/) integration for verification and approval by the Okta OIN team. - -Your integration is available in the OIN for the Okta community to use after Okta validates and publishes your app integration. - -After your customer adds your SSO app integration to their Okta org, their workforce can use their company-issued Okta credentials to securely access your app. In addition to email-password credentials, your customers can control their authentication experience with Okta sign-on policies and features. See the [Multifactor Authentication](https://help.okta.com/okta_help.htm?id=ext_MFA) and [Okta FastPass](https://help.okta.com/okta_help.htm?type=oie&id=ext-fp-enable) features. - -## Why build an SSO integration with Okta? - -|   |   | -| ------ | ------ | -| **Enhance security** | Integrating with Okta allows your customers to manage password strength and configure access policies for your apps. For example, they may require employees to use multifactor authentication (such as a push notification to their phone or SMS) to access your apps from an unknown device. | -| **Deliver a strong end user access experience** | Take away all the friction of managing usernames and passwords. After users authenticate through Okta, they can access your apps with a single click. | -| **Enterprise ready** | Your customers have a growing set of compliance needs that are continuously evolving. An Okta app integration helps you meet compliance and audit requirements and shortens sales cycles. | -| **Ease of adoption** | Your customers can add SSO to your OIN-published app integration with minimal effort. They use Okta to add and configure your app integration into their identity ecosystem without extensive support from your customer service resources. Their workforce can access your app within hours of configuring the integration and policies. | - -## Choose your SSO protocol - -Okta supports two protocols for handling federated SSO: OpenID Connect (OIDC) and Security Assertion Markup Language (SAML). The SSO protocol that you choose to implement your app integration with is based on your app and use case. For new app integrations, OIDC is recommended. - -|   | ![OIDC](/img/idp-logos/oidc.png) OIDC | ![SAML](/img/idp-logos/saml.png) SAML | -| ------ | :------------------- | :----------------------- | -| **Description** | [OpenID Connect](/docs/concepts/oauth-openid/#openid-connect) extends OAuth 2.0 to provide an ID token that can be used to verify a user’s identity and sign them in to a cloud-based app. It's quickly becoming the new standard for SSO. | [Security Assertion Markup Language (SAML)](/docs/concepts/saml) is a traditional enterprise protocol for SSO in web apps. Okta supports SAML 2.0. | -| **Benefits** |
  • A newer protocol with widespread and growing use
  • Best Okta customer configuration experience
  • Ideal for mobile and cloud apps
|
  • Many people are familiar with SAML because it's an older protocol
  • Widely used federation protocol for SSO in web apps
  • Many SaaS providers support SAML integration to grant SSO access to end users
| -| **Technology** |
  • An identity layer on top of the [OAuth 2.0](https://oauth.net/2/) protocol
  • Verifies end user identity and obtains profile information
  • Lightweight and REST-based
|
  • XML-based messages
  • The specification doesn’t have user consent, although it can be built into the flow
| -| **Resources** |
  • [OpenID Connect Foundation](https://openid.net/connect/)
|
  • [SAML 2.0 Technical Overview](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html)
| -| **Get started** |
  • [Build an Okta SSO integration with OIDC](/docs/guides/sign-in-overview/main/)
|
  • [Build an Okta SSO integration with SAML](/docs/guides/create-an-app-integration/saml2/main/)
| - -> **Note:** For specific OIDC and SAML protocol features not supported in the OIN, see [OIN submission limitations](/docs/guides/submit-app-prereq/main/#oin-limitations). - -### Okta organization and multi-tenancy - -In a typical scenario, your app relies on Okta to act as a multi-tenant Identity Provider (IdP) for your customers' Okta orgs. An [Okta org](/docs/concepts/okta-organizations/) acts as a container that sets hard boundaries for all users, apps, and other entities that are associated with a single customer. This provides tenant-based isolation. In developing your SSO app integration, the customer’s Okta org serves as the authorization server (OIDC) or as the IdP (SAML). - -#### Tenants in Okta - -Within Okta, the concept of a tenant is instantiated as an Okta org. The org is the home for all user identity and access management, such as user store, handling connections, and mapping profile information. Your Okta org is used to authenticate your users for your apps. - -In Google Cloud products, the user identity is globally unique across the entire identity namespace through their email address. By contrast, in Okta the unique identity concept is specific to just within the tenant used to authenticate and authorize. Code your app so that it's aware of what tenant is being used to authenticate that user. - -As an example, `alice.doe@example.com` is a registered Okta user in both company 1 and company 2 Okta tenants, accessed at `https://company1.okta.com` and `https://company2.okta.com`. Your app aims to provide different services for users that are specific to each tenant. You can't assume that the user information is identical for a given user across both tenants. Your app needs to manage user credentials to identify each unique combination of user and tenant. - -Okta orgs host their interfaces through individual subdomains and each org is assigned a separate URL. The typical org URL is the tenant name (the subdomain) followed by the domain name. However, you can customize the domain name for your own domain and add individual aliases for each of your tenants. - -> **Note:** The process for specifying the variable app instance names in an OIDC app is explained in [Submit an SSO integration with the OIN Wizard: Integration variables](/docs/guides/submit-oin-app/openidconnect/main/#tenant-settings). - -## Use case examples - -### Example of a partner integration journey with Okta - -Erika is an app developer at Acme, a technology partner with Okta. Acme is looking to use the OIN as a way for their customers to adopt and incorporate Acme’s app to the customer’s existing Okta tenant. This allows Acme’s customers to add Acme’s app to their existing identity infrastructure with minimal integration resources. - -Erika performs the following tasks: - -* Builds the Acme-Okta integration, doing the heavy lifting so that their customers don’t have to -* Documents the required configuration steps for the customer admin -* Submits the app integration and corresponding documentation for the Okta OIN team to verify and review - -After approval, Acme’s app is published to the OIN. With a pre-built Acme-Okta integration, Acme avoids the extra support staff required for each individual customer integration. - -### Example of an identity admin journey with Okta - -Ali is an IT admin at Initech. Initech is looking to add Acme's app into their existing Okta identity infrastructure. - -Ali performs the following tasks: - -* Finds the Acme app in the OIN catalog. Since Acme is in the OIN, Ali knows that he can trust Acme to be securely incorporated into their existing Okta-managed SSO with minimal effort. -* Adds the Acme app integration from the Admin Console -* Follows the instructions provided by Acme to configure the app integration -* Configures the Okta app sign-in policy and the group of Initech employees who have access to the Acme app -* Tests signing in to the Acme app with existing Okta credentials to verify the authentication flow - -Initech's group of employees with privileges can sign in to the Acme app with their existing Okta credentials. No additional Acme app registration is required. - -### Example of an enterprise user Single Sign-On journey with Okta - -Ramon is an Initech employee with access to the Acme app. Follow his SSO journey: - -* Ramon starts his work day. In his web browser, he clicks the Okta browser extension and selects his email app, which loads in a new tab. -* Initech has an Okta global session policy, which requires each employee to verify their identity every 12 hours. Since it’s been more than 12 hours since he last worked, Ramon is prompted to enter his Okta username and password. -* Initech has also enabled Okta multifactor authentication. After Ramon successfully entered his credentials, a push notification is sent to the Okta Verify app on his phone. Ramon taps his phone to verify his identity. He can now access his email. -* Next, Ramon goes to his Okta browser extension and selects the Acme app. Since he started a session less than 12 hours ago, he has access to the app without needing to sign in again. Ramon can access all the Okta-integrated apps that he has privileges to without signing in again because he already has an authenticated session with Okta. - -## Next steps - -Ready to get started? Choose how you want to implement your SSO app integration: - - -Build an Okta SSO integration with OIDC - -Build an Okta SSO integration with SAML - -
- -After your app integration is built, [submit the integration](/docs/guides/submit-app-overview/) to the Okta OIN team for verification and publication. - -Want to automate even more for your customers and increase adoption of your product? Learn more about [lifecycle management integration](/docs/guides/oin-lifecycle-mgmt-overview/) in the OIN. diff --git a/packages/@okta/vuepress-site/docs/guides/submit-app-prereq/main/index.md b/packages/@okta/vuepress-site/docs/guides/submit-app-prereq/main/index.md index b30f469b0ec..bec72951f5d 100644 --- a/packages/@okta/vuepress-site/docs/guides/submit-app-prereq/main/index.md +++ b/packages/@okta/vuepress-site/docs/guides/submit-app-prereq/main/index.md @@ -45,7 +45,7 @@ Your app integration must support multi-tenancy to be listed in the public OIN c What does this mean? -Multi-tenancy in the OIN refers to the concept that as an ISV, you support several instances of your app. Each app instance has a unique credential system for each of your customers. An instance of an app that contains the infrastructure to support a group of users is considered a tenant. See [Tenants in Okta](/docs/guides/oin-sso-overview/#tenants-in-okta). +Multi-tenancy in the OIN refers to the concept that as an ISV, you support several instances of your app. Each app instance has a unique credential system for each of your customers. An instance of an app that contains the infrastructure to support a group of users is considered a tenant. See [Tenants in Okta](/docs/concepts/multi-tenancy/#tenants-in-okta). Provide a method for each of your customer tenants to uniquely connect to their Okta org. This allows your customers to find your app integration from the OIN catalog in their own Okta org. Then, they can instantiate the app integration with their unique tenant credentials, either with your support or on their own. diff --git a/packages/@okta/vuepress-site/docs/guides/submit-oin-app/main/openidconnect/protocol-supported.md b/packages/@okta/vuepress-site/docs/guides/submit-oin-app/main/openidconnect/protocol-supported.md index de16ba3806b..0d8286e25f7 100644 --- a/packages/@okta/vuepress-site/docs/guides/submit-oin-app/main/openidconnect/protocol-supported.md +++ b/packages/@okta/vuepress-site/docs/guides/submit-oin-app/main/openidconnect/protocol-supported.md @@ -12,6 +12,8 @@ This guide covers submissions that use the following protocols and integrations: * [Universal Logout](/docs/guides/oin-universal-logout-overview/) +See [Choose your SSO protocol](/docs/concepts/sso-overview/#choose-your-sso-protocol) for help choosing the right protocol for your app integration. + > **Notes:** > * Universal Logout integrations are only supported for the SAML 2.0 and OIDC protocols. If you want to submit a Universal Logout integration with SCIM provisioning, you must also submit an SSO integration with either SAML 2.0 or OIDC. > * Entitlement Management is supported for integrations that manage entitlements through a SCIM server. From 346b046acd84781998aa0a45a4ce251bbb41b4d3 Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 15 May 2026 15:19:56 -0400 Subject: [PATCH 2/3] Delete old file --- .../vuepress-site/docs/guides/oin-sso-overview/index.md | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md diff --git a/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md b/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md deleted file mode 100644 index c1fa20f2f43..00000000000 --- a/packages/@okta/vuepress-site/docs/guides/oin-sso-overview/index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Overview of Single Sign-On in the OIN -meta: - - name: description - content: Provides a high level overview of Single Sign-On app integrations for the Okta Integration Network. ---- From ba562557748c82456c2ccbf9393e16f55043c58d Mon Sep 17 00:00:00 2001 From: Thomas Cavanagh Date: Fri, 15 May 2026 15:57:42 -0400 Subject: [PATCH 3/3] Fixing broken links --- .../OktaIntegrationNetwork/components/Explore.vue | 2 +- .../OktaIntegrationNetwork/components/Features.vue | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Explore.vue b/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Explore.vue index e02617edc72..f2aaf61be77 100644 --- a/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Explore.vue +++ b/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Explore.vue @@ -56,7 +56,7 @@ caption: 'Design & build', text: 'OIN is a catalog and a support system. View SSO, lifecycle, and service app integration guides to help you to design, build, and test your integration before you submit it for verification. Get support from the Okta Developer Forum during your build journey.', link: 'Start with SSO', - path: '/docs/guides/oin-sso-overview/' + path: '/docs/concepts/sso-overview/' }, { id: 3, diff --git a/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Features.vue b/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Features.vue index b86de6e29bc..b68443dd2e7 100644 --- a/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Features.vue +++ b/packages/@okta/vuepress-theme-prose/custom-landings/OktaIntegrationNetwork/components/Features.vue @@ -102,7 +102,7 @@ id: 1, title: 'Enable Single Sign-On', text: 'Let users securely sign in to your app with their credentials.', - link: '/docs/guides/oin-sso-overview/', + link: '/docs/concepts/sso-overview/', linkText: 'Get started with Single Sign-On', list: [ 'Streamline the sign-in flow',