Automate target resource group membership

Table of Contents

Usually, users of a certain category, such as employees, contractors, etc., are assigned to certain groups by default. In this guide, we do not really work with roles and have users of only one category (Person archetype), but all users are in the all-users group in Active Directory. You have already automated username creation and Active Directory provisioning for new users. It is time now to make sure new users also get assigned to the universal group in which all users should be.

What awaits you in this module

To assign new users to a group automatically, you will take these steps:

  1. Create an AD Group resource object type in the Active Directory resource.

  2. Create an association between the AD Group and AD resource accounts.

  3. Create an association construction in the Person archetype to grant the group membership to the users of the Person archetype.

  4. Reconcile the HRIS resource accounts so that users get recomputed and all are assigned to the group automatically.

If you use the Docker images prepared for this guide, most of the settings are already preconfigured. Follow the steps in this module and review the settings to understand how the group assignment works.

1. Create object type for user groups

In midPoint, groups of users (or any other identities, such as printers) are represented by object types of the entitlement kind. When a user is added to a group, it means the account of the user is associated with the entitlement object type.

Firstly, you need to create the group entitlement object type in the AD resource schema handling.

  1. In Resources > All resources, open the AD resource.

  2. In Schema handling, click Add object type.

  3. Basic information about the object type screen:

    • Display name: e.g., AD Group

    • Kind: Entitlement

    • Intent: e.g., adgroup

    • Default: True

  4. Specify the resource data screen:

    • Object class: groupOfNames

  5. Specify the midPoint data screen:

    • Leave unchanged

  6. Click Save settings

  7. Click Back to object types.

The new object type is in the Active lifecycle state by default. You can leave it at that because you will create the association part of the configuration in the Proposed state, meaning the recurring HRIS import task you have set up earlier will not pick up your new configuration until you activate the association.

2. Associate AD accounts with the group

With the entitlement for the group ready, you need create an association between the entitlement and user accounts. In short, the association definition tells midPoint the following:

  • With what to associate the resource accounts (the group).

  • In which direction the association works (object to subject, i.e., the group contains list of accounts belonging to the group).

  • Which entitlement object attribute (i.e., which attribute of the group) holds the list of subjects, i.e., the accounts.

  • Which subject attribute (i.e., which attribute of the account) to use in the list of subjects belonging to the group—in our case, it is the distinguished name (dn).

It is worth noting that when you associate accounts to an entitlement, nothing is written neither into the account shadows, nor their respective focal objects. It is the entitlement resource object that holds the membership information and midPoint pulls this information from the remote system (e.g., Active Directory) whenever needed (and caches the information if configured to do so).

Learn more: Entitlements and Associations

To add the association:

  1. In the target resource, go to Accounts.

  2. Click Configure and select Associations.

  3. Click Add association.

  4. Fill in the form fields to define the association:

    • ref: The name of the entitlement object you have created earlier: adGroup

    • Display name A human-friendly for the association: e.g., AD Group Membership

    • Kind: Entitlement

    • Intent: adGroup

    • Direction: Object to subject

      • In this case, the entitlement object holds a list of members, i.e., subjects.

    • Association attribute: : member

      • Declares which attribute in the entitlement object holds the member list.

      • This value depends on the remote resource attribute naming.

    • Value attribute: dn

      • Declares which account attribute to store in the association attribute of the entitlement object

      • This value depends on the remote resource attribute naming.

    • Lifecycle state: Proposed

  5. Click Save association settings to save your changes.

Association of AD account with the all-users group
Figure 1. Association of AD accounts with the all-users group

3. Grant all Persons membership in the group

In this guide, we do not use roles; however, it is necessary to have some key to determine which accounts are entitled to the group membership. Normally, user roles would be the key. Here, instead of roles, we can use archetypes for the classification: Only accounts of the Person archetype are eligible for the group membership.

To achieve this, you need to induce the entitlement in the Person archetype:

  1. In Archetypes > All archetypes, open the Person archetype for editing.

    • You can filter archetypes by Name.

  2. In Inducements > Resource, select the Construction Associations tab.

  3. Click New to add a new association.

  4. In the modal that appears, select the group entitlement: cn=all-users,ou=groups,dc=example,dc=com.

    • You may need to click Reload to refresh the list if you do not see the desired entitlement.

  5. Click Done to save the settings.

  6. Click Done in the Construction Associations tab to save the settings.

  7. Click Save in the top toolbar to save the archetype configuration.

Select the group to entitle the Person archetype-related accounts to the group membership
Figure 2. Select the group to entitle the Person archetype-related accounts to the group membership

4. Verify your configuration

To test the new configuration, you need to reconcile the accounts. You can either reconcile the source HRIS accounts or the target AD ones, the simulation results will be the same regardless, because the induced entitlement comes from the Person archetype which is "above" the resources. We suggest simulating on the HRIS, though, because it is the HRIS application from which you import users to midPoint.

Firstly, import preview a single user with empnum 90XX (those are the new users you have added to HRIS when testing the Active Directory provisioning). After the import preview finishes, inspect the results and verify the results are as expected.

Import preview in HRIS of Luise Callahan, showing the projection entitlement would change for the resource object
Figure 3. Import preview of Luise Callahan in the HRIS resource, showing the projection entitlement would change for the resource object

Once you verify the configuration works as expected on one user, create and run a simulated reconciliation task in the HRIS resource.

Follow this guide: Create and Run Tasks in GUI

  1. In the HRIS resource, create a new reconciliation task with the simulation toggle on.

  2. Name it, e.g., HR Reconciliation - development simulation.

  3. Select the Preview mode with the Development configuration in the Execution screen.

  4. Save the task and run it.

When the reconciliation simulation task finishes, review its results: Only the 90XX-series accounts you have added earlier should be affected. The only change should be the addition of entitlements on the AD resource objects.

HRIS resource import simulation task results overview
Figure 4. The HRIS resource import simulation task results overview shows five resource objects would be changed due to the group membership assignment

5. Put the configuration to production

Once you verify the group is assigned to the new 90XX-series users and nothing else changes (as it should not), you can activate the configuration.

To activate the configuration on production, trace back your steps and make sure every new piece you have added is in the Production lifecycle state:

  1. The new AD resource object type for entitlements.

    • Go to the AD resource > Schema handling and ensure the AD Group entitlement is active.

  2. The association between the entitlement and user accounts.

    • In the AD resource > Accounts > Configure > Associations, ensure the association is active.

  3. The construction association in the Person archetype resource inducement.

    • You do not need to do anything here because the archetype is already active and the association construction does not have its own lifecycle.

Once all is active, wait for the recurring HRIS reconciliation task to pick up the accounts and process them. After it finishes, you can verify the results in two places:

  1. In the AD server web UI.

    The all-users group member list in the AD user interface. The new users are shown at the bottom.
    Figure 5. The all-users group member list in the AD user interface. The new users are shown at the bottom.

  2. In Users > Persons, where you open one of the new users for inspection, go to Projections, select the AD projection, and look into the Associations section.

    The projections screen in Luise Callahan’s user profile in midPoint showing the user is a member of the all-users group in AD
    Figure 6. The projections screen in Luise Callahan’s user profile in midPoint showing the user is a member of the all-users group on AD

Next steps

Now that you have a complete target resource provisioning configuration, it is time to think about consistency management. In the beginning, you have decided that the HR information system is your single source of truth (SSoT). That means the data in all midPoint-managed applications should be consistent with what is in the HRIS.

You have configured your midPoint deployment with that in mind and gradually took steps to harmonize the HRIS and AD data. It is now the time to confirm that the setup enforces data consistency across the connected applications even in case of nefarious changes and considers the HRIS as the SSoT.

link

When you are through the basics…

Should you want to pursue more complex group membership configurations, take the MidPoint Deployment: Group Synchronization group after you finish this First steps guide.
Was this page helpful?
YES NO
Thanks for your feedback