Instructions for

Publish an OIN integration

This guide walks you through the process of submitting a Workflows connector, OIDC, SAML 2.0, or SCIM integration to the Okta Integration Network (OIN). It also shows you how to update a previously published integration or delete a draft submission.

Note: For submitting API service integrations, see Build an API service integration.

Learning outcomes

Understand how to submit a new integration to the OIN.
Understand how to update a previously published integration.
Understand how to delete a draft submission or delete a published integration.

What you need

A functional integration created and tested in accordance with one of our OIN guides:

Overview

The Okta Integration Network (OIN) is the identity industry’s broadest and deepest set of pre-built cloud integrations to manage access management, authentication, and provisioning. By adding your integration to the OIN, you can gain exposure to thousands of Okta customers who can discover your integration and deploy your application to millions of users. OIN integrations speed adoption by simplifying configuration steps and reducing friction for your customers.

If you're an independent software vendor (ISV), Okta customer, or IT system integrator who wants to add their integration to the Okta Integration Network (opens new window), read this guide for instructions on how to submit your integration. Adding your integration to the Okta Integration Network is completely free.

Protocols supported

This guide covers submissions that use one or more of these protocols or tools:

System for Cross-domain Identity Management (SCIM) (opens new window)
OpenID Connect (OIDC) (opens new window)
Note:
- To support the potentially large numbers of Okta orgs accessing 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.
Okta Workflows (opens new window)

Note: For submitting API service integrations, see Build an API service integration.

Submission process

After you have built a functioning app integration, a few steps are required to submit it to Okta for review and publication in the OIN:

Review the OIN submission requirements and prepare the various items required during submission. See the following guidelines:
Submit your integration to Okta through the OIN Manager tool. Your submission must provide Okta with the general and protocol or tool-specific metadata that's required to create a customized integration for publication in the OIN.

Note: In the OIN manager, the Profile Sourcing option (formerly known as Profile Mastering) is enabled for developer orgs by Okta Developer Support. You can contact your Okta account team or post on our forum (opens new window) to request temporary activation of this capability when submitting a SCIM app integration.
Work with the Okta OIN team to test your integration using your input and then get it published to the OIN Catalog.

The Okta OIN team reviews all submissions on a best-case basis.

If the Okta OIN team identifies any issues in the initial review and QA testing phases, you are sent an email with the specific details. At any point in the process, you can check the status of your submission in the OIN Manager (opens new window).

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

Understand the submission review process

The submission review process begins when you click Submit for Review in the OIN Manager (opens new window). Okta sends you an email notification that your integration is now queued for review by the Okta OIN team, which includes the date that the initial review of the integration is expected to finish.

The OIN Manager shows the current status of your integration.

Step 1: Initial review

Pending review by Okta: The Okta OIN team is notified of your submission. Okta reviews the submission and notifies you by email when the submission review is complete.
Action required: Okta has reviewed your submission and found issues that require your attention. Check your email for results from the Okta initial review. Sign in to OIN Manager, update the requested details, and click Submit for Review. After the OIN team reviews your updated submission and verifies that the issues are resolved, your submission moves to step two for QA testing.

Step 2: Code review

Pending review by Okta: The Okta OIN team conducts internal QA tests and notifies you by email when the QA review is complete. If the QA test is successful, your submission is automatically published in the OIN.
Action required: Okta has found QA issues that require your correction. Check your email for results from the Okta QA review. Make the requested changes as an update to your existing submission.
Final review by Okta: The Okta OIN team conducts a final internal QA test based on previously requested changes and notifies you by email when the final QA review is complete. If the review is successful, your submission is automatically published in the OIN.

Step 3: Published

Congratulations, your integration is published in the OIN!

The following flowchart outlines the entire process:

ISV Submission process flow

Submission support

Getting your app integration in the OIN catalog involves two phases: creating a functional integration and submitting it through the OIN publication process. For each phase in the process, Okta has an associated support stream to assist you.

When you're constructing your Okta integration, you can post a question on the Okta Developer Forum (opens new window).

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 additional support to publish your app integration, you can reach out to the Okta OIN team directly at oin@okta.com.

Note: All integrations in the OIN catalog are public. If you want to submit a request to create a private app integration for an application that uses SCIM 1.1 or Profile Sourcing, or for an application that uses a custom header expression for the Header Auth, then use the SCIM App Integration Wizard (opens new window) to create your integration and submit your app through the OIN Manager (opens new window). The Okta OIN team works with you to create an internal-only integration that isn't included in the OIN.

Submit an integration

To start your integration submission, open the OIN Manager (opens new window) and click Start Submission Form.
Sign in to the OIN Manager with your Okta development org credentials. Ensure that this org contains your developed app integration for submission.
Click Add New Submission to create a new submission instance.
If you want to review an in-progress submission, click View beside the name of your integration.

Note: If you need to update an integration, see Update your published integration.
Begin defining your submission by specifying details in the General Settings and protocol or tool-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 already 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 already 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 application 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 in size. 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, and then click + Add Another to add additional contacts. 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 application to run their tests. This test account needs to be kept 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 application. An Okta OIN team member navigates to this URL and uses the account credentials you provide in the subsequent fields to sign in to your application.
Test account username or email: The username for your application 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 application 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 or tool-specific settings

If your integration isn't a Workflows connector, then your application needs to support at least one protocol for interacting with Okta: OIDC or SAML for authentication, or SCIM for provisioning. For API service integrations, see Build an API service integration for API Service tab descriptions.

You can submit protocol support details all together or asynchronously. For example, if your application currently only supports SAML and SCIM, you can create the submission with the SAML and SCIM protocol details. At a later date, when you add OIDC support to your application, you can return to your integration submission, activate the OIDC support panel, and add in the details needed for Okta to enable OIDC support.

Note: Select the Instructions for dropdown menu on this page for the protocol or tool tab descriptions in the following section.

To submit an OIDC integration, click the OIDC tab and select On from the OIDC 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.

OIDC settings

Does your Redirect URI vary per tenant?: If Yes, a new field appears 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 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 when installing 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 you create the variable, 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 Redirect URI by copying the variables above and pasting them where applicable: Provide one or more complete sign-in redirect URIs where Okta sends the OAuth responses for your app integration. You must add at least one valid redirect URI.
  
  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}.
Do you require an Initiate Login URI (Optional): Include a sign-in URI if you want the Okta integration to handle redirecting your users to your application to start the sign-in request. When end users click a tile in their Okta dashboard, they are redirected to the initiate_login_uri of the client application, which constructs an authorization request and redirects the end user back to Okta.
- Does your Initiate Login URI vary per tenant?: If Yes, an additional field appears to assist you in setting up a per tenant configuration. The instructions for adding and using the custom variables are identical to the per tenant instructions for the Redirect URI.
- Enter your Initiate Login URI: Provide the complete sign-in URI for your app integration, including the variable names if you're using a per tenant design.
Do you require a Post Logout Redirect URI? (Optional): Include a sign-out Redirect URI if you have a location where you want to send your end user after they sign out of your application.
- Does your Post Logout URI vary per tenant?: If Yes, an additional field appears to assist you in setting up a per tenant configuration. The instructions for adding and using the custom variables are identical to the per tenant instructions for the Redirect URI.
- Enter your Post Logout Redirect URI: Provide the complete sign-out redirect URI for your app integration, including the variable names if you're using a per tenant design.
Okta requires that all OIDC integrations support multi-tenancy. Do you support this in your implementation?: Select Yes if your customers can set up an OIDC connection between their tenant in your application and multiple external IdPs or even multiple instances inside a single IdP.
To configure OIDC, 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. We recommend that you build a UI that enables self-service configuration to reduce the setup time for your customers.
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.
What type of sign-in flows do you support?: Choose either IdP initiated or SP initiated, or both.
Select the OIDC mode supported by your application: Choose either SPA (for Single-Page Application) or Web.

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

You must include all required information before you can click Submit for Review to move your integration into the submission phase.

Update your published integration

If you need to make protocol changes to your integration that is already published in the OIN catalog, you can visit the OIN Manager (opens new window) and create an updated version of the integration.

Similarly, when you enable a new capability in your application (for example, adding SCIM provisioning onto an existing published SAML application), you don't need to create an entirely new submission. You can update your existing submission to enable and specify the settings for that protocol, then submit the updated integration.

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

Note: You must 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. Click Update.

This creates a new 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.
Update any of the parameters for your existing protocols or add a new 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 on again, the published version and your in-progress version appears. Click Edit on the in-progress version to pick up where you left off.
When you complete the updates or fill in the new protocol information so that the indicator shows 100% complete, you can click Submit for Review.

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

After the new version of the integration reaches the Publish stage and is published by Okta, 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:

You have 10 draft submissions, which is the maximum number permitted in the OIN Manager.
You have 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:

Click the delete icon beside the Edit button. If the delete icon is unavailable, that submission can't be deleted.
Confirm the deletion in the dialog box.

No email confirmation is sent when deleting a submission. Deleted submissions can't be recovered.

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 is already published to the OIN catalog, this change must be processed by the Okta OIN team. 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 won't be removed from end-user dashboards until an admin for the customer's org removes the app integration from the org.

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

On this page