Syncing Groups and Users from Office 365 Groups Using 'mi-o365-usersync' Script

In addition to configuring SAML Single Sign-On (SSO) in Metric Insights, you can also sync Office 365 groups and users by using the mi-o365-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 Office 365. The mapping is 1:1, if you want the group name in MI to have a name different from the Office 365 group, use the --target-group parameter.
  • 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-o365-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 Office 365 group called 'SomeO365Group', mi-o365-usersync will create a corresponding group called 'SomeO365Group' in Metric Insights. Then, for each user in the Office 365 group, mi-o365-usersync will create a corresponding MI user and make sure the MI user is in the MI group called 'SomeO365Group'.

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.

The whole process comprises the following steps:

Provisioning Groups and Users

mi-o365-usersync provision Parameters (-h)

Example:

  1. Create an App for Use in Azure AD
    1. Access Microsoft Azure Portal
    2. Register an Application
    3. Add Microsoft Graph Application Permissions
    4. Add Microsoft Graph Delegated Permissions
    5. Grant Admin Consent
    6. Add a Client Secret
    7. Copy Application (client) ID and Directory (tenant) ID
  2. Run 'mi-o365-usersync' Script from the Web Container
  3. Check the Added Users and Groups in your MI Instance

mi-o365-usersync supports proxies. To configure proxy access, run the MI installer with the --proxy-server-https-address option specifying the proxy server address.
Example:  --proxy-server-https-address http://192.168.0.1:3128

Provisioning Groups and Users

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

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

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

$ root@web:/opt/mi# mi-o365-usersync provision \  
    --tenant <Directory (tenant) ID> \  
    --client-id <Application (client) ID> \  
    --client-secret <Client Secret Value> \ 
    --auto-create all \
    --full-summary \ 
    <Group name> \
    -v

mi-o365-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.
--tenant TENANT The directory tenant that you want to request permission from. The value can be in GUID or a friendly name format.
--client-id CLIENT_ID The application ID that the Azure app registration portal assigned when you registered your app.
--client-secret CLIENT_SECRET The client secret that you generated for your app in the app registration portal.
--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: userPrincipalName)
--first-name-attr FIRST_NAME_ATTR The user attribute name to use for the user's first name. (Default: givenName)
--last-name-attr LAST_NAME_ATTR The user attribute name to use for the user's last name. (Default: surname)
--email-attr EMAIL_ATTR The user attribute name to use for the user's email address. (Default: mail)
--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 similar.
--custom-user-attribute CUSTOM_USER_ATTRIBUTE Set list of custom attributes to user sync. Example: attr1,attr2.
--map-attr-to-group MAP_ATTR_TO_GROUP Map user to group based on attribute value. Example: attr1,attr2
--custom-attr-app-id CUSTOM_ATTR_APP_ID The ID of the application used by AAD for storing user data.
--trusted-server-username-attr TRUSTED_SERVER_USERNAME_ATTR The field name that stores the trusted server username. (default: None)
--attributes-transformation ATTRIBUTES_TRANSFORMATION Transformation attributes. Example: '[{'attr_name': 'trusted_server_username', 'action': '^([a-zA-Z0-9._%+-]+)@'}]'. (default: None)
--username USERNAME Run sync for specified user only. Credentials will be taken from config variables: O365_USERSYNC_TENANT, O365_USERSYNC_CLIENT_ID, O365_USERSYNC_CLIENT_SECRET
Example

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

1. Create an App for Use in Azure AD

1.1. Access Microsoft Azure Portal

  1. In Azure Portal, access App registrations
  2. [+ New registration]

1.2. Register an Application

  1. Enter the App's Name
  2. Supported account types: "Accounts in any organizational directory (Any Azure AD directory - Multitenant)" OR "Accounts in this organization only (<directory name> only - Single tenant)"
  3. [Register]

The App menu is opened.

1.3. Add Microsoft Graph Application Permissions

  1. Access API Permissions tab
  2. [+ Add a permission]
  3. Microsoft Graph
  4. [Application permissions]
  5. Enable the following permission:
    • Directory:
      • Directory.Read.All
  1. [Grant admin consent for <directory name>]
  2. [Yes]

1.5. Add a Client Secret

  1. Access Certificates & Secrets tab
  2. [+ New Client Secret]
  3. [Add]
  4. Copy and save Client Secret Value

1.6. Copy Application (client) ID and Directory (tenant) ID

  1. Access Overview tab
  2. Copy Application (client) ID and Directory (tenant) ID

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

  1. Access the web container:
    • MI Simple Installation: mi-web
    • 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-o365-usersync provision command, syncing all the users from the mi-o365-usersync 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