Syncing Groups and Users from Okta SAML Using 'mi-okta-usersync' Script

In addition to configuring Okta authentication in Metric Insights, you can also sync Okta groups and users by using the mi-okta-usersync script.

General script logic is as follows:

  • Group: Groups are added to Metric Insights and any users in that group can also be added. Groups created in Metric Insights will be named as they are in the Okta server. The mapping is 1:1.
  • Users: If a user in a group that is being synced does not yet exist in Metric Insights, the user will be created in MI (if so desired).
  • Default user settings for new users: The type of a user created in MI with mi-okta-usersync script is specified by the --user-type parameter; if this parameter is not provided, the created user is a  regular user with no default settings. Only informational data for the  user's profile (user ID, email address, first name, last name) is set, along with group membership.

As an example, if you're syncing all users from an Okta group called 'SomeOktaGroup', mi-okta-usersync will create a corresponding group called 'SomeOktaGroup' in Metric Insights. Then, for each user in the Okta group, mi-okta-usersync will create a corresponding MI user and make sure the MI user is in the MI group called 'SomeOktaGroup'.

Subsequent syncs can be set via a cron job to sync the group and the users in that group as well as adding (if so desired) any new users in that same Office 365 group.

Table of contents:

Provisioning Groups and Users

mi-okta-usersync provision Parameters (-h)

Example

  1. Obtain Okta API Token
  2. Run 'mi-okta-usersync' Script from the Web Container
  3. Check the Added Users and Groups in your MI Instance

Provisioning Groups and Users

Note: Run the mi-okta-usersync script inside the web container.

  • For details on parameters available for mi-okta-usersync script, see the Parameters section
  • See the Example section for a detailed example on syncing an Okta group in MI

The 'mi-okta-usersync' script is governed by one basic provision command. Provisioning is the action of creating and syncing Okta groups and users in Metric Insights. Here's an example of a very basic provisioning command using the mi-okta-usersync script:

$ /opt/mi/bin/ mi-okta-usersync provision \  
    --okta-host <Okta host> \  
    --okta-token <Okta token> \  
    --auto-create all \  
    --full-summary \  
    -v \ 
    <Group name>

Note that in order to provision a group we need a few bits of information, namely the Okta host URL, Okta API token, and the group's name.

Note: Okta API tokens have a limited lifetime of 1 month and have to be re-created after expiration.

mi-okta-usersync provision Parameters (-h)

Positional Parameter (required)
group_dns The group names to sync with.
Optional parameters
--help, -h Show this help message and exit.
--okta-host OKTA_HOST, -H OKTA_HOST Define the Okta host to connect to.
--okta-token [OKTA_TOKEN], -P [OKTA_TOKEN] Okta API token.
--verbose, -v Use this parameter to run the query in verbose mode with diagnostics written in contrast to standard output.
--dry-run, -n Use this parameter to perform a test run of a given query. Implies -v.
---no-summary, -q Do not display summary at the end.
--full-summary Display detailed info about every affected user and group in the summary.
--user-type {regular,administrator,power_user}, -t {regular,administrator,power_user} Specify the type of users to be added to Metric Insights. (Available options: regular, administrator, power_user)
--username-attr USERNAME_ATTR The user attribute name to use for the username. (Default: login)
--first-name-attr FIRST_NAME_ATTR The user attribute name to use for the user's first name. (Default: firstName)
--last-name-attr LAST_NAME_ATTR The user attribute name to use for the user's last name. (Default: lastName)
--email-attr EMAIL_ATTR The user attribute name to use for the user's email address. (Default: email)
--skip-default-group Skip adding synced users to Default Group.
--sync-user-limit SYNC_USER_LIMIT The max number of users to sync. (Default: 10000)
--auto-create [{all,groups}], -a [{all,groups}] If specified without value or 'all' key - automatically create an MI group for the group DN if it doesn't already exist. If specified with 'groups' key - new groups will automatically be created, but only existing users will be updated. If not specified - only users in existing groups will be created and updated.
--force Force update related objects.
--target-group TARGET_GROUP Create and sync target Metric Insights group instead of creating Okta similar.
Example

In this example we will sync an Okta group containing 2 users with MI.

1. Obtain Okta API Token

Access your Okta host > Security > API > Tokens tab

  1. To create a new Token, click [Create Token]
  2. Enter a name for the token, click [Create Token]
  3. Save the obtained token value. You will need it for syncing Okta user groups with MI

Note: Okta API tokens have a limited lifetime of 1 month and have to be re-created after expiration.

2. Run 'mi-okta-usersync' Script from the Web Container

  1. Access the web container:
    • MI Simple Installation: mi-console
    • Docker Swarm: docker exec -it <container name> bash
    • Kubernetes: kubectl exec -n <namespace> -it <pod> -- bash
    • OpenShift:
      • Single-container pod: oc exec -it <pod> bash
      • Multi-container pod: oc exec -it <pod> -с <container> bash
  2. Execute mi-okta-usersync provision command, syncing all the users from the my_new_group group
  3. The summary of added groups and users is displayed

3. Check the Added Users and Groups in your MI Instance

Access Admin > Users & Groups > Groups tab

  1. Click on the added group
  2. The synced users are displayed on the Members tab