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 Integrator Free Plan orgs. If you need to test this feature in your Okta Integrator Free Plan org, contact your Okta account team.

Tasks

Configure federation between orgs using OIDC (recommended)

Early Access release. See Enable self-service features.

To configure federation between two Okta orgs using OIDC, first add an Org2Org integration into your source (spoke) org, and then set up an OIDC identity provider in your target (hub) org.

Add an Org2Org integration in your source org

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
  2. Click Browse App Catalog.
  3. Search for and select the Okta Org2Org app.
  4. Click Add Integration.
  5. Complete the fields on the General Settings page:
    • Application Label: Add the name for your source app (for example: Okta spoke org).
    • Base Url: Add the Okta domain name of your target (hub) org (for example: https://your-hub-domain.okta.com).
    • Application Visibility: Select this checkbox if you don't want to show the Org2Org app in the source org's End-User Dashboard. You can change this at a later time if necessary.
    • Browser plugin auto-submit: Select this checkbox to enable the feature.
  6. Click Next.
  7. Select the OpenID Connect sign-on option, and then click Done.

Set up an OIDC IdP in your target org

  1. In the target org, open the Admin Console and go to SecurityIdentity Providers.
  2. Click Add identity provider.
  3. Click OpenID Connect IdP, and then click Next.
  4. In General settings, enter a name for the IdP.
  5. In the Client details section, enter the client ID for the Org2Org app. You can find the client ID from the source org's app list.
  6. Set the Authentication type to Public key / private key.
  7. In the Endpoints section, provide a value in the following fields:
    • Issuer: The URL for the spoke org (for example: https://your-spoke-org).
    • Authorization endpoint: The authorization endpoint for the spoke org (for example: https://your-spoke-org/oauth2/v1/authorize).
    • Token endpoint: The token endpoint for the spoke org (for example: https://your-spoke-org/oauth2/v1/userinfo).
    • JWKS endpoint: The JWKS endpoint for the spoke org (for example: https://your-spoke-org/oaut/v1/keys).
  8. In the Authentication Settings section, use the default settings. For more information on these configurations, see Add an Okta Identity Provider.
  9. Click Finish.
  10. In the summary of your Okta Integration IdP, copy the IdP ID, Authorize URL, and Redirect URI values and store them safely. See Enterprise identity provider for more information.

Finish the Org2Org OIDC configuration in your source org

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
  2. Select the Okta Org2Org app.
  3. On the Authentication tab, click Edit for the Sign-on settings section.
  4. In Advanced Sign-on Settings, paste the IdP ID that you copied earlier into the Target Org IdP ID field.
  5. Click Done.
  6. Optional. Enable provisioning from the source org to the target org using OAuth 2.0 (preferred) or an API token.

Configure federation between orgs using SAML

To configure federation between two Okta orgs using SAML, first add an Org2Org integration into your source (spoke) org, and then set up a SAML identity Provider in your target (hub) org.

Add an Org2Org integration in your 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 tab:
    • Application label: The name of your source org (for example: Okta spoke org).
    • Base URL: The domain URL for the target (hub) org (for example: https://your-hub-org.okta.com).
    • Application visibility: Select this checkbox if you don't want the Org2Org app to appear in the source org's End-User Dashboard. You can change this at a later time if necessary.
    • Browser plugin auto-submit: Leave this setting unchecked.
  6. Click Next.
  7. Select the SAML 2.0 sign-on option.
  8. Click Done.
  9. Open the Org2Org app and go to the Authentication tab.
  10. Click View SAML setup instructions. Use the org-specific instructions to create a SAML IdP in the target org to work with the Org2Org app.

Set up a SAML IdP in your target org

  1. In the target org, open the Admin Console and go to SecurityIdentity Providers.
  2. Click Add identity provider.
  3. Select SAML 2.0 IdP and click Next.
  4. In General settings, add a name for the IdP.
  5. In Account matching with IdP Username, select idpuser.subjectNameId to reference the entity in the SAML assertion that contains the username.
  6. In SAML Protocol Settings, update IdP Issuer URI, IdP Single Sign-On URL, and IdP Signature Certificate fields with the values that you copied earlier.

Finish the Org2Org SAML configuration in your source org

  1. In the source org, open the Admin Console and go to ApplicationsApplications.
  2. Select your Org2Org app.
  3. On the Authentication tab, click Edit for the Sign-on settings section.
  4. In Advanced Sign-on Settings, update the Hub ACS Url and Audience URI fields with the values that you copied from the target org values.
  5. Click Save.
  6. 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 API service integration 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. Select 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. When active_with_pass is selected and Okta Password Sync isn't enabled, the user is created with a temporary password. 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.

Test your Org2Org configurations

After you've set up federation and provisioning between orgs, test your configurations.

Assign a user in your source org to the Org2Org app

  1. In the Admin Console, go to ApplicationsApplications.

  2. Select your Org2Org app.
  3. Go to the Assignments tab and select AssignAssign to People.
  4. Select a user and click Assign.
  5. Click Save and Go Back, and then click Done.
  6. Go to your target org, and go to DirectoryPeople. Search for the user that you assigned the app to and ensure that they're provisioned to the target org.

Push a group in your source org to the Org2Org app

  1. In the Admin Console, go to ApplicationsApplications.

  2. Select your Org2Org app.
  3. Go to the Push Groups tab.
  4. Select Push GroupsFind groups by name.
  5. Select the group you want to push to the target org.
  6. Click Save. Your group is provisioned to the target org.
  7. Go to your hub org, and select DirectoryGroups. If your group users were previously provisioned, they appear in the group.

Create a bookmark app for source org users

You can create a bookmark app for your source org users to sign in to a resource on the target org. You can also hide the Org2Org app icon for your target org users.

  1. In the target org, go to ApplicationsApplications.
  2. Select the app you want to grant to the source org users.
  3. Assign the app to one or more of your source org users.
  4. On the General tab, copy the Embed Link value from the App Embed Link section.
  5. In the source org, Create a Bookmark App integration.
  6. 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, if you concatenate the preceding values, the resulting bookmark URL is https://sourceorg.okta.com/app/okta_org2org/app_ext_id/sso/saml?RelayState=https://targetorg.okta/home/app_name/org_id/app_id
  7. Assign the bookmark app to the user in the source org.
  8. Go to your source org and sign in as the assigned user.