Skip to main content

Connect an Okta Directory

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 SCIOM 2.0 Test App screen displays.

    search_scim_test_app.png

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

    • Local host URL: https://{your_name}sbackend.ngrok.io/scim/v2

    • Test environment URL: https://api-test.tonkean.com/scim/v2

  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.

    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 the Tonkean API.

Add Tonkean Roles

Now that the API integration is set up, you must add Tonkean roles to users and to the application.

Add Tonkean Roles to Users

You must add the tonkeanRoles parameter to the users in your directory, and then assign users those roles.

  1. In Okta, select Directory > Profile Editor. The Profile Editor screen displays.

    select_profile_editor.png

  2. Select User. The User profile displays.

    profile_editor_select_user.png

  3. Select Add Attribute. The Add Attribute window displays.

    profile_editor_add_attribute.png

  4. Enter the following values:

    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, select the User personal checkbox.

    application_add_attribute.png

  5. Confirm the values are correct and select Save.

  6. Now, you can provide permissions for users in your Okta directory. In the Okta navigation panel, select People. The People screen displays.

    select_people.png

  7. Select a user. The selected user profile displays.

    okta_people.png

  8. One the user profile, select the Profile tab, then select Edit. The user profile enters edit mode.

    okta_people_profile.png

  9. Scroll to the bottom of the screen. There should be a custom field titled Tonkean Role with checkboxes the values you created in previous steps. Select the checkboxes to assign the roles as desired, then select Save.

    okta_people_profile_finish.png

  10. Repeat steps #7-9 for the rest of the users that you would like to assign a role to in Tonkean.

Add Tonkean Roles to the Application

Once roles are added and assigned to users, you can add Tonkean roles to your Okta 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, select the User personal checkbox.

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

    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.

In this section: