Submit an integration with the OIN Wizard

Learn how to submit an integration with SSO, Universal Logout, provisioning, Entitlement Management, API service, or Identity Verification (IDV) capabilities to the Okta Integration Network (OIN) using the OIN Wizard.

---

What you need

• An Okta Integrator Free Plan org (opens new window). The OIN Wizard is only available in Integrator Free Plan orgs.

• An admin user in the Integrator Free Plan org with either the super admin or the app and org admin roles

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

• Google Chrome browser with the Okta Browser Plugin installed (see OIN Wizard requirements)

• A functional integration that's based on the Build a SCIM provisioning integration and the Sign users in overview guides.

---

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 Integrator Free Plan 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 Integrator Free Plan org to submit your integration using the OIN Wizard.

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

• Provide all your integration submission details.
• Generate an app instance in your org for testing:
  • Test your SSO integration with the OIN Submission Tester.
  • Test your SCIM integration with manual test cases and Runscope test suites.
  • Test your SCIM-based Entitlement Management manually.
  • Test your Universal Logout integration manually.
• 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.
• Edit published integrations and resubmit them to the OIN.

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

Note: Traditional SPA and mobile apps integrate with Okta using an OIDC flow that authenticates by exchanging and storing tokens on the client. They rely on client-side authentication and can't be added to the OIN Wizard directly. However, SaaS app stacks with SPA or mobile components can be included in the OIN Wizard if a backend server handles the authentication. See the Enterprise-Ready workshop (opens new window) for more information on authenticating SaaS apps with OIDC.

Protocols supported

This guide covers submissions that use the following protocols and integrations:

• OpenID Connect (OIDC) (opens new window)

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

• System for Cross-domain Identity Management (SCIM) 2.0 Provisioning (opens new window)

• SCIM 2.0 Entitlement Management (opens new window)

• Universal Logout

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.
• SWA app integrations are no longer accepted for publication in the OIN catalog. However, the OIN team still maintains existing SWA apps.
• There are protocol-specific limitations on integrations in the OIN. See OIN limitations.

Start a submission

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

Note: As a best practice, add two or three extra admin users in your Okta org to manage the integration. This ensures that your team can access the integration for future updates. See Add users manually (opens new window) and ensure that the app and org admin roles are assigned to your admin users. The super admin role also provides the same access, but Okta recommends limiting assignments to this role.

Start your integration submission for OIN publication:

1. Sign in to your Integrator Free Plan org as a user with either the super admin (SUPER_ADMIN) role, or the app (APP_ADMIN) and org (ORG_ADMIN) admin roles (opens new window).

   Note: Submit your integration from an Okta account that has your company domain in the email address. You can't use an account with a personal email address. The OIN team doesn't review submissions from personal email accounts.

2. On the Home page, do one of the following:

   • Click Create app to create an app that you want to list in the Okta Integration Network.
     
     OR
     
   • If there's an existing integration for an app, click Add more integrations to add more integrations for your app. The Manage your app page appears.

3. Select your integration capabilities, and then enter a display name and description.

4. Click Add Integration Details. The Integration details page appears.

   Note: Alternatively, you can go to Applications > Your OIN Integrations to build your integration and select your capabilities.

   If you only want to test an existing submission, see Navigate directly to test your integration.

   Note: The instructions on this page are for the SCIM 2.0 protocol.
   If you want to change the instructions that you see on this page, select a different option from the Instructions for dropdown list on the right.

Integration details

Configure your OIN catalog properties:

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 app 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.
   Use Cases	Add optional use case categories that apply to your integration: Automation Centralized Logging Directory and HR Sync Identity Governance and Administration (IGA) Identity Verification Multifactor Authentication (MFA) Zero Trust You can select up to three optional use cases. Default use cases are assigned to your integration based on supported features. See Use case guidelines.

   * Required properties

Tenant settings

Configure integration variables if your URLs are dynamic for each tenant. The variables are for your customer admins to add their specific tenant setting values during installation. See Dynamic properties with Okta Expression Language.

2. In the Tenant settings section, specify the name and label for each tenant setting variable:

   Property	Description
   Label *	The tenant setting label that's displayed when admins install your app integration. For example: Subdomain or Tenant name
   Name *	The tenant setting variable name. This is used to construct dynamic URLs or other app properties that are dependent on the tenant. It's hidden from admins and is only used to pass tenant details to your external app. String is the only variable type supported. Note: Use alphanumeric lowercase and underscore characters for the variable name field. The first character must be a letter and the maximum field length is 1024 characters. For example: subdomain_div1

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

3. Click + Add another to add another variable. You can add up to eight variables.

   Note: Apps that are migrated from the OIN Manager and that have more than eight variables can retain those variables, but you can't add new ones. However, you can update or delete the existing variables.

4. If you need to delete a variable, click the delete icon () next to it.

Authentiation settings

5. Specify authentication settings to your app resources.

Property	Description
Authentication mode *	Select the authentication mode to make outbound calls to your SCIM server. Header: Uses authorization header with a customer-provided token in the following format: Authorization: {API token} Bearer: Uses authorization header with a customer-provided bearer token in the following format: Authorization: Bearer {API token} OAuth 2: Uses OAuth 2.0 authorization code grant flow Note: Basic authentication isn't supported for SCIM. See SCIM integration limitations.
	OAuth 2.0 settings
Authorize endpoint	Specify the HTTPS authorize endpoint. For example: https://myexample.com/oauth2/auth You can specify a dynamic endpoint URL. See Dynamic properties with Okta Expression Language.
Token endpoint	Specify the HTTPS token endpoint. For example: https://myexample.com/oauth2/token You can specify a dynamic endpoint URL. See Dynamic properties with Okta Expression Language.
Client ID	Specify the client ID.
Client secret	Specify the client secret.
Scopes	Optional: Specify scopes.

6. Click Configure your integration.

Configure your integration

Configure your integration settings. Settings appear based on your capability selection.

Support contact

1. Specify a support contact from your organization:

   Property	Description
   Support email *	Specify an email that the Okta team can use to contact your organization for emergencies and escalations. This field is private and not visible to customers. See Customer support contact guidelines.

SCIM properties

Notes:

• This section appears if you select provisioning with SCIM 2.0.
• The instructions on this page are for the SCIM 2.0 protocol.
  If you want to change the instructions that you see on this page, select a different option from the Instructions for dropdown list.

1. Specify the following protocol properties in the SCIM properties section:

   Property	Description
   Base URL *	Specify the base URL for your SCIM server. The base URL must support the HTTPS protocol. If you're using a per tenant design, include the variable names that you created in your URL. For example:'https://' + app.subdomain + '.example.com/scim2/'. See Dynamic properties with Okta Expression Language. The maximum field length is 1024 characters.
   What objects do you want Okta to manage in your integration? *	Select the objects that you want Okta to manage with your SCIM integration. Users: Okta manages users in your app by default. Groups: Select this option if you also want Okta to manage groups in your app.
   User operations *	Select user operations for your SCIM integration. Create: Okta can create users in your app. Read *: Okta can read users from your app. Update: Okta can update users in your app. Change password: Okta can update user passwords in your app. Deactivate: Okta can deactivate users in your app. Support PATCH for User: Okta can update users with the PATCH method in your app. Import User Schema: Okta can automatically retrieve supported attributes from your SCIM server. Note: Import users capability is enabled by default. Profile sourcing isn't supported, contact the OIN team if your integration must support this capability.
   Group operations	Group operations for your SCIM integration. These are all selected by default if your integration manages the Groups object. Create: Okta can create groups in your app. Read *: Okta can read groups from your app. Update (Uses PATCH): Okta can update groups in your app with the PATCH method. Delete: Okta can delete groups in your app. Note: Import groups capability is enabled by default.
   Link to configuration guide *	Specify the URL link to your customer-facing instructions on how to configure SCIM provisioning between Okta and your app. See Customer configuration document guidelines.

   * Required properties

SCIM 2.0 entitlement management properties

1. Specify the following properties if you want to integrate Entitlement Management:

   Notes:

   • Entitlement Management is supported for integrations that manage entitlements through a SCIM server.
   • The SCIM Entitlement Management properties section only appears when you select Entitlement Management from the Identity Lifecycle Management section. This selection must be made along with the protocols that your integration supports.

   Property	Description
   Resource type mapping
   Resource type *	The name of the resource type. For example, Role or License.
   Endpoint *	Endpoint of the entitlement server. For example, /Roles.
   Properties	Required: This option makes an entitlement mandatory for user assignment. If an entitlement property is required, you can’t assign a user to the app without granting at least one entitlement from a category. Multi-valued: This option determines if a user can be assigned multiple entitlements from the same category.
   Description	Description of the entitlement resource type.
   Schema mapping	Allows mapping the custom SCIM properties to the Okta SCIM URN.
   ID *	The attribute or column name for the ID of the entitlement. This appears as the Value Name field on the Governance tab. For example, roleId.
   Display Name *	The attribute or column name for the display name of the entitlement. This appears as the Display Name field on the Governance tab. For example, roleName.
   Description	The attribute or column name for the description of the entitlement. For example, roleDesc. This appears as the Description field on the Governance tab.

   * Required properties

2. Click + Add another to add another resource type.

3. To delete a resource type, click the delete icon .

Universal Logout properties

Notes:

• This section appears if you select Universal Logout with GTR.
• Universal Logout integrations are only supported with SSO. 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. For more information on Universal Logout with GTR, see Universal Logout (opens new window).

1. Specify the following properties if you want to integrate for Universal Logout:

   Property		Description
   Global token revocation endpoint *		Specify your Global Token Revocation (GTR) (opens new window) endpoint. If your endpoint URL is dynamic, use the variables that are specified in the Integration variables section. For example: https://' + app.subdomain + '.example.org/strawberry/login. See Dynamic properties with Okta Expression Language (opens new window). The maximum field length is 1024 characters.
   Authentication method		Specifies the authentication method that's used for Universal Logout. Currently, Okta only supports SIGNED_JWT.
   Subject format		Specify how the user is identified in the logout request for your app. The default value is Email.
   	Email	Your integration uses the email address of the user.
   	Issuer and Subject identifier	Your integration uses the user identifier.
   Partial support		Select if you only require partial Universal Logout support for your app. Note: If you select this option, while clearing the user's session from Okta, the app only revokes the user's refresh tokens, which prevents the user from getting new access in the future. However, the existing user sessions aren't terminated until the user's existing access tokens expire or the user signs out of an app.

   * Required properties

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

Dynamic properties with Okta Expression Language

The OIN Wizard supports Okta Expression Language to generate dynamic properties, such as URLs or URIs, based on your customer tenant. You can specify dynamic strings for your

SCIM

properties in the OIN Wizard:

1. Add your tenant settings in the OIN Wizard. These settings become fields for customer admins to enter during your OIN integration installation to identify their tenant.

2. Language format in your integration properties for dynamic values based on customer information.

For example, if you have a SCIM configuration variable called subdomain, then you can set your Base URL string to 'https://' + app.subdomain + '.example.org/strawberry/scim2/'. When your customer sets their subdomain variable value to berryfarm, then https://berryfarm.example.org/strawberry/scim2/ is their base URL.

Note: A variable can include a complete URL (for example, https://example.com/scim2/). This enables you to use global variables, such as app.baseURL.

The following are Expression Language specifics for SCIM properties:

• Any SCIM tenant settings that you define in the OIN Wizard are considered application properties. They have an app. prefix when you reference them in Expression Language. For example, if your tenant variable name is subdomain, then you can reference that variable using app.subdomain.

• SCIM properties support Expression Language conditional expressions. For example:

  'https://' + app.subdomain + '.example.org/strawberry/scim2/'`
  

  'https://' + (app.region == 'us' ? 'myfruit' : 'myveggie') + '.example.com/strawberry/oauth/token'
  

• SCIM properties support Expression Language String functions (opens new window). For example:

  (String.len(app.baseUrl) == 0 ? 'https://fruit.example.com/scim2/' : app.baseUrl) + 'v1/oauth_token'
  

  (String.stringContains(app.environment,"PROD") ? 'https://fruit.example.com' : 'https://fruit-sandbox.example.com') + '/v1/oauth2/token'
  

Enter test information

From the OIN Wizard Test your integration page, specify the information that's required for testing your integration. The OIN team uses this information to verify your integration after submission.

Test information for Okta review

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

• Privileges to configure admin settings in your test app
• Privileges to administer test users in your test app

• Credentials to access the SCIM server for SCIM integrations
  
  

After your integration is verified, Okta automatically deletes test account credentials 30 days after your app is published in the OIN Wizard. To resubmit your app after this period, create a test account and provide the required information.

See Test account guidelines.

In the Testing information for Okta review section, specify the following Test account details:

Property	Description
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
Testing instructions	Include information that the OIN team needs to know about your integration for testing (such as the admin account or the testing configuration). You can also provide instructions on how to add test user accounts.

* Required properties

For a SCIM integration, specify how to access the SCIM server for testing. Provide the SCIM server base URL and credentials for the OIN team to conduct QA testing. You can include instructions on obtaining SCIM credentials (API token or OAuth 2.0 properties) from your app.

SCIM

Tests

Before you test your Okta SCIM integration, confirm that your SCIM API service is operational. Okta provides a SCIM API specification test suite in Runscope. See Test your SCIM API.

After you've successfully run the Okta SCIM API specification test suite in Runscope, save the URL of the test results. This Runscope test results URL is one of the requirements to submit your integration.

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

Test your integration

The OIN Wizard journey includes the Test integration experience page to help you configure and test your integration within the same org before submission. These are the tasks that you need to complete:

1. Generate instances for testing. You need to create an app integration instance to test each protocol that your integration supports.

   • For an SSO integration, configure SSO and assign test users in the test instance.

   • For a SCIM integration, configure provisioning and map user profile attributes in the test instance.

   • For SCIM Entitlement Management integration, manually test this functionality as follows:

     1. Verify that the Entitlement Management feature is enabled. To enable it, see Entitlement Management (opens new window).

     2. Configure provisioning and update the operations that are supported by your SCIM server.

     3. Verify that the resource types or entitlements that are supported by your SCIM server are listed on the Governance tab.

        Note: After provisioning is complete, it might take some time for the entitlements to load.

     4. Map user profile attributes on the test instance.

     5. Assign the entitlements to the users manually for testing or automatically through a policy. See Assign entitlements to users (opens new window).

   • For the Universal Logout integration, assign the test user and enable the Logout option on the instance. You can use the same instance that you created for SSO integration testing.

2. Test your integration.

   • For an SSO integration, test the required flows in the OIN Submission Tester with your generated test instance. Fix any test failures from the OIN Submission Tester, then regenerate the test instance (if necessary) and retest.
   • For a SCIM integration, execute the Runscope CRUD tests and the Okta manual integration tests with your generated test instance.
   • For a SCIM Entitlement Management integration, execute the Entitlement Management Runscope tests and the Okta manual integration tests with your generated test instance.
   • For a Universal Logout integration, test the logout flow manually. See Test your Universal Logout integration.

3. Submit your integration after all required tests are successful.

Note: You must have the Okta Browser Plugin installed with Allow in Incognito enabled before you use the OIN Submission Tester. See OIN Wizard requirements.

Navigate directly to test your integration

You can navigate directly to the OIN Wizard Test integration page if you have an existing submission in the Your OIN Integrations dashboard. You can bypass the Select protocol, Configure your integration, and Test your integration pages in the OIN Wizard, and start generating instances for testing. This saves you time and avoids unnecessary updates to an existing integration submission.

Follow these steps to bypass the configuration pages in the OIN Wizard:

1. Select Applications > Your OIN Integrations. Then select the more icon () next to the integration submission that you want to test.

2. Select Test your integration.

   • The OIN Wizard Test integration page appears for you to generate an instance and test your integration.

   • If you haven't specified test information in the Test your integration page, then you're directed to this page to enter testing details. You can go to the Test integration page only if the protocols, configuration, and test details are provided in your submission.

   • If your integration is in read-only mode, click Edit integration to enter test details before testing.

Generate instances for testing

Generate instances for testing in your Integrator Free Plan org directly from the OIN Wizard. The OIN Wizard takes the configuration and test information from your OIN submission and allows you to configure a specific integration instance to your test app. You can test the admin and end user sign-in experiences with the generated instance flow.

Note: Okta recommends that you:

• Separate environments for development, testing, and production.
• Use the Integrator Free Plan org as part of your development and testing environment.
• Don't connect the generated app instance from the Integrator Free Plan org to your production environment. Connecting your development and testing environment with your production environment creates several potential risks, including unintentionally modifying data and misconfiguring your service. This could result in providing inadequate security or disrupting your service.

Okta recommends that you generate an instance for testing each protocol supported by your integration:

• You must generate separate instances for testing if you support two SSO protocols (one for OIDC and one for SAML). The OIN Submission Tester can only test one protocol at a time.
• If your SSO integration supports both SCIM and SCIM Entitlement Management, create one instance specifically for SCIM protocol and SCIM entitlement management testing. You also need to create a separate instance for each supported SSO protocol testing.
• For a Universal Logout integration, you can use the same instance that you created for SSO protocol testing.

There are certain conditions where you can test two protocols on one instance. You can create one instance for SSO and SCIM testing if your integration meets all of these conditions:

• It supports SCIM and one SSO protocol
• It doesn't support JIT provisioning
• The Create User SCIM operation is enabled

The Integrator Free Plan org has no limit on active instances. You can create as many test instances as needed for your integration. To deactivate any instances you no longer need, see Deactivate an app instance in your org.

Generate an instance for

SCIM

Note: The steps in this section are for generating one instance to test the

SCIM

.
If you want to change the instructions that you see on this page, select a different option from the Instructions for dropdown list.

1. From the Test integration page, click Generate instance.

   A page appears to add your instance details. See Add existing app integrations (opens new window).

   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 Okta org. The next few steps are exactly what your customer admins experience when they instantiate your integration with Okta. This enables you to assume the customer admin persona to verify that app labels and properties are appropriate for your integration.

   If you need to change any labels or properties, go back to edit your submission.

   Note: The Integrator Free Plan has no limit on active app instances. You can create as many test instances as needed for your integration. To deactivate any instances that you no longer need, see Deactivate an app instance in your org.

2. In the General settings tab, enter an Application label and any other required integration properties.

3. Click Done. Your generated test instance appears with more tabs for configuration.

4. Click Provisioning > Configure API Integration.

5. Select Enable API integration.

   • For custom or bearer authentication, specify the API token for your instance.
   • For OAuth 2.0 authentication, click Authenticate with {yourApp} and provide credentials for your test instance.

6. Click Test API Credentials to test authentication to your SCIM service. If there's an error, verify that the credentials are correct.

7. Click Save.

8. Select Settings > To Okta from the updated Provisioning tab.

9. In the General section, click Edit to schedule imports and configure the username format for imported users.

   You can also define a percentage of acceptable assignments before the import safeguards (opens new window) feature is automatically triggered.

10. Click Save. Next, configure attribute mappings.

Note: Your SCIM app must support redirect URIs that include the app name ({appName}) that's generated after you create your app instance. See SCIM service authentication for a list of redirect URIs required. Your app name appears in the General settings tab or in the Admin Console URL when you're viewing the instance page.

Configure attribute mappings

Note: Configure attribute-mapping instructions are only for SCIM integrations.

SCIM integrations that are submitted through the OIN Wizard have a default set of user attribute mappings. Because your SCIM app may not support all default attributes, you must ensure that your submission reflects only the attributes supported by your app.

There are now two ways to define your user schema in the OIN Wizard:

• Automated (Recommended): If you selected the Import User Schema checkbox in the SCIM provisioning properties section, Okta dynamically pulls the supported attributes directly from your SCIM server (core and extension schemas).

• Manual: If you didn’t enable schema import, you must manually delete unsupported attributes and add new ones through the Profile Editor.

Automated configuration

If the Import User Schema checkbox within the SCIM provisioning properties section is selected, Okta manages your integration’s attributes based on the following logic:

• No manual deletion required: You can skip the deletion process. Only the required attributes defined on your SCIM server are populated.

• Adding attributes: To add an attribute, click Add Attribute in the Profile Editor and choose from a picklist of discovered fields. Consider the following details when managing your attributes:

  • Schema discovery details: Okta identifies these fields by retrieving core user attributes from the schema with the URN urn:ietf:params:scim:schemas:core:2.0:User in /Schemas endpoint within the SCIM server. Extension attributes are pulled from schemas matching the URNs specified under the User Resource Type of the /ResourceTypes endpoint within the SCIM server.

  • ISV requirement: If your schema varies across different customers, only add attributes that are common to all environments to ensure that the integration works for everyone.

• Manual mapping required: Although attributes are imported automatically, you must still define their relationship to Okta fields. Follow the instructions starting from step 3 of Add attributes and mapping in the Manual configuration section.

Manual configuration

SCIM integrations that are submitted through the OIN Wizard have a default set of user attribute mappings. The user schema in your SCIM app might not support all of these attributes. Ensure the integration that you're submitting to Okta reflects the attributes that are supported by your app. The OIN team uses the attribute mappings in your test instance for your integration provisioning settings in the OIN catalog.

After you've enabled the provisioning API connection in your test instance, configure user attribute mappings to and from Okta in the Provisioning tab of your instance.

• To App: User attribute mappings from Okta to your app
• To Okta: User attribute mappings from your app to Okta

Configure the user attribute mappings after deleting the unnecessary mappings and attributes, and then proceed to configure the attributes:

Delete mappings

1. Select To App on the left Settings panel. The Provisioning to App settings appear. The provisioning operations are already set by default from the SCIM properties section when you configured your integration.
2. Scroll to the {yourApp} Attribute Mappings section.
3. Click X next to the attribute that you want to delete, and then click OK to confirm. Repeat this step until you remove all the mappings for the attributes that you want to delete.
4. Select To App on the left Settings panel.
5. Scroll to the Okta Attribute Mappings section.
6. Click X next to the attribute that you want to delete, and then click OK to confirm. Repeat this step until you remove all the mappings for the attributes that you want to delete.

Delete attributes

1. After removing all the mappings for the attributes that you want to delete, click Go to Profile Editor.

2. In the Profile Editor, delete all the corresponding attributes from the mapping by clicking X next to the attribute and then Delete Attribute to confirm.

3. Repeat this step for all the attributes that you want to delete.

Add attributes and mappings

1. In the Profile Editor, click Add Attribute.

2. Enter the information for the new attribute that you’re adding and then click Save.

   Note: The Scope property determines whether the attribute that you're adding can be assigned at a group level or per user. If you want your admins to assign a value for this attribute at a group level, don't select the User personal checkbox.

3. After adding attributes, go back to the {yourApp} Attribute Mappings section and click Edit to map your new attributes. A dialog appears with two dropdown fields.

   

4. Select Map from Okta Profile in the first dropdown list.

5. In the second dropdown list, select the Okta profile attribute that you want to map over to the SCIM attribute.

6. Click Save.

7. Repeat these steps for all SCIM attributes that you want to map (from Okta to your app).

8. After you update the mappings from Okta to your app, click To Okta in the Settings section.

9. Scroll to the {yourApp} Attribute Mappings section. Find the attribute that you want to update and click Edit. A dialog appears with two dropdown fields next to the Attribute value.

10. Select Map from {yourApp} App Profile from the first dropdown list.

11. In the second dropdown list, select the SCIM attribute that you want to map to the Okta attribute.

12. Click Save.

After you complete your attribute mappings, you're ready to test your SCIM integration.

Assign test users to your integration instance

For SSO-only flow tests, create your test users in Okta before you assign them to your app. See Add users manually (opens new window) and Assign app integrations (opens new window).

For SSO flow tests without JIT provisioning, you need to create the same test user in your app. If the app supports JIT provisioning, Okta provisions the test user automatically.

For SCIM provisioning, you can assign an imported user to your app. Alternatively, you can create a user in Okta and push them to the app through SCIM. Then you can assign the user to the app. See About adding provisioned users (opens new window).

Note: You need an Okta admin role that grants permission to create users.

To assign test users to your app:

1. In the OIN Wizard, go to Test integration > Generate instance.

2. Click the Assignments tab.

3. Click Assign, and then select either Assign to People or Assign to Groups.

4. Enter the people or groups that you want to assign to the app, and then click Assign for each.

5. Verify the user-specific attributes for the assigned users, and then select Save and Go Back.

6. Click Done.

7. Click Begin testing in the OIN Wizard. After the Test integration page appears, continue to the Application instances for testing section to include your test instance in the OIN Submission Tester.

   Note: If you're not in the OIN Wizard, go to Your OIN Integration > Select protocol > Configure your integration > Test integration.

Required app instances

The Required app instances field displays the instances detected in your org. Use these instances to test your integration. This field also shows you the test instances required for the OIN Submission Tester based on your selected protocols:

• The CURRENT VERSION status indicates the instances that you need to test your current integration submission.
• The PUBLISHED VERSION status indicates the instances that you need to test backwards compatibility if you edit a previously published integration. See Update a published integration with the OIN Wizard.

Application instances for testing

The Application instances for testing section displays, by default, the instances available in your org that are eligible for submission testing.

Note: The filter () is automatically set to only show eligible instances.

An instance is eligible if it was generated from the latest version of the integration submission in the OIN Wizard. An instance is ineligible if it was generated from a previous version of the integration submission and you later made edits to the submission. This is to ensure that you test your integration based on the latest submission details.

If you modify a published OIN integration, you must generate an instance that's based on the currently published integration for backwards compatibility testing. A backward-compatible instance is eligible if it was generated from the published version of the integration before any edits are made in the current submission. The OIN Wizard detects if you're modifying a published OIN integration and asks you to generate a backward-compatible instance before you make any edits.

Note: The Integrator Free Plan org has no limit on active instances. You can create as many test instances as needed for your integration. To deactivate any instances you no longer need, see Deactivate an app instance in your org.

Add to Tester

Note: The OIN Submission Tester only supports SSO integrations. The Add to Tester option isn't available for SCIM integrations.

• Click Add to Tester next to the app in the Application instances for testing list. This includes it for testing with the OIN Submission Tester. The Add to Tester option only appears for apps that are active and eligible for testing.

  The test cases are populated with the app name and the Run test option is enabled in the OIN Submission Tester.

• Click Remove from Tester to disable the test cases that are associated with the app.

  The app name and test results are removed from the corresponding test cases in the OIN Submission Tester. The Run test option is also disabled.

  Instructions for submitting an API service integration have been removed from the OIN Manager guide. You can no longer submit API service integrations through the OIN Manager. See Submit an integration with the OIN Wizard to submit an API service integration through the OIN Wizard.

Deactivate an app instance in your org

To deactivate an instance from the OIN Wizard:

1. Go to Test integration > Application instances for testing.
2. Click Clear filters to see all instances in your org.
3. Disable the ACTIVE toggle next to the app instance you want to deactivate.

Alternatively, to deactivate an app instance without the OIN Wizard, see Deactivate app integrations (opens new window).

Update an app instance in your org

To edit the app instance from the OIN Wizard, follow these steps:

1. Go to Test integration > Application instances for testing.

2. Click Clear filters to see all instances in your org if you don't see the instance that you want to edit.

3. Select Update instance details from the more icon () next to the app instance you want to update. The instance details page appears.

4. Edit the app instance. You can edit app instance settings or assign users to your app instance (opens new window).

5. Return to the OIN Wizard:

   • Click Begin testing (upper-right corner) for the current submission instance.

     The Test integration page appears.

   • Click Go to integrations (upper-right corner) for the backward-compatible instance.

     The Your OIN Integrations dashboard appears. Go to your integration submission > Configure your integration > Get started with testing to continue with testing your integration.

Note: After you edit a test instance, any previous test results for that instance are invalid and removed from the OIN Submission Tester. Rerun all the required tests again with the new instance.

OIN Submission Tester

Note: The OIN Submission Tester only supports SSO integrations.

The Test integration page includes the integrated OIN Submission Tester, which is a plugin app that runs the minimal tests required to ensure that your sign-in flow works as expected. Ideally, you want to execute other variations of these test cases without the OIN Submission Tester, such as negative and edge test cases. You can't submit your integration in the OIN Wizard until all required tests in the OIN Submission Tester pass.

Before you start testing with the OIN Submission Tester, see OIN Wizard test requirements.

Notes:

• Click Initialize Tester if you're using the OIN Submission Tester for the first time.
• Click Refresh Tester session for a new test session if the OIN Submission Tester session expired.
• See Troubleshoot the OIN Submission Tester if you have issues loading the OIN Submission Tester.

The OIN Submission Tester includes the mechanism to test the following flows:

• IdP flow
• SP flow
• Just-In-Time (JIT) provisioning (with IdP flow)
• Just-In-Time (JIT) provisioning (with SP flow)

Note: The JIT provisioning (with SP flow) test case appears in the OIN Submission Tester if your integration supports JIT and only the SP flow. If your integration supports JIT, IdP, and SP flows, then a successful JIT provisioning (with IdP flow) test is sufficient for the submission.

The test cases for these flows appear in the Test integration using the OIN Submission Tester section depending on your OIN Wizard test information.

Note: See Run test for the steps on how to run each test case.

Your test results in the OIN Submission Tester are valid for 48 hours after the test run. Rerun all your test cases in the OIN Submission Tester if they expired.

Submit your integration if all your tests have passed. If you have errors, see Failed tests to resolve the errors.

Run tests

The Run test option is enabled for test cases that have an eligible test instance.

After you click Run test, the OIN Submission Tester opens a browser window in incognito mode. Use the incognito browser window to execute the test and verify it with the Test in progress dialog that appears in the upper-right corner.

Run the IdP flow test

To run the IdP flow test:

1. Click Run test next to the IdP flow test case.

   A new Chrome browser in incognito mode appears for you to sign in.

2. Sign in to Okta as an end user who's assigned to your test app instance.

   • Your app tile appears on the Okta End-User Dashboard.
   • The tester selects the app tile and you're signed in to your app.

3. Verify that the test end user signed in to your app with the correct profile.

4. Select The user successfully signed in to your app in the upper-right Test in progress dialog to confirm that the IdP flow test passed.

5. Click Continue from the Test in progress dialog to sign out of your app.

   The incognito browser closes and you're redirected to the OIN Submission Tester. The OIN Submission Tester records the test run result and time stamp.

6. Click the IdP flow expand icon () to view the test steps and network traffic details for the test run.

   If your test run wasn't successful, this is a useful tool to troubleshoot the issues and correct your integration, instance, or submission details.

Run the SP flow test

1. Click Run test next to the SP flow test case.

   A new Chrome browser in incognito mode appears for you to sign in.

2. Sign in to your app as the test end user who's assigned to your app instance.

3. Verify that the test end user signed in to your app with the correct profile.

4. Select The user successfully signed in to your app in the upper-right Test in progress dialog to confirm that the SP flow test passed.

5. Click Continue from the Test in progress dialog to sign out of your app.

   The incognito browser closes and you're redirected to the OIN Submission Tester. The OIN Submission Tester records the test run result and time stamp.

6. Click the SP flow expand icon () to view the test steps and network traffic details for the test run.

Run the JIT provisioning with IdP flow test

For the JIT provisioning test, the OIN Submission Tester creates a temporary Okta test user account for you to verify that JIT provisioning is successful. The OIN Submission Tester then removes the test user account from Okta to complete the test.

Notes:

• Ensure that your app integration supports JIT provisioning before you run the JIT provisioning test.
• For JIT provisioning testing, you must have either the super admin role or both the app admin and org admin roles assigned to you.
• The JIT provisioning test case appears only if you select Supports Just-In-Time provisioning in your submission.

To run the JIT provisioning with IdP flow test:

1. Click Run test next to the JIT provisioning (w/ IdP flow) test case.

   The OIN Submission Tester executes the following steps for the JIT provisioning test case:

   1. Creates a user in Okta and assigns them to the test app instance.
   2. Opens an incognito browser window to sign in to Okta.
   3. Sign in to Okta as the test user.
   4. Selects the app tile.
   5. Wait for confirmation that the new test user signed in and was provisioned in your app. You're responsible for verifying this step.

2. Verify that the test user signed in to your app with the correct first name, last name, and email attributes.

   Note: You can go back to the OIN Submission Tester window and expand the test case to view network traffic details for this test run. The NETWORK TRAFFIC tab contains API calls to Okta with the test user details in the request payload.

3. Select The user successfully signed in to your app in the upper-right Test in progress dialog to confirm that the JIT provisioning IdP flow test passed.

4. Click Continue from the Test in progress dialog to sign out of your app.

   The OIN Submission Tester executes the following steps after you click Continue:

   1. Signs out of the app and closes the incognito browser window.
   2. Unassigns the test user from the app instance in Okta.
   3. Deletes the test user from Okta.
   4. Records the test run result and time stamp in the OIN Submission Tester.
   5. Redirects you to the OIN Submission Tester.

5. Click the JIT provisioning (w/ IdP flow) expand icon () to view the test steps and network traffic details for the test run.

Note: The test user account created in your app from JIT provisioning persists after the JIT provisioning test. The OIN Submission Tester only removes the temporary test user account from your Okta org. It's your responsibility to manage the JIT test user accounts in your app.

Run the JIT provisioning with SP flow test

You're only required to pass one JIT provisioning test case to submit your integration. The OIN Submission Tester includes the JIT provisioning (w/ SP flow) test case if you support JIT and only the SP flow. If your integration supports JIT, IdP, and SP flows, then a successful JIT provisioning (w/ IdP flow) test is sufficient for submission.

Similar to the JIT provisioning with IdP flow test, the OIN Submission Tester creates a temporary Okta test user account for you to verify that JIT provisioning was successful. The OIN Submission Tester then removes the test user account from Okta to complete the test.

Follow the same steps in Run the JIT provisioning with IdP flow test to run the JIT provisioning with SP flow test. The only difference in the SP test is that the OIN Submission Tester opens an incognito browser window to sign in to your app first.

Failed tests

If any of your test cases fail, investigate and resolve the failure before you submit your integration. You can only submit integrations that have successfully passed all the required tests in the OIN Submission Tester.

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

Note: You don't have to generate a new app instance 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 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 test instances that aren't in use. You can delete the instance later to clean up your app integration list.

If you have questions or need more support, email Okta developer support at developers@okta.com and include your test results. Follow these steps to obtain your test results:

1. From the OIN Submission Tester, click Export results (upper-right corner) to download a JSON-formatted file of all your test results.

All required tests in the OIN Submission Tester must have passed within 48 hours of submitting your integration.

Test your Universal Logout integration

If your integration supports Universal Logout, you need to test the logout flow manually.

1. Ensure you have an active session on your app.
2. From the Admin Console, go to Directory > People.
3. Select the user that has the current session on your app.
4. Click More Actions > Clear User Sessions.
5. Select Also include logout enabled apps and Okta API tokens, and then click Clear and revoke.
6. Go back to the app and ensure that the session is terminated.

   Note: For partial Universal Logout, the app only revokes the user's refresh tokens when it ends the user's Okta session. This prevents the user from getting new access in the future. However, existing user sessions aren't terminated until the user's existing access tokens expire or the user signs out of an app.

Test your SCIM integration

You need to run three sets of tests for SCIM integrations:

1. SCIM API specification tests

   You need to test your SCIM API service before you conduct SCIM integration tests. Okta provides you with a SCIM API specification test suite to execute in Runscope. See Test your SCIM API for instructions on how to run this test suite. Provide the test results URL in the Link to Runscope spec test results field when you submit your integration to the OIN.

2. Runscope create, read, update, and delete (CRUD) user profile tests

   Enter the results URL from these tests in the Link to Runscope CRUD test results field when you submit your integration to the OIN.

3. Entitlement management Runscope tests

   When you submit your integration to the OIN, enter the URL from the test results in the Link to SCIM Entitlement Management Runscope test results field.

4. Manual Okta SCIM integration tests

   You must certify that you've completed these tests when you submit your integration to the OIN.

Runscope CRUD tests

1. Depending on your selected integration type, download the corresponding CRUD test file:

   • SCIM only: Okta SCIM 2.0 CRUD Test file.
   • SCIM with Entitlement Management: Okta SCIM 2.0 Entitlement Management CRUD Test file.

   This CRUD test file is built for the BlazeMeter Runscope (opens new window) API monitoring tool. If you don't have a Runscope account, you can sign up with a free trial to Runscope (opens new window) for Okta developers.

2. In Runscope, click Import Test.

3. Select API Monitoring Tests as the import format.

4. Click Choose File, and then select the Okta SCIM 2.0 CRUD Test file.

5. Click Import API Test. In the new test bucket, click Editor from the left-navigation menu.

6. Click Test Settings, and then click Initial Variables.

7. Add the following variables with values that match your SCIM integration:

   • oktaOrgUrl: The base URL for your Okta org. Include the https:// prefix.
   • oktaAppId: The unique identifier that's assigned to your test app instance. You can see this value in the App Embed Link panel under the General tab for your instance.

   

   • oktaToken: The Okta API token that's used by Runscope to connect to Okta APIs. You can generate an API token inside your org. See Create an API token.

   • SCIMUrl: The base URL of the SCIM service. For example: https://example.com/scim/v2

   • SCIMAuth: The authorization token that's used to access your SCIM API. You can use the same authorization token you used to Enable API integration from Generate an instance for

     SCIM

     .

     The following is an example of the Runscope variable values:

   

8. Click Test Settings, and then click Initial Script.

9. Copy the contents of the Okta CRUD Initial Script text file and paste into this Runscope console.

10. Click Save & Run.

Review Runscope test results

On the left of your Runscope page, the test appears in the Recent Test Runs section.

1. Click View Progress from the Recent Test Runs section. As the test suite runs, Runscope displays live updates of the test in progress. After the test suite completes, the main panel displays the results of your test.
2. Click a test case to see its Request, Response, and Connection information.

When you're satisfied with your Runscope CRUD test results, enter them in the Link to Runscope CRUD test results field:

1. In your Runscope dashboard, open the test results that you want to share.

2. At the top of the test result, set the Private | Shareable toggle to Shareable.

3. Copy the URL for the test result. The test results can be viewed in detail, but the test can't be edited or rerun by people outside of your team.

   Example of a test result URL: https://www.runscope.com/radar/abcdefghijkl/m01nopq2-3456-7r8s-9012-t34567uvw890/history/123ef4gh-i567-89j0-1k2l-3m4n5o678901.

4. Paste the test results URL into the Link to Runscope CRUD test results field in the OIN Wizard Test integration > SCIM integration testing step section.

Entitlement management Runscope tests

1. Download the Okta SCIM 2.0 Entitlements Test file.

   This Entitlement Management test file is built for the BlazeMeter Runscope API monitoring tool. If you don't have a Runscope account, you can sign up with a free trial to Runscope (opens new window) for Okta developers.

2. In Runscope, click Import Test.

3. Select API Monitoring Tests as the import format.

4. Click Choose File, and then select the Okta SCIM 2.0 Entitlements Test file.

5. Click Import API Test. In the test bucket, click Editor from the left navigation menu.

6. Click Test Settings, and then click Initial Variables.

7. Add the following variables with values that match your SCIM integration:

   • SCIMBaseURL: The base URL of the SCIM service. For example, https://example.com/scim/v2.

   • EntitlementEndpoint: The endpoint of the resource type. For example, /Roles.

   • auth: The authorization token that's used to access your SCIM API. You can use the same authorization token that you used to enable the API integration in Generate an instance for

     SCIM

     .

     The following is an example of the entitlement variable values:

   

8. Click Save & Run.

Manual Okta SCIM integration tests

Execute the test cases in the Okta SCIM Test Plan. Skip the test cases for the features that your integration doesn't support. All the other supported-feature test cases must pass before you can submit your integration to the OIN.

Depending on your test scenario, you can import users from the Import tab (see Import users (opens new window)) or create users in Okta before assigning them to your test instance. See About adding provisioned users (opens new window) and Assign test users to your integration instance.

After you've successfully completed the manual integration tests, you can submit your integration.

Submit your integration

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

The OIN Wizard checks the following for SSO submissions:

• All required instances are detected.
• All required instances are active.
• All required tests passed within the last 48 hours.

The OIN Wizard checks the following for SCIM submissions:

• All required instances are detected.
• All required instances are active.
• The Link to Runscope spec test results field is specified.
• The Link to Runscope CRUD test results field is specified.

Note: See Test your SCIM integration for SCIM submission requirements.

The OIN Wizard checks the following for Universal Logout submissions:

• All required instances are detected.

Submit integration is enabled after all these requirements are met.

1. Select I certify that I have successfully completed required tests.
2. Click Submit integration to submit your integration.
3. Click Close wizard. The Your OIN Integration dashboard appears.

After you submit your integration, your integration is queued for OIN initial review. Okta sends you an email with the expected initial review completion date.

The OIN review process consists of two phases:

1. The initial review phase
2. The QA testing phase

Okta sends you an email at each phase of the process to inform you of the status, the expected phase completion date, and any issues for you to fix. If there are issues with your integration, make the necessary corrections and resubmit in the OIN Wizard.

Note: Sometimes, your fix doesn't include OIN Wizard edits to your integration submission. In this case, inform the OIN team of your fix so that they can continue QA testing.

Check the status of your submission on the Your OIN Integrations dashboard.

See Understand the submission review process.

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

   • When you're constructing your app integration, you can post a question on the Okta Developer Forum (opens new window) or submit your question to developers@okta.com.

2. Using the OIN Wizard to submit an integration phase

   • If you need help with the OIN Wizard, review this document or see Publish an OIN integration.
   • Submit your OIN Wizard question to developers@okta.com if you can't find an answer in the documentation.
   • If you have an integration status issue, contact oin@okta.com.

3. Testing an integration phase

   • If you have issues during your integration testing phase, you can post a question on the Okta Developer Forum (opens new window) or submit your question to developers@okta.com.

See also

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