Skip to main content

Connect an Okta Directory (SCIM)

To connect an Okta directory to Tonkean using SCIM, follow the steps below.

You must already have an existing Okta directory to follow this process. If you don't already have an Okta account, visit Okta to create one.

Create an Application in Okta

To connect to Okta from an external service, you must configure an application in Okta.

  1. Navigate to Okta and log in to your account.

  2. Select Applications > Applications. The Applications screen displays.

    applications_side_pane.png

  3. Select Browse App Catalog. The Browse App Integration Catalog screen displays.

    browse_app_catalog_select.png

  4. Enter "SCIM 2.0 Test App (Header Auth)" in the search field and select SCIM 2.0 Test app (Header Auth) in the Suggestions dropdown. The SCIM 2.0 Test App screen displays.

    search_scim_test_app.png

  5. Select Add Integration. The Add SCIM 2.0 Test App (Header Auth) screen displays.

    scim_test_app_select_add.png

  6. If desired, you can enter a name for the application in the Application label field. If you choose to add a custom name, we recommend using the name of the board you plan to connect to the application. Leave all other fields set to their default values. Then, select Next. The Sign-On Options tab displays.

    scim_test_app_naming.png

  7. The Sign-On Option tab allows you to configure how users log in to your application, but this isn't necessary for provisioning. Scroll to the bottom and select Done.

    scim_test_app_select_done.png

Your application is connected.

Configure API Integration

Once your Okta application is connected, you must configure the API integration.

  1. On the SCIM 2.0 Test App (Header Auth) screen, select the Provisioning tab. The Provisioning tab displays.

    okta_app_provisioning.png

  2. Select Configure API Integration.

    configure_api_integration.png

  3. Select the Enable API Integration checkbox. The Base URL and API Token fields display.

    enable_api_integration_select.png

  4. In the Base URL field, enter the server you want to use with the suffix /scim/v2.

    You can find the Tonkean SCIM API URL by selecting your profile icon in the upper right and navigating to Board Settings > Identity Provider.

    enable_api_int_base_url.png

  5. Next, you must generate an API token. To generate this token, open your Tonkean board, select your profile icon in the upper right, and navigate to Board Settings > Identity Provider. Select Create New Provider. The Create New Provider window displays.

    id_provider_create_new_provider.png

  6. Select the Provider Type dropdown and choose OKTA. Then, enter a Display Name for the provider. When finished, select Generate Token. The Access Token displays.

    create_new_provider.png

  7. Select Copy to copy the access token. Paste the token in a separate file.

    create_new_provider_copy_token.png

    This is the last time you'll be able to view the decrypted token, so make sure you save it somewhere safe in case you need to reference it later.

  8. Return to Okta. In the API Token field, enter token, insert a space, and then paste in the API token.

    Remember to include the string token and a space before entering your API token, or Okta will generate an error when testing the credentials.

    enable_api_int_token.png

  9. Select Test API Credentials. If the test is successful, a success message displays. If the test is not successful, an error message displays. The content of the error message should help you troubleshoot potential causes for the error.

    create_new_provider_token_verified.png

  10. Once you receive a success message, select Save.

  11. Select the Provisioning tab. The Provisioning tab displays.

    okta_config_select_provisioning_tab.png

  12. Select Edit. The Provisioning to App settings become editable.

    okta_config_provisioning_select_edit.png

  13. Select the Enable checkboxes that correspond with the following settings:

    • Create Users

    • Update User Attributes

    • Deactivate Users

    okta_config_provisioning_enable_settings.png

  14. When finished, select Save.

The Okta application is successfully integrated with Tonkean.

Add Tonkean Roles to the SCIM Application

Now that the API integration is set up, you can add Tonkean roles to the SCIM application.

  1. In Okta, select Applications > Applications. The Applications screen displays.

  2. Select SCIM 2.0 Test App (Header Auth) from the list of applications. The SCIM 2.0 Test App (Header Auth) screen displays.

    select_scim_test_app.png

  3. On the SCIM 2.0 Test App (Header Auth) screen, select the Provisioning tab. The Provisioning tab displays

    okta_app_provisioning.png

  4. Scroll down to the SCIM 2.0 Test App (Header Auth) Attribute Mappings heading. Below this heading, select Go to Profile Editor. The Profile Editor screen displays.

    attribute_mapping_go_to_profile_editor.png

  5. Select Add Attribute. The Add Attribute window displays.

    dir_prof_editor_add_attribute.png

  6. Enter the following values:

    These are the same values you added in step #4 when adding roles to users.

    1. Data type - string array

    2. Display name - Tonkean Roles

    3. Variable name - tonkeanRoles

    4. External name - tonkeanRoles

    5. External namespace - urn:scim:tonkean

    6. Enum - Select the Define enumerated list of values checkbox.

    7. Attribute members:

      • Process Contributor - PROCESS_CONTRIBUTOR

      • System User - SYSTEM_USER

    8. If the Scope field displays, leave the User personal checkbox unselected.

    application_add_attribute.png

  7. Confirm the values are correct and select Save.

  8. On the Profile Editor screen, select Mappings. The Application User Profile Mappings window displays.

    dir_prof_editor_select_mappings.png

  9. Select Okta User to {Application Name}.

    profile_mappings_select_okta_user.png

  10. Scroll to the down to the bottom of the window and select the dropdown beside the tonkeanRoles. From that dropdown, select user.tonkeanRoles.

    attribute_mapping_select_attribute.png

  11. When finished, select Save Mappings.

The connection and configuration process is complete. You can now provision Tonkean users and groups in Okta.

Assign Users

With Tonkean user roles configured in your SCIM application, you can assign users and user groups to the application, granting users those roles.

Assign User Groups to the Application

Assigning user groups to your SCIM application is the most common way to add users and assign them the appropriate roles.

  1. In the Okta sidenav, select Applications > Applications. The Applications screen displays.

    applications_side_pane.png

  2. Select the SCIM application you want to individually add users to. The SCIM 2.0 Test App (Header Auth) screen displays.

    applications_scim_app_select.png

  3. Select the Assignments tab. The Assignments tab displays.

    applications_scim_assignments_tab_select.png

  4. Select Assign > Assign to Group. The Assign {SCIM App} to Groups window displays.

    application_scim_assign_to_groups.png

  5. Select the group you want to assign to the application. The group configuration fields display.

    application_scim_assign_to_groups_select_group.png

  6. Scroll to the bottom of the window and locate the Tonkean Roles field. Select the role(s) you want to assign the group, then select Save and Go Back.

    application_scim_assign_to_groups_assign_roles.png

  7. Repeat steps #5-6 for any additional groups you want to provision in Tonkean.

Assign Individual Users to the Application

While less common than assigning groups to an application, you can add individual users to your SCIM application.

  1. In the Okta sidenav, select Applications > Applications. The Applications screen displays.

    applications_side_pane.png

  2. Select the SCIM application you want to individually add users to. The SCIM 2.0 Test App (Header Auth) screen displays.

    applications_scim_app_select.png

  3. Select the Assignments tab. The Assignments tab displays.

    applications_scim_assignments_tab_select.png

  4. Select Assign > Assign to People. The Assign {SCIM App} to People window displays.

    application_scim_assign_to_people.png

  5. Select the user you want to assign to the application. The user configuration fields display.

    application_scim_assign_to_people_select_user.png

  6. Scroll to the bottom of the window and locate the Tonkean Roles field. Select the role(s) you want to assign the user, then select Save and Go Back.

    application_scim_assign_to_people_assign_roles.png

  7. Repeat steps #4-5 for each user you want to add. Each user added this way is assigned to the SCIM application with the relevant roles you selected.

In this section: