Integrate Okta Org2Org with Okta

You can use the Okta Org2Org integration to authenticate and optionally provision users from a source Okta org to a target org. The integration is installed and configured in the source org. You can use Okta Org2Org to connect multiple source orgs to a single Okta target org. This integration enables the source orgs to push users to the target org.

If you choose to use the provisioning features of the Org2Org app, you can use OAuth 2.0 or an API token to secure the connection between the orgs.

A common scenario where Org2Org is used is the hub-and-spoke model. In these scenarios, the spoke orgs are the source orgs and the hub org is the target org.

The Org2Org integration isn't available in Okta Developer Edition orgs. If you need to test this feature in your Developer Edition org, contact your Okta account team.

Configure federation between orgs

This procedure assumes you're configuring Okta Org2Org in an Okta source org.

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
  2. Click Browse App Catalog.
  3. In the search field, enter Org2Org, and then select Okta Org2Org.
  4. Click Add Integration.
  5. Complete the fields on the General Settings page, and then click Next.
  6. Select a sign-on option. If you select SAML 2.0, click View Setup Instructions and follow the steps.
  7. Click Done.
  8. Go to ApplicationsApplications.
    1. Open the Org2Org app and switch to the Sign On tab.
    2. Click View SAML setup instructions. Follow the directions to create an IdP in the target org to work with the Org2Org app. For details and security best practices, see Add a SAML Identity Provider.
    3. Copy the value of the IdP Single Sign On URL to use in a later step.
  9. Switch to the Assignments tab of the Org2Org app. Assign users and groups to the Org2Org app by completing these steps:
    1. Click Assign, and then select Assign to People or Assign to Groups.
    2. Click Assign next to a user or group name, or use the search field to locate a user or group, and then click Assign.
  10. Configure one or more apps in the target org to allow source org users to access.
    1. Create and configure an application in the target org.
    2. In the General tab of the app, copy the Embed Link value from the App Embed Link section.
    3. In the source org, Create a Bookmark App integration.
    4. Create the URL for the bookmark app by concatenating these values:
      • The IdP Single Sign On URL (for example, https://sourceorg.okta.com/app/okta_org2org/app_ext_id/sso/saml)
      • ?RelayState=
      • The Embed Link value for the app (for example, https://targetorg.okta/home/app_name/instance_id/app_id)

      For example, concatenate the preceding values to create the following URL for your bookmark app: https://sourceorg.okta.com/app/okta_org2org/app_ext_id/sso/saml?RelayState=https://targetorg.okta/home/app_name/org_id/app_id

  11. Optional. Enable provisioning from the source org to the target org using OAuth 2.0 (preferred) or an API token.

Enable provisioning from source to target

If you need provisioning but don't need real-time sync of users, user profile attributes, and groups, manually create source org users in the target org:

  1. In the source org, export a list of active users. In the Admin Console, go to Reports and click Okta Password Health. The report is generated and sent to your email address. You can also download the report. Open the CSV file and filter the Status column to show active users.
  2. In the target org, import the users from the CSV file. Assign them to the groups for their source orgs and to any groups for apps that they need access to.
  3. Manually link the newly created users to the IdP configured for the source org.

If you need provisioning and real-time sync of users, choose one of the following methods:

Use OAuth 2.0 for provisioning

To enable OAuth 2.0 provisioning between orgs, you must use a combination of the Okta APIs and the Admin Console.

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
    1. Open the Org2Org app.
    2. Copy the app ID from the URL. For example, in the URL <sourceorg>/admin/app/okta_org2org/instance/0oa78guhzaGH4KHZt1d7/#tab-import, the ID is 0oa78guhzaGH4KHZt1d7.
  2. List the key credentials for the Org2Org app, passing the application ID from the previous step.
  3. Create an OAuth 2.0 service app in the target org, using the key credentials from the previous step as the keys entry in the jwks object.
  4. In the target org, open the Admin Console and go to ApplicationsApplications. Open the OAuth 2.0 service app.
  5. On the Admin roles tab, click Edit assignments.
  6. Click + Add assignment and then select Group Administrator from the Role dropdown list.
  7. Click + Add assignment and then select Group Membership from the Role dropdown list.
  8. Click Save Changes.
  9. Grant consent for the API scopes that enable the service app to create users and manage user profiles and credentials.
    1. In the target org, open the Admin Console and go to ApplicationsApplications. Open the OAuth 2.0 service app.
    2. On the Okta API Scopes tab, grant the okta.groups.manage and okta.users.manage scopes.
  10. Assign admin roles to the OAuth 2.0 service app.
  11. Optional. Enable provisioning to automate account creation, updates, and deactivation.
    1. In the target org, open the Admin Console and go to ApplicationsApplications. Open the OAuth 2.0 service app and copy the client ID from the General tab.
    2. In the source org, use the Okta API to enable OAuth 2.0-based provisioning.
    3. In the source org, configure the provisioning settings for the Org2Org app.
      1. In the Admin Console, go to ApplicationsApplications.
      2. Open the Org2Org app.
      3. On the Provisioning tab, go to the Okta Org2Org Attribute Mappings section and find the initialStatus attribute. Click Edit. The most common configuration for the initial status Attribute value is Same value for all users and active_with_pass.
      4. Choose your desired settings.
      5. Click Save.
    4. Optional. Test your Org2Org provisioning.
      1. In the Provisioning to App section, click Edit, and then select Create Users, Update Users, and Deactivate Users. Save your settings.
      2. Assign the app to a group. On the Assignments tab, click AssignAssign to Groups, select a group and click Save and Go Back. Click Done. Filter your assignments by people to view the list of users who belong to the group that you configured.
      3. Go to the Admin Console on the target org. Go to DirectoryPeople and confirm that the users assigned to the Org2Org app in the source org have been provisioned.

Use API token for provisioning

  1. Create the API token on the target Okta org:
    1. In the Admin Console, go to SecurityAPI.
    2. Click the Tokens tab, and then click Create token.
    3. Enter a descriptive name for the token, and then click Create token.
    4. Copy the token value to your clipboard or a text editor.
    5. Click OK, got it.
  2. In the source org, open the Admin Console and go to ApplicationsApplications.
  3. Select Okta Org2Org from the list of applications.
  4. Click the Provisioning tab, click Configure API Integration, and then select Enable API integration.
  5. Complete these fields:
    • Security token: Paste the security token that you copied earlier.
    • Prefer Username Over Email: Optional. Select this option if you don't want to use an email address as the username.
    • Import Groups: Optional. Clear the checkbox if you don't want to import groups from the connected org.
  6. Optional. Click Test API Credentials to test the API integration.
  7. Click Save.

  8. Optional. Change the provisioning settings from the target Okta org to the source org:

    1. Click the Provisioning tab, and then select To App under Settings.
    2. Click Edit.
    3. Select the Create Users, Update User Attributes, Deactivate Users, or Sync Password checkboxes.
    4. Click Save.
  9. Optional. Change the provisioning settings from the source org to the target Okta org:
    1. Click the Provisioning tab, and then select To Okta under Settings.
    2. Click Edit in the General, User Creation & Matching, Profile & Lifecycle Sourcing, or Import Safeguard areas to edit the settings.

      When you select Allow Okta Org2Org to source Okta users in the Profile & Lifecycle Sourcing area, the source org is the source for user profile data. When you import Okta users into your target org, updates made to user properties in the source org are applied to other apps that the user is assigned.

    3. Click Save.
    4. Select an option for Initial status (initialStatus). This attribute determines the status of the user in the connected org when they're created, linked, or reactivated. When active_with_pass or pending_with pass is selected, a temporary password is generated for the user. When Okta Password Sync is enabled, the temporary user password is overwritten when the user signs in. The most common configuration for the initial status Attribute value is Same value for all users and active_with_pass. Click Edit. Choose your desired settings, and then click Save.
  10. Optional. Push new Okta groups to the connected org. See Manage Group Push.