On This Page
Publish an OIN integration
This guide walks you through the process of submitting a SCIM, OIDC, or SAML 2.0 app to the Okta Integration Network (OIN), including preparation, configuration, and updating published integrations.
- Submit a new app to the OIN.
- Update a previously-submitted app.
What you need
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 are 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.
This guide covers submissions that use one or more of these protocols:
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
Note: ISVs shouldn't rely on the
email_verifiedscope-dependent claim returned by an OIDC integration to evaluate whether a user has verified ownership of the email address associated with their profile.
Note: SAML integrations must use SHA256 encryption for security. If you are using SHA-1 for encryption, see our guide on how to Upgrade SAML Apps to SHA256.
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:
Create a customer-facing configuration guide.
Note: This guide is required for SCIM and OIDC OIN apps. It's optional for SAML integrations, as Okta provides its own documentation for those apps. The guide is supplied with your published app.
Submit your integration to Okta through the OIN Manager tool. Your submission must provide Okta with the general and protocol-specific metadata that is 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 email@example.com to have this capability temporarily activated 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.
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 are constructing your Okta integration, you can post a question on the Okta Developer Forum (opens new window).
When you are troubleshooting a submission or need to know the current publication status, sign in to the OIN Manager (opens new window) using your dev credentials. You can make any necessary changes to your submission there. If you have questions or need additional support to publish your app integration, you can reach out to the Okta OIN team directly at firstname.lastname@example.org.
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.
A configuration guide helps your customers understand how to configure your Okta integration to work with your cloud application.
You need to provide a configuration guide as part of the OIN submission process. Your guide is provided to administrators through the Okta Admin Console. Okta checks your document for general adherence to the configuration guide instructions. After your integration is published to the OIN, you can make the link public or customer‐accessible.
Note: A configuration guide is required for SCIM and OIDC integrations. It's optional for SAML integrations, as Okta supplies its own documentation with the apps.
You can create the guide in whatever format works best for you: a Web page, a Google or Word doc, or a PDF are all acceptable.
Some examples of detailed configuration guides:
- GitHub Enterprise (opens new window)
- Runscope (opens new window)
- Salesforce (opens new window)
- Zoom.us (opens new window)
- Atlassian Cloud (opens new window)
- Contentful (opens new window)
- Fuze (opens new window) (PDF link)
- Zscaler (opens new window)
Your configuration guide should include the following sections:
In this section, specify any prerequisites required before your customer configures your integration in Okta. Examples may include enabling specific Okta features or SKUs, enabling API access to your SCIM server, or adding a particular version of an integration in Okta.
When using SAML as the SSO mode with provisioning, you need to enable a specific account plan on the application side for silent activation.
In this section of your guide, you want to outline what features your application supports. For example:
- IdP-initiated SSO
- SP-initiated SSO
- SLO (Single Log Out)
- Force Authentication
- Create Users
- Update User Attributes
- Deactivate Users
- Import Users
- Import Groups
- Sync Password
- Profile Sourcing (formerly called Profile Mastering)
Also include any restrictions. For example:
Okta can't update user attributes for Admin users. This is an API limitation.
Note: You can briefly describe what each feature does. See the guides from the earlier SCIM section for examples.
This section constitutes the majority of your guide and explains all the configuration steps needed to get your customers set up with your integration. Detail all settings and include any screenshots that can assist the user.
Also include any best practices for your procedure, such as guidance on setting mappings for attributes, especially required attributes that don't have a default mapping. For example:
Note: The External ID is a required attribute, but it doesn't have a default mapping. This is because some customers prefer to set it to
EmployeeNumber, and others like to set it to
emailAddress. Assign the mapping to the correct value for your organization.
You need to only include this section if there are known issues that apply to the entire configuration. In general, you should include best practices with the step-by-step procedure instructions.
You may also want to include information on how to contact your organization if the customer has any support queries.
To start your integration submission, open the OIN Manager (opens new window) and click Start Submission Form.
Sign in using your development org credentials and 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.
If you need to update an integration, see Update your published integration.
In the General Settings page, you need to fill in the basic information about your integration:
Does your app exist 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 are 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.
App category: Specify one or more categories that Okta uses to categorize your integration in the OIN catalog. Click Add Another to choose up to three categories.
App description: Give a general description of your application and what the Okta integration does. For examples, see the overview section for any of the integrations listed on the OIN (opens new window).
App icon: Upload a PNG, JPG, or GIF file of a logo to accompany your integration in the catalog. The logo file must be smaller than 1 MB in size. For best results, use a PNG image with a transparent background, a landscape orientation, and use a minimum resolution of 420 x 120 pixels to prevent upscaling.
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 drop-down menu to specify if you are adding an email, a URL, or a phone number and 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 should be an email distribution list for Okta to use when contacting your company about your integration. It can be a phone number, but ideally when there is an issue with your integration, Okta wants to reach as many people as possible without creating any bottlenecks. Make sure that the contact provided here isn't a generic contact such as
email@example.com a 1-800 number. The escalation contact should be a contact list that Okta can reach out to in an emergency. This contact information isn't shared with customers.
The Okta OIN team requires a dedicated account on your application to run their tests. This account needs to be kept active beyond the submission period in case Okta needs to update or troubleshoot a submission.
Test account URL: This is a static URL for Okta to sign in to your application. The account credentials that you provide below must work for this URL.
Test account username or email: The account name for Okta to use to sign in to your application. Our preferred account name is
Test account password: Password for the 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.
Your application needs to support at least one protocol for interacting with Okta: SAML or OIDC for authentication, or SCIM for provisioning.
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.
For each protocol, click the appropriate tab name and change the protocol support drop-down box from Off to On.
For each protocol, enter the Okta instance URL for your integration in the first field.
To get your Okta instance URL in your development org:
- In the Okta Admin Console, go to Applications > Applications to see all the integrations in your org.
- Click the name of the app integration that you are going to submit.
- On the settings page, confirm that the settings match what you want as the global defaults for all customers.
- 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.
- Back in the OIN Manager, paste that URL into your submission.
Each of the supported protocols has different configuration settings for the remainder of the submission.
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.
The submission review process begins after 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, along with a date by which you should complete the initial review.
The OIN Manager always shows the current status of your integration.
- 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 submission review is complete, the Okta OIN team moves it to Step 2 for QA testing.
- Pending review by Okta: The Okta OIN team is now conducting internal QA tests and notifies you by email when the QA review is complete. If the QA test is successful, your submission is published automatically 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 is conducting 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 published automatically in the OIN.
- Congratulations, your integration is published in the OIN!
The following flowchart outlines the entire process:
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.
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 firstname.lastname@example.org.
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 email@example.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 are deploying a replacement solution.