Update a published integration with the OIN Wizard

Learn how to update an OIDC, SAML 2.0, or SCIM 2.0 published integration in the Okta Integration Network (OIN) using the OIN Wizard.

---

What you need

• A published OIDC, SAML 2.0, or SCIM integration in the OIN
• The Okta Developer Edition org (opens new window) from where you originally submitted your published integration. The OIN Wizard is only available in Okta Developer Edition orgs.
• An admin user in the Okta Developer Edition org with either the super admin or the app and org admin roles

---

Overview

If you have a published Single Sign-On (SSO) or lifecycle management integration in the OIN catalog (opens new window), you can update and resubmit it with the OIN Wizard.

The OIN Wizard currently supports updates for integrations that use the following protocols:

• 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 (opens new window)

Note: You can also update OIDC, SAML 2.0, and SCIM 2.0 integrations with the OIN Wizard that were originally submitted through the OIN Manager.

When you edit a published OIN integration, you need to test the flows for the updated version and the published version for backwards compatibility. The integration version that was previously installed in your customer's org isn't modified with the updated version from the OIN catalog. Testing the published version for backwards compatibility ensures that your integration still works for customers who have already installed it. See Update integration considerations before you edit your published integration.

After you successfully test the updated and published versions of your integration, resubmit your integration to the OIN team. Your integration goes through a submission review process before the updated version is published in the OIN catalog.

Update integration considerations

For published integrations that were migrated from the OIN Manager, if you need to update configured properties that aren't available the OIN Wizard, contact oin@okta.com.

Note: Some considerations on this page are specifically for the

SCIM

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

• You can't update a published SCIM integration with Basic authentication. This breaks the integration for existing customers. For any updates, you must submit a new SCIM integration that implements header authentication or OAuth 2.0 authentication. You can use either token or bearer token format for header authentication.

• If you edit a published SCIM integration that was migrated from the OIN Manager, the Import users (and Import groups if groups are managed) capability is automatically enabled in the OIN Wizard. You must support and test this capability if your previous SCIM integration didn't support it. If you need help with implementing this feature, contact developers@okta.com.

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

  • If you modify the Name (name) property of your integration variables, Okta removes the original variable and creates a variable with your updated name. This action negatively impacts your existing customers if you use the original variable in your integration dynamic properties.

  • Migrated published integrations from the OIN Manager don't have some OIN Wizard restrictions. For instance:

    • Published integrations can have more than three integration variables
    • Published integrations can have variable names with uppercase letters
    • Published integrations can use http (instead of enforced https) in URLs and Expression Language-supported properties

  • If your update introduces new variables and you're using dynamic URLs, ensure that your tests cover various scenarios with different possible values for those variables. The newly introduced variables aren't populated for older instances of your integration.

    For example:

    Your integration update introduced a new variable (companyId), and you use it in your updated SCIM server base URL. The base URL changed from https://fruits.example.com/scim2/myapp/ to 'https://fruits.example.com/scim2/myapp?connection=' + app.companyId. In this case, ensure that the dynamic base URL is also valid for existing instances where the companyId value isn't set.

    To handle empty companyId values, you can define the base URL as:

    'https://fruits.example.com/scim2/myapp' + (String.len(app.companyId) == 0 ? '/' : '?connection=' + app.companyId)
    

    This expression handles scenarios where companyId is populated or empty. See Dynamic properties with Okta Expression Language.

Update your integration

Note: When you edit your published OIN integration, your previous PUBLISHED status and date are overwritten with the DRAFT status and current date.

To update a previously published OIN integration:

1. Sign in to your Okta Developer Edition org as a user with either app admin or super admin roles.

   Note: Edit 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 submission edits from a personal email account.

2. In the Admin Console, go to Applications > Your OIN Integrations.

   Note: If you have a draft submission and want to go straight to testing, see Navigate directly to test your integration.

3. Click your published integration to update from the dashboard. Your published OIN submission appears in read-only mode.

4. From the This integration is read-only information box, click Edit integration.

   Note: You can skip this step if your submission is in draft status. The Edit integration option isn't available for submissions in draft status because it's not in read-only mode.

5. Click Configure your integration to proceed to update your integration as required in the following sections of the OIN Wizard:

   • OIN catalog properties
   • Integration variables

     Note: See Update integration considerations for backwards compatibility with integration variables.

   • SCIM properties
   • Enter test information

6. Click Test your integration to save your updates and move to the testing section of the OIN Wizard.

Test integration updates

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

1. Generate an app instance from your updated integration. See Generate instances for testing.

2. Execute the Runscope CRUD and integration tests with your generated test instance. See Test your integration.

See Submit your updated integration after all required tests are successful.

Note: Test steps on this page are specifically for the

SCIM

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

Generate instances for testing

Generate instances for testing your updates directly from the OIN Wizard. See Required app instances in the OIN Wizard for the instances that you need to generate.

Required app instances

The Required app instances section shows you the instances detected in your org that are required to test your integration.

• The CURRENT VERSION status indicates the instances that you need to test your current integration submission. Generate an instance to test SCIM if No instance detected appears next to the SCIM label.
• The PUBLISHED VERSION status indicates the instances that you need to test backwards compatibility for SSO. If your integration only supports the SCIM protocol, then the OIN Wizard doesn't require a published-version instance.

Depending on the nature of your updates, you may need to generate instances for backwards-compatibility testing. Okta recommends that you execute the Runscope tests on your SCIM published-version instance for backwards compatibility, but it's not a requirement for submission.

• If you're only updating app profiles or mapping, then you don't need to create an extra app instance for SCIM backwards-compatibility testing. You can test the app profile updates in the updated instance version of your submission. See Configure attribute mappings when you generate a SCIM instance for testing. However, if you're updating the properties such as description, logo, or guide link, then Okta recommends that you create an extra app instance for SCIM backwards-compatibility testing.

• If you're updating all other properties from the Configure your integration and Test integration pages, then Okta recommends SCIM backwards-compatibility testing:

  • If you tested and submitted your published integration from the same Okta Developer Edition org, you might already have an existing backwards-compatible instance. Use this older app instance version to test backwards compatibility. See Test your integration.

  • If you don't have an instance based on the published integration, exit the OIN Wizard and create an instance of the SCIM OIN-published instance. See Add existing app integrations (opens new window) to create an OIN-published instance for SCIM backwards-compatibility testing.

Notes: If your integration also supports SSO:

• You can avoid creating another app instance for SSO testing if these conditions apply:
  • Your integration supports SCIM and one SSO protocol.
  • Your integration doesn't support SSO JIT.
  • The Create User SCIM operation is enabled.
• You should already have an instance of your published integration for SSO backwards-compatibility testing. The OIN Wizard ensures that an SSO published instance is available in your org before you update your integration. If you don't have a published-version instance for SSO testing, exit the OIN Wizard and create the SSO OIN-published instance. See Add existing app integrations (opens new window) to create an OIN-published instance for backwards-compatibility testing.

Generate an instance

Generate a SCIM instance based on your submission configuration:

1. From the Test integration page, click Generate instance. A page appears to add your instance details.

   Note: There's a limit of five app instances in an Okta Developer Edition org. The Generate instance option is deactivated when you reach this limit. Deactivate unused instances to make room for new instances in your org. See Deactivate app instances 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}). This app name string is 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

SCIM attribute mappings are configured at the instance-level. Ensure that these mappings reflect the current attributes supported by your app. The OIN team uses the updated attribute mappings in your test instance for integration provisioning settings in the OIN catalog.

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

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

Update attributes

1. Select To App on the left Settings panel of the Provisioning tab. 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 Go to Profile Editor.

4. In the Profile Editor, click Add Attribute.

5. 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.

6. 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.

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

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

9. Click Save.

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

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

12. 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 Attribute value.

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

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

15. Click Save.

16. Repeat these steps for all SCIM attributes that you want to map from your app to Okta (in the Settings > To Okta panel).

Update mappings

1. In the Profile Editor, click Mappings.

2. Click {yourApp} to Okta User at the top of the page.

3. Scroll to the attribute that you want to delete, click the mapping icon (yellow arrow) and select Do not map.

   

4. Click Save Mappings.

5. Perform Do not map and Save Mappings actions for all attributes that you want to remove from your app to Okta mappings.

6. Click Apply updates now to save all the attributes you unmapped.

7. In the Profile Editor, click Mappings.

8. Click Okta User to {yourApp} at the top of the page.

9. Scroll to the attribute that you want to delete, click the mapping icon (yellow arrow) and select Do not map.

10. Click Save Mappings.

11. Perform Do not map and Save Mappings actions for all attributes that you want to remove from Okta to your app mappings.

12. Click Apply updates now to save all the attributes you unmapped.

13. In the Profile Editor, delete all the corresponding attributes from the mapping by clicking X next to the attribute and then clicking Delete Attribute to confirm. Repeat this step for all the attributes that you want to delete.

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

Test your integration

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

1. SCIM API specification tests

   First, test your SCIM API service before you conduct Okta-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

   The Runscope CRUD test relies on your updated SCIM instance for testing. See Runscope CRUD tests for instructions on how to run this test suite. 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. Manual Okta SCIM integration tests

   See Manual Okta SCIM integration tests for instructions on how to run this test suite. There's no field in the OIN Wizard for the Manual Okta SCIM integration tests results, however, you must certify that you've completed these tests when you submit your integration to the OIN.

Note: Okta recommends that you execute the Runscope CRUD tests and the manual Okta SCIM integration tests on a published-version SCIM instance for backwards compatibility. The results of the backwards-compatibility tests aren't requirements for submission.

Submit your updates

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

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.

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.

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:

• 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 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.

• If you have an integration status issue, contact oin@okta.com.