Submit an SSO integration

Deprecated

Deprecated: As of release 2024.01.0 (Jan 10, 2024), you can't submit new Single Sign-On (SSO) integrations using the OIN Manager. Use the new OIN Wizard for a seamless ISV submission experience. Okta is in the process of migrating published integrations from the OIN Manager to the OIN Wizard. If your published integration hasn't been migrated yet, you can still use the OIN Manager to update integrations. See Submission process for OIN submission guidance.

---

Learning outcomes

• Understand how to submit an SSO integration to the Okta Integration Network (OIN) with the OIN Manager.
• Learn how to update or delete a previously published OIN SSO integration with the OIN Manager.

What you need

• The various items necessary for submission in accordance with the OIN submission requirements

---

Overview

The Okta Integration Network (OIN) Manager (opens new window) is a submission tool that's connected to your developer org where you test and develop your Okta integration. Use this tool to submit your SSO app integration for verification and publication in the OIN catalog.

Protocols supported

This guide covers submissions that use the following protocols:

• OpenID Connect (OIDC) (opens new window)

  Note:
  

  • To support the potentially large number of Okta orgs that access an authorization server through the OIN, an OIDC integration can't use a custom authorization server, including the default server.
  • ISVs shouldn'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.

• Security Assertion Markup Language (SAML) (opens new window)

  Note: SAML integrations must use SHA256 encryption for security. If you're using SHA-1 for encryption, see our guide on how to Upgrade SAML Apps to SHA256.

Note: SWA app integrations are no longer accepted for publication in the OIN catalog. However, the OIN team still maintains existing SWA apps.

Submission support

If you need help during the submission process, use the Get Support section on the My App Integrations page after you sign in to the OIN Manager (opens new window). This section provides the following resources from the Okta developer portal (opens new window):

• OIN integration guides
• Okta, OIDC, SAML, and SCIM concepts
• A search tool to find articles in the Okta developer portal

If you have questions or need more support to publish your app integration, you can reach out to the Okta OIN team directly at oin@okta.com.

Submit an integration

Deprecated

Deprecated: As of release 2024.01.0 (Jan 10, 2024), you can't submit new Single Sign-On (SSO) integrations using the OIN Manager. Use the new OIN Wizard for a seamless ISV submission experience.

Review the OIN submission requirements before you start your submission.

1. Open the OIN Manager (opens new window) and click Start Submission Form.

2. Sign in to the OIN Manager with your Okta development org credentials. Ensure that this org contains your developed app integration for submission.

3. Click Add New Submission.

4. Click View beside the name of your integration if you want to review an in-progress submission.

   Note: If you need to update an integration, see Update your published integration.

5. Begin defining your submission by specifying details in the General Settings and protocol-specific tabs.

Configure general settings

On the General Settings tab, fill in the basic information about your integration:

App information

• Does your app exist in the OIN?: Indicate if your integration exists in the OIN.

  • If your integration exists in the OIN, provide the Existing OIN app name so that the Okta OIN team can locate it.

  • What changes are you making to the existing OIN integration?: If your integration exists in the OIN, summarize the changes that you're requesting in your update. This summary helps the Okta OIN team address your changes.

• App name: Provide a name for your integration. This is the main title used for your integration in the OIN.

• App website: Provide a link to your product or service homepage or a specific location on your website where users can learn more about your integration.

• Use case(s): Specify one or more use cases for Okta to categorize your integration in the OIN catalog. Click + Add Another to choose up to five use cases. See Use case guidelines.

• App description: Give a general description of your app and what the Okta integration does. See App description guidelines.

• App icon: Upload a PNG, JPG, or GIF file of a logo to accompany your integration in the catalog. The logo file must be less than one MB. See Logo guidelines.

Customer support

• Support contacts: Include one or more public contact points for users who need assistance with your integration. You can also add a link to an FAQ or a troubleshooting guide. Use the dropdown menu to specify if you're adding an email, a URL, or a phone number. Click + Add Another to add another contact. Okta shares this information with customers in the OIN catalog description for your app integration.

• Escalation support contact: This is an email distribution list for Okta to use when contacting your company about your integration. Okta can use this escalation contact in an emergency, so make sure that the contact provided here isn't a generic contact, such as support@example.com or a 1-800 number. This contact information isn't shared with customers.

See Customer support contact guidelines.

Test account

The Okta OIN team requires a dedicated account on your app to run their tests. Ensure that this test account is active beyond the submission period in case Okta needs to update or troubleshoot your app integration. See Test account guidelines.

• Test account URL: This is a static URL to sign in to your app. An Okta OIN team member goes to this URL and uses the account credentials that you provide in the subsequent fields to sign in to your app.

• Test account username or email: The username for your app test account. The Okta OIN team signs in with this username to run tests. The preferred account username is isvtest@okta.com.

• Test account password: The password for your app test account

• Additional instructions: Include any other information that you think the Okta OIN team needs to know about your integration, the test account, or the testing configuration.

Configure protocol-specific settings

You can submit protocol support details all together or asynchronously. For example, if your app currently only supports SAML, you can create the submission with the SAML protocol details. Later, when you add Workflows Connector capabilities to your app, you can return to your integration submission to include Workflows Connector support.

Note: If you don't see the protocol-specific settings that you want in this section, select the Instructions for dropdown menu on this page.

SAML

To submit a SAML integration, click the SAML tab and select On from the SAML support dropdown menu.

• Provide the instance URL for your app where Okta will retrieve configuration details: Specify the Okta instance URL for your integration.

  To retrieve your Okta instance URL from your development org:

  1. From the Okta Admin Console, navigate to Applications > Applications to see all the integrations in your org.
  2. Click the name of the app integration that you're going to submit.
  3. Confirm that the app settings match what you want as the global defaults for all customers.
  4. In your browser, click in the address bar showing the current URL and copy it to your clipboard. This is the Okta instance URL for your integration.
  5. Back in the OIN Manager, paste that URL in the Provide the instance URL for your app where Okta will retrieve configuration details field of your submission protocol tab.

Setup instructions

• Is your Service Provider configured as a “Big Bang”?: If Yes, what is the backdoor URL for admins to sign in if SAML is misconfigured? If the SP is a "Big Bang", Okta suggests that you have a backdoor URL or some other recovery mechanism available.

• Is SAML support available in the SP for all tenants by default or is it available only for specific SKUs?: If you select Certain SKUs, provide details on which products provide SAML support.

• To configure SAML, can your customers do it by themselves from your app's UI, or do they need to contact your support team?: If a customer needs support to configure your app integration, you need to include support contact information in your configuration guide. See SAML configuration steps example for configuration steps when the customer requires the support team to configure SAML. See SAML admin configuration steps example for configuration steps when the customer configures SAML for themselves. Okta recommends that you build a UI that enables self-service configuration to reduce the setup time for your customers.

• Are tenants deployed on-premises?: If tenant data for your application is hosted locally on your customer's systems, select Yes. If the tenant data for your application is hosted on your servers, select No.

• Is your app capable of requesting other SSO URLs?: Select this option to configure support for multiple ACS URLs where the SAML Response can be sent. If Yes, specify an index or URL to identify each ACS URL endpoint. If an AuthnRequest message does not specify an index or URL, the SAML Response is sent to the default ACS URL specified above. Enter the SSO URLs and an index value for any other nodes. You can specify variables in the SSO URL field to construct non-static URLs, for example, https://${app.variableName}.okta.com.

• What is the unique SAML identifier for authentication: the subject NameID or a specific SAML attribute?: What identifier is used by the integration to perform authentication against your SAML application? If you are using an attribute different than the NameID attribute, what is the name of that attribute?

• Link to configuration guide: Your configuration guide (in HTML or PDF format) should have step-by-step instructions on how to configure SSO between Okta and your systems. See Customer configuration document guidelines.

Configure variables

• Does your ACS URL or Audience URI vary per tenant?: If you select No, the ACS URL and Audience URI are pulled from the app during the submission review. If you select Yes, new fields appear to assist you in setting up a per tenant configuration.

  • What variables do your admins need to specify to install your app?: When you click Add Variable, the interface displays a dialog box to collect the following information:

    • Label Name: A descriptive name for the dynamic variable that administrators see when installing your app integration.
    • Variable Name: An automatically generated variable used when constructing the dynamic address. This is hidden from admins and is only passed to your external application.
    • Help Text: Any descriptive text to be shown to administrators about the variable when they install your app integration.
    • Type: The property type for your parameter. Options are "String", "URL", or "HTTPS URL".

    Click Save to add the variable to the list.

    After the variable is created, you can click the pencil icon to make changes to the details, the clipboard icon to copy the Variable Name to your local clipboard, or the "X" icon to remove the variable entirely.

  • Construct your dynamic ACS URL by copying the variables above and pasting them where applicable: Provide your complete Assertion Consumer Service (ACS) URL endpoint where Okta posts SAML responses for your app integration.

    If you're using a per tenant design, include the variable names that you created. For example:

    • https://${app.variableName}.okta.com
    • https://okta-${app.variableName}.com
    • ${app.variableName}/route

    Note: A variable can include a complete URL (for example, https://example.com). This enables you to use more globally useful variables such as org.baseURL.

  • Construct your dynamic Audience URI by copying the variables above and pasting them where applicable: Provide your complete Audience URI. This field, which dictates the audience the SAML Assertion is intended for, can be any data string up to 1024 characters long.

    It is typically in the form of a URL, often the same as the ACS URL for your app integration. If you're using a per tenant design, include the variable names that you created, the same as for the ACS URL.

Supported features

• Do you support SAML Just-In-Time provisioning?: With Just-in-Time provisioning, you can use a SAML assertion to create users on the fly the first time they try to sign in. This eliminates the need to create user accounts in advance.

• Do you support receiving SAML user/group attribute statements?: If Yes, you can add the attribute statements or group attribute statements in the provided fields. For more details on configuring attribute statements in SAML integrations, see Create a SAML integration using AIW (opens new window).

• Okta requires that all SAML integrations support multi-tenancy. Do you support this in your implementation?: Select Yes if your customers can set up a SAML connection between their tenant in your application and multiple external IdPs or even multiple instances inside a single IdP. See OIN multi-tenancy.

• What type(s) of sign-in flows do you support?: Choose from IdP or SP initiated, or both. If you support SP-initiated flows, you must specify the URL used to initiate the SP flow and include a description of how the SP flow is triggered by your integration.

• Force authentication?: Select Yes if your application forces users to authenticate again, even if they have an existing session. If you select Yes, include how customers configure force authentication on your end. Provide the steps for Okta to test this forced authentication.

• Do you use encrypted assertions?: Select Yes if you support an encryption method for authentication assertion.

  • Encryption Algorithm: Select which standard algorithm is used in your encryption assertion.
  • Key Transport Algorithm: Select the key transport algorithm used in your encryption.
  • Are you going to use the same encryption certificate for all tenants?: If you support the same encryption certificate for all tenants, copy your certificate and paste it in the field provided.

• Do you support SP-initiated Single-Logout?: If you select No, there is nothing to configure in this section. If you select Yes, then more questions appear to help you set up your SP-initiated single-logout (SLO) configuration.

  • Does your Single-Logout URL vary per tenant?: If you select Yes, new app instance properties appear to assist you in setting up a per tenant configuration.

    • What variables do your admins need to specify to install your app?: When you click Add Variable, a dialog box appears to collect the following information:

      • Label Name: A descriptive name for the dynamic variable that administrators see when installing your app integration. For example, sloBase.
      • Variable Name: An automatically generated variable used when constructing the dynamic address. This is hidden from admins and is only passed to your external application. For example, ${org.slobase}.
      • Help Text: Any descriptive text to be shown to administrators about the variable when they install your app integration.
      • Type: The property type for your parameter. Options are "String", "URL", or "HTTPS URL".

      Click Save to add the variable to the list.

      After the variable is created, you can click the pencil icon to make changes to the details, the clipboard icon to copy the Variable Name to your local clipboard, or the "X" icon to remove the variable entirely.

    • Construct your dynamic Single-Logout URL by copying the variables above and pasting them where applicable: Provide your complete SLO URL endpoint where Okta redirects for your app integration single-logout. For example, ${org.slobase}/signout.

  • Are you going to use the same single-logout certificate for all tenants?: Select Yes if you support the same single-logout certificate for all tenants. Copy your certificate and paste it in the field provided.

    The Single Logout URL and SP Issuer should be specified in the test application.

    Note: Okta only supports Single Logout requests.

• Do you require a default relay state: The default relay state is the page where your users land after they successfully sign in. If you have this configured, enter a specific application resource for an IdP-initiated Single Sign-On (SSO) scenario.

Review info

• Optional: link to demo video: If you have a video that explains how to configure access to your SAML application, enter the URL here. A short demo video showing your working test application helps expedite the review process. Please show the IdP and SP-initiated sign-in flows and sign-out (if applicable).

• Optional: link to the test results of a SAML validation tool: Use the tool at http://saml.oktadev.com (opens new window) to validate your SAML Service Provider implementation. The results help expedite the review process.

As you add configuration information about your integration to the submission page, the indicators in the upper-right corner of the page show your progress towards 100% completion.

Include all required information before you click Submit for Review to move your integration into the submission phase.

Update your published integration

Note: Okta is migrating published SSO integrations from the OIN Manager to the OIN Wizard:

• If your published SSO integration was migrated to the OIN Wizard, make updates in the OIN Wizard. A deprecated note appears next to your integration in the OIN Manager. If you edit and submit your migrated integration from the OIN Manager, it won't be reviewed by the OIN team.
• If your published SSO integration wasn't migrated to the OIN Wizard, it appears as usual in the OIN Manager. Follow the steps in this section to update your published integration in the OIN Manager.

When you enable a new capability in your app, you don't need to create an entirely new submission. For example, you can add SCIM provisioning to an existing published SAML app. You can update your existing submission to enable and specify the settings for that protocol, then submit the updated integration.

1. Sign in to the OIN Manager using the credentials for your original dev org.

   Note: Submit the updated integration using the same dev org that was used to make the original submission, otherwise the Okta OIN team rejects the update.

   The published integration appears on your integrations page.

2. Click Update.

   This creates an instance of your integration where you can safely change any of the parameters. Your existing integration remains in the OIN catalog and keeps the previous settings until this new version is published.

3. Update any of the parameters for your existing protocols or add a protocol depending on your needs.

   If you need to leave your in-progress submission at any point, you can return to it through the OIN Manager. When you sign in again, the published version and your in-progress version appear. Click Edit on the in-progress version to continue.

4. Click Submit for Review when you complete the updates or fill in the new protocol information. Ensure that the indicator shows 100% complete before you submit.

   At this point, the Okta OIN team is notified and your submission undergoes the same process flow as the original submission.

   Okta publishes the new version of your integration after it reaches the Publish stage. The new version replaces the old one in the OIN catalog.

Note: You can have a maximum of 10 submissions for any development org in the OIN Manager.

Delete draft submissions

There are two scenarios where you need to delete a draft submission:

1. You have 10 draft submissions, which is the maximum number permitted in the OIN Manager.
2. You've decided against completing a draft submission and want to remove it.

In either of these scenarios, the OIN Manager provides a method to delete unpublished submissions. For instructions on how to delete app integrations that are already published in the OIN catalog, see Delete published submissions.

You can only delete unpublished submissions that are in DRAFT state.

To delete your submission:

1. Click the delete icon next to Edit. If the delete icon is unavailable, you can't delete that submission.
2. Confirm the deletion in the dialog.

No email confirmation is sent when deleting a submission. You can't recover deleted submissions.

If you need assistance with deleting a draft submission, contact the Okta OIN team at oin@okta.com.

Delete published submissions

If you want to remove an app integration that's already published in the OIN catalog, contact the Okta OIN team. Only the Okta OIN team can remove published integrations in the catalog. Send an email to oin@okta.com with the URL of your dev org, the name of the app integration, and a link to its location in the OIN catalog.

Removing an app integration from the OIN doesn't prohibit existing users from accessing it. The app integration isn't removed from end-user dashboards until an admin for the customer's org removes the app integration from their org.

Finally, if you intend to remove your back-end app support for your Okta integration, alert your customer admins about the change. Inform your customers if you're deploying a replacement solution.

See also

• SAML - Frequently Asked Questions
• Okta Developer Forum: SAML (opens new window)