Instructions for

On this page

Submit an SSO integration with the OIN Wizard

Use this guide to learn how to submit a Single Sign-On (SSO) integration to the Okta Integration Network (OIN) team using the OIN Wizard. This guide also shows you how to create an SSO integration instance for testing in your org.


Learning outcomes

  • Learn how to submit an SSO integration using the OIN Wizard.
  • Learn how to create an integration instance for testing from the OIN Wizard.
  • Understand the basic test cases required for your SSO features.

What you need


Overview

Okta provides you with a seamless experience to integrate and submit your app for publication in the Okta Integration Network (OIN) (opens new window). When you obtain an Okta Developer Edition org (opens new window), you can use it as a sandbox to integrate your app with Okta and explore more Okta features. When you decide to publish your integration to the OIN, you can use the same Developer Edition org to submit your integration using the OIN Wizard.

The OIN Wizard is a full-service tool in the Okta Admin Console for you to:

  • Provide all your integration submission details.
  • Generate an app instance in your org for testing.
  • Submit your integration directly to the OIN team when you're satisfied with your test results.
  • Monitor the status of your submissions through the Your OIN Integrations dashboard.

The OIN team verifies your submitted integration before they publish it in the OIN catalog (opens new window).

Note: Only cloud-based SaaS apps (either traditional web applications with a back-end or a modern browser-based SPA) are published 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)

    Notes:

    • 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.
    • The OIN Wizard places certain limits on SAML integration submissions. See OIN limitations.

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

Start a submission

Review the OIN submission requirements before you start your submission. There are artifacts and technical details that you need to provide during the submission process.

Notes:

  • To access the Your OIN Integrations dashboard and the OIN Wizard, you must have either the Super Administrator or the Application Administrator role (opens new window).
  • As a best practice, create two or three extra admin users in your Okta org to manage the integration. This ensures that your team can access the integration for updates in the future. See Add users manually (opens new window) and ensure that the Super Administrator or the Application Administrator role is assigned.

Start your integration submission for OIN publication:

  1. Sign in to your Developer Edition org as a user with administrative privileges.
  2. Go to Applications > Your OIN Integrations in the Admin Console.
  3. Click Build new OIN integration. The OIN Wizard appears.
  4. From the Select your protocol section, select
    .

    Note: If you want to change the protocol instructions on this page, select the protocol you want from the Instructions for dropdown list on the right.

  5. Click Configure your integration.

Note: Currently, you can only configure one protocol per OIN integration submission.

Configure your integration

Continue with the OIN Wizard and configure your integration:

OIN catalog properties

  1. In the OIN catalog properties section, specify the following OIN catalog information:

    Property
    Description
    Display name * Provide a name for your integration. This is the main title used for your integration in the OIN.
    The maximum field length is 64 characters.
    Description * Give a general description of your application and the benefits of this integration to your customers. See App description guidelines.
    Logo * 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.

    * Required properties

Integration variables

Configure integration variables if your URLs are dynamic for each tenant. The variables are for your customer admins to add their specific tenant values during installation.


  1. In the Integration variables section, specify the name and label for each variable:

    Property
    Description
    Label * A descriptive name for the dynamic variable that admins see when they install your app integration
    Name * Specify the variable name. This variable name is used to construct the dynamic URL. It's hidden from admins and is only passed to your external application.
    String is the only variable type supported.
    The maximum field length is 1024 characters.

    * This section is optional, but if you specify a variable, both Label and Name properties are required.

  2. Click + Add another to add another variable. You can add up to three variables.

  3. If you need to delete a variable, click the trash can; delete icon icon next to it.

properties

Continue with the OIN Wizard and configure your protocol settings:

  1. In the

    properties section, specify the following protocol properties:

  2. Click Get started with testing to save your edits and move to the testing section, where you need to enter your integration test details.

Enter test information

From the OIN Wizard Test your integration experience page, specify information required for testing your integration. An OIN analyst uses this information to verify your integration after submission.

Test information

A dedicated test admin account in your app is required for Okta integration testing. This test account needs to be active beyond the submission period in case Okta needs to update or troubleshoot your app integration. Ensure that the test admin account has:

  • Privileges to configure SSO in your test app
  • Privileges to administer test users in your test app

See Test account guidelines.

Note: This admin account is in your app and not an account in Okta.

  1. In the Testing information section, specify the following test account details:

    Property
    Description
    Test account URL * A static URL to sign in to your app. An OIN analyst goes to this URL and uses the account credentials you provide in the subsequent fields to sign in to your app.
    Username * The username for your test admin account. The OIN analyst signs in with this username to execute test cases. The preferred account username is isvtest@okta.com.
    Password * The password for your test admin account
    Support contact * Provide an email for Okta to contact your company about your integration. This email isn't exposed in the OIN catalogs or to your customers. Okta uses this email to contact your company for issues during the QA testing phase or for ongoing maintenance of your integration in the OIN. See Escalation support contact in the customer support-contact guidelines.
    Testing instructions Include any other information that you think the OIN analyst needs to know about your integration (such as the test admin account or the testing configuration). You can also provide instructions on how to add test user accounts.

    * Required properties

tests

Continue with the OIN Wizard and specify your supported SSO flows:

  1. In the

    tests section, specify the following sign-in flow details:

  2. Click Test your integration to save your test information and begin the testing phase.

Test your integration

You need to test your integration to verify that the integration performs as you expect before you submit it. Test all the SSO functions that your integration supports:

The Test your integration experience page of the OIN Wizard helps you prepare and test your integration within the same org. You can generate an integration instance from the information you provide in the wizard. The generated instance allows you to test your customer admin experience and your end-user sign-in experience.

The test cases presented in this section are the minimum tests that you need to execute to ensure that your sign-in flow works as expected. Ideally, you want to execute several variations of these test cases with negative and edge cases in mind.

How to prepare your integration instance for testing

To prepare your app integration instance for testing, you need to execute the following:

  1. As the customer admin persona, generate the integration instance.
  2. As the customer admin persona, assign test users to the integration instance.

Generate the instance for testing

This flow tests the customer admin experience. The test steps start from the OIN Wizard to generate the instance. Then the steps shift to add an existing app integration (opens new window) page, where you assume the customer admin persona. When your integration is published in the OIN catalog, the customer admin uses the Admin Console Browse App Catalog > add an existing app integration (opens new window) page to add your integration to their org. So the following steps (after step 1) are exactly what your customer admins experience.

Test case preconditions:

To generate an integration instance:

  1. In the Test your integration experience section of the OIN Wizard, click Generate Instance. The app General settings tab appears.

Assign test users to your integration instance

As a customer admin persona, assign users to your app integration instance to test your SSO flow. Create your test users in Okta before you assign them to your integration. See Add users manually (opens new window) and Assign app integrations (opens new window) topics in the Okta product documentation.

Test case preconditions:

To assign test users to your integration:

  1. Continue as the customer admin persona from the OIN Wizard > Generate instance pages. Alternatively, if you aren't in the OIN Wizard, go to Applications > Applications > your app integration instance in the Admin Console.
  2. From your app integration instance page, click the Assignments tab.
  3. Click Assign and then select either Assign to People or Assign to Groups.
  4. Enter the appropriate people or groups that you want to have SSO into your application, and then click Assign for each.
  5. Verify the user-specific attributes for any people that you add, and then select Save and Go Back.
  6. Click Done.
  7. If you want to go back to the OIN Wizard, click Begin testing (upper-right corner). The Test your integration experience page appears. Testing guidance is provided on this page, and you can submit your integration after you've successfully completed testing.

How to test an IdP flow

Test the IdP sign-in flow as a customer end-user persona. Use an end user that you assigned to your integration. This sign-in flow initiates from the Okta End-User Dashboard.

Sign in with the IdP flow

Test case preconditions:

To test the SSO IdP flow:

  1. Open a new incognito window in your browser.
  2. Go to your Developer Edition Okta org. For example: https://dev-12345678.okta.com
  3. Sign in to the Okta End-User Dashboard as an end user that was assigned the integration.

    Note: If you sign in as a non-admin user to your Okta org from a browser, the End-User Dashboard appears.

  4. Confirm that your app tile appears on the Okta End-User Dashboard.
  5. Click your app tile and confirm that you can sign in.
  6. Sign out of your app.
  7. Verify that you're able to sign out and are redirected to the sign-in page.

How to test an SP flow

To test the SP flow (the app-initiated flow), you need to execute the test cases as a customer end-user persona. Use one of the test end users you previously assigned to your integration.

There are two options to sign in with the SP-initiated flow:

  1. Direct URL: Sign in with a direct URL for the SP flow
  2. Sign-in page: Sign in with the sign-in page for the SP flow

Sign in with a direct URL for the SP flow

Test case preconditions:

To test the SP-initiated flow with a direct URL:

  1. Open a new incognito window in your browser.
  2. Go to the app sign-in page directly from the browser URL address field (for example: https://berryfarm.example.org/strawberry/signin). The browser redirects you to Okta for authentication.
  3. Sign in with Okta credentials for the test end user.
  4. Confirm that you are signed in to the app.

    Note: If you have multiple apps in the OIN catalog, verify that you've signed in to the correct app.

  5. Sign out of your app.
  6. Verify that you're able to sign out and are redirected to the sign-in page.

Sign in with a sign-in page for the SP flow

Test case preconditions:

To test the SP-initiated flow with a sign-in page:

  1. Open a new incognito window in your browser.
  2. Go to the app sign-in page.
  3. Initiate the sign-in action from the sign-in page (such as clicking Sign in with Okta).
  4. Sign in with Okta credentials for the test end user.
  5. Confirm that you're signed in to the app.

    Note: If you have multiple apps in the OIN catalog, verify that you've signed in to the correct app.

  6. Sign out of your app.
  7. Verify that you're able to sign out and are redirected to the sign-in page.

How to test JIT provisioning

To test Just-In-Time (JIT) provisioning, you need to execute the test cases with two personas: as a customer admin user and as an end user. The customer admin user sets up the new end user in Okta. And the new end user signs in to the app. The new user profile is provisioned in the app without extra admin intervention.

Test JIT provisioning with either SSO flow:

Test JIT provisioning with the IdP flow

Test case preconditions:

To test JIT provisioning with the IdP flow:

  1. As an Okta admin user, verify that the test user doesn't exist in your Okta org.
  2. As an app admin user, verify that the test user doesn't exist in the app. Sign in to your app and verify that there's no user with the same unique attributes as your new test user.
  3. As an Okta admin user, sign in to your Okta org.
  4. Go to Directory > People and add the new test user in Okta. See Add users manually (opens new window) for complete instructions.
  5. Go to Applications > Applications > your app integration instance in the Admin Console.
  6. From your app integration instance page, click the Assignments tab.
  7. Click Assign > Assign to People.
  8. Find the name of the new test user and click Assign next to their name. A dialog box appears with the title Assign {app-name} to People.
  9. Click Save and Go Back.
  10. On the People page, click Done.
  11. Open a new incognito window in your browser.
  12. Go to your Okta org URL.
  13. Sign in to the Okta org as the new user that was assigned to the app integration. The End-User Dashboard appears.
  14. Confirm that your app tile appears on the Okta End-User Dashboard.
  15. Click your app tile and confirm that you can sign in.
  16. Sign out of your app.
  17. Verify that you're able to sign out and are redirected to the sign-in page.
  18. Verify that the new user was created in your app with supported attributes passed from the Okta profile, such as the user's name and email.

Test JIT provisioning with the SP flow

Test case preconditions:

To test JIT provisioning with the SP flow:

  1. As an admin user, verify that the test user doesn't exist in your Okta org.
  2. As an admin user, verify that the test user doesn't exist in the app. Sign in to your app and verify that there's no user with the same unique attributes as your new test user.
  3. As an admin user, sign in to your Okta org.
  4. Go to Directory > People and add the new test user in Okta. See Add users manually (opens new window) for complete instructions.
  5. Go to Applications > Applications > your app integration instance in the Admin Console.
  6. From your app integration instance, click the Assignments tab.
  7. Click Assign > Assign to People.
  8. Find the name of the new test user and click Assign next to their name. A dialog box appears with the title Assign {app-name} to People.
  9. Click Save and Go Back.
  10. On the People page, click Done.
  11. Open a new incognito window in your browser.
  12. Go to the app sign-in page directly from the browser URL address field (for example: https://berryfarm.example.org/strawberry/signin). The browser redirects you to Okta for authentication.
  13. Sign in with Okta credentials for the new test user that was assigned to the app integration.
  14. Confirm that you can sign in to the app.
  15. Sign out of your app.
  16. Verify that you're able to sign out and are redirected to the sign-in page.
  17. Verify that the new user was created in your app with supported attributes passed from the Okta profile.

Failed SSO tests

If any of your SSO test cases failed, you need to investigate and resolve the failure before submitting the integration. You can only submit integrations that have successfully passed all basic supported SSO tests.

If you have to update SSO flow properties in your submission to resolve your failed test cases, then you need to generate a new app integration instance for testing. Assign test users to your new integration instance before executing all your SSO test cases again.

Note: You don't have to generate a new app integration for every failed test scenario. If you have an environment issue or if you forgot to assign a user, you can fix your configuration and run the tests again. Generate a new instance only if you need to modify an SSO property, such as an integration variable, a redirect URI, or an ACS URL.

It's good practice to deactivate your app integration instance (from the failed test cases) from the Applications > Applications page of the Admin Console. You can later delete the test app integration instance if you want to clean your app integration list.

To receive help with failed test cases or server error messages, post your questions on the Okta Developer Forum (opens new window) or submit your questions to developers@okta.com.

If you have questions or need more support with the OIN submission process, contact the Okta OIN team at oin@okta.com.

Submit your integration

After you successfully test your integration, you're ready to submit.

  1. Close the incognito browser window and return to the Test your integration experience page in the OIN Wizard.
  2. Select I certify that I have successfully completed the required tests.
  3. Click Submit integration.
  4. Click Close wizard from the Thank you for your submission confirmation page. This takes you back to the Your OIN Integrations dashboard.

After you submit your integration, an OIN analyst performs an initial review of your submission details. They send an email to you with any submission issues to correct.

After the initial review is complete and all the issues are correct, the submission moves to the QA testing phase. An OIN analyst uses the test information that you provide in the OIN Wizard to test your integration. They send you an email with any test failures or issues to correct. See Understand the submission review process.

Update your integration

You can modify a submitted or published integration in the Your OIN Integrations dashboard. These integrations are initially in read-only mode. If you decide to edit an integration and update any property from the previous submission, your integration reverts to Draft status. You have to retest and resubmit your draft integration.

Notes:

  • If you edit your submitted or published integration in the Your OIN Integrations dashboard, your previous status and date are overwritten with the Draft status and date.
  • If you previously submitted your SSO integration using the OIN Manager, you can edit your published integration only with the OIN Manager.

To update a submitted integration:

  1. Sign in to your Okta Developer Edition org as a user with admin privileges.
  2. Go to Applications > Your OIN Integrations in the Admin Console.
  3. Click your integration to update from the dashboard. The OIN Wizard appears.
  4. Go to the OIN Wizard page that you want to update.
  5. From the This integration is read-only information box, select Edit integration.
  6. Update the desired properties in the OIN Wizard.
  7. Click View testing information or Close wizard to save the modified integration. When you save the updated properties, the integration submission status is set to Draft.
  8. Go to Applications > Your OIN Integrations in the Admin Console and confirm that your integration submission is in Draft status.
  9. Retest your integration before you submit it again.

Update integration considerations

  • If you have an existing SAML SSO integration and you want to update advanced properties that aren't available in the OIN Wizard, contact oin@okta.com.

  • When you update an integration that is already published, be mindful to preserve backwards compatibility for your integration. Older instances of your integration could be in use by Okta customers.

    If your update introduces new variables and you're using dynamic URLs, ensure that your test cases cover a variety of scenarios with different possible values for those variables. The newly introduced variables aren't populated for older instances of your integration. For example:

Submission support

If you need help during your submission, Okta provides the following support stream for the various phases of your OIN submission:

  1. Building an integration phase

  2. Using the OIN Wizard to submit an integration phase

  3. Testing an integration phase

See also