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 app 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:

The OAuth method uses an API token to enable OAuth 2.0 provisioning for the app, after which the token isn't used. The OAuth 2.0 approach is more secure and provides greater granularity of permissions than using the API token method for provisioning.

Use OAuth 2.0 for provisioning (with automatic key rotation)

Early Access release. See Enable self-service features.

This method ensures that your keys are automatically rotated, and eliminates the need for manual key management.

Okta recommends using this method for OAuth2.0 provisioning.

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
    1. Open the Org2Org app.
    2. Go to the Provisioning tab and select Integration from the Settings menu.
    3. Click Edit.
    4. Set the Authentication Scheme to OAUTH Auto-Rotation (recommended).
    5. Click the Copy button next to Client Public Key URL.
  2. In the target org, open the Admin Console and go to ApplicationsApplications.
    1. Create an OAuth 2.0 servce app. See Add an API Service Integration.
    2. On the General tab, go to the Client Credentials section and click Edit.
    3. Set the Client authentication to Public key / Private key.
    4. Set the Configuration to Use a URL to fetch keys dynamically.
    5. Paste the client public key URL from step one in the URL field, and then click Save.
    6. Go to the Admin roles tab and click Edit assignments.
    7. Select Organization Administrator from the Role dropdown menu, and then click Save Changes.
    8. On the Okta API Scopes tab, grant the okta.users.manage scope. This enables the app to create and manage user profiles and credentials. If you want to configure Group Push, grant the okta.groups.manage scope.
    9. On the General tab, go to the General Settings section and click Edit.
    10. Select the Require Demonstrating Proof of Possession (DPoP) header in token requests checkbox, and then click Save.
    11. On the General tab, go to the Client Credentials section and copy the Client ID.
  3. In the source org, paste the client ID in the Target Org Client ID field, and then click Save.
  4. Optional. Click Test API Credentials to ensure that the target org is verified successfully.
  5. 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.
    4. Choose your desired settings and click Save.
  6. Optional. Test your Org2Org provisioning.
    1. In the Provisioning to App section, click Edit.
    2. Select Create Users, Update Users, and Deactivate Users, and then click Save.
    3. 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.
    4. Go to the Admin Console in the target org. Go to DirectoryPeople and confirm that the users assigned to the Org2Org app in the source org have been provisioned.

Use OAuth 2.0 for provisioning (with manual key configuration)

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 app ID from the previous step.
  3. Add an API Service Integration in the target org. Use 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 Save Changes.
  8. 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.
  9. 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.
      4. Choose your desired settings and click Save.
    4. Optional. Test your Org2Org provisioning.
      1. In the Provisioning to App section, click Edit.
      2. Select Create Users, Update Users, and Deactivate Users, and then click Save.
      3. 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.
      4. Go to the Admin Console in 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 apps.
  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.