How Do I Provision Groups to Active Directory Domain Services

How Do I Provision Groups to Active Directory Domain Services

One basic requirement for an identity management system is the ability to provision resources to an external system.
This guide walks you through the main building blocks that are involved in the process of provisioning groups from Microsoft Forefront™ Identity Manager (FIM) 2010 to Active Directory® Domain Services (AD DS), outlines how you can verify whether your scenario works as expected, provides suggestions for managing Active Directory groups by using FIM, and lists additional sources for information.



Before You Begin

In this section, you will find information about the scope of this document.
In general, "How Do I" guides are targeted at readers who already have basic experience with the process of synchronizing objects with FIM as covered in the related Getting Started Guides.

Audience

This guide is intended for information technology (IT) professionals who already have a basic understanding of how the FIM synchronization process works and are interested in getting hands-on experience and more conceptual information about specific scenarios.

Prerequisite knowledge

This document assumes that you have access to a running instance of FIM 2010 and that you have experience in configuring simple synchronization scenarios as outlined in the following documents:

The content in this document is scoped to function as an extension to these introductory documents.

Scope

The scenario outlined in this document has been simplified to address the requirements of a basic lab environment.
The focus is to give you an understanding of the concepts and technologies discussed.
This document helps you develop a solution that involves managing groups in AD DS by using FIM.

Time requirements

The procedures in this document require 120 to 150 minutes to complete.
These time estimates assume that the testing environment is already configured and does not include the time required to set up the test environment.

Getting support

If you have questions regarding the content of this document or if you have general feedback you would like to discuss, feel free to post a message to the Forefront Identity Manager 2010 forum.

Scenario Description

Fabrikam, a fictitious company, is planning to use FIM to manage the groups in the corporation’s AD DS by using FIM.
As part of this process, Fabrikam needs to provision groups to AD DS.
To start with the initial testing, Fabrikam has installed a basic lab environment that consists of FIM and AD DS.
In this lab environment, Fabrikam is testing a scenario that consists of a group that was manually created in the FIM Portal.
The objective of this scenario is to provision the group to AD DS.

When managing groups with FIM, you should first test the synchronization of the group objects, and then add an attribute flow mapping for the member attribute.
This approach simplifies the process of troubleshooting your environment.
The scenario outlined in this document follows this recommendation.
After provisioning a test security group to AD DS, the scenario will be extended with a flow of the member attribute.

Scenario Design

To use this guide, you need three architectural components:

  1. Active Directory domain controller
  2. FIM Synchronization Server
  3. FIM Portal Server

The following illustration outlines the required environment:

You can run all components on one computer.

 

  noteNote
  For more information about how to set up FIM, see the FIM Installation Guide

 

Scenario Components List

The following table lists the components that are part of this scenario in this guide.

 Organizational unit:
  • FIM Objects - Organizational unit that is used as a target for the provisioned group.
 User accounts:
  • ADMA - Active Directory user account with sufficient rights to connect to AD DS.
  • FIMMA - Active Directory user account with sufficient rights to connect to FIM.
 Management agents and run profiles:
  • Fabrikam ADMA - Management agent that exchanges data with AD DS.
  • Fabrikam FIMMA - Management agent that exchanges data with FIM.
 Synchronization Rules:
  • Fabrikam Group Outbound Synchronization Rule - Outbound synchronization rule that provisions users to AD DS.
 Sets:
  • All Groups - Set with dynamic membership for all group objects in FIM.
 Workflows:
  • AD Group Provisioning Workflow – Workflow to bring the FIM user into the scope of the AD Outbound Synchronization Rule.
 Management policy rules:
  • AD Group Provisioning Management Policy Rule - Management policy rule (MPR) that triggers when a resource becomes a member of the All Contractors set.
 FIM Security Group:
  • Test Security Group - Universal Security Group in FIM that you provision to AD DS.

 

Scenario Steps

The scenario outlined in this guide consists of the following building blocks:

 

Configuring the External Systems

In this section, you will find instructions for the resources that you need to create that are outside of your FIM environment.

Creating the organizational unit

You need the organizational unit as a container for the provisioned sample user.

  Step 1  
   Create an organizational unit called FIMObjects in your AD DS.  
  Note: For more information about creating organizational units, see Create a new organizational unit.  

 

Creating the Active Directory user accounts

For the scenario in this guide, you need two Active Directory user accounts:

  • Adma - User account used by the Active Directory management agent.
  • Fimma – User account used by the FIM Service management agent.

In both cases, it is sufficient to create regular user accounts.
More information about the specific requirements of both accounts is found later in this document.

 

  Step 2  
   Create two Active Directory user accounts based on the previous description.  
  Note: For more information about creating user accounts, see Create a new user account.  

 

Configuring the FIM Synchronization Service

For the configuration steps in this section, you need to start the FIM Synchronization Service Manager.

Creating the management agents

For the scenario in this guide, you need to create two management agents:

  • Fabrikam ADMA - management agent for AD DS.
  • Fabrikam FIMMA – management agent for FIM Service Management Agent.

 

Configuring the Fabrikam ADMA

When you configure a management agent for AD DS, you need to specify an account that is used by the management agent in the data exchange with AD DS.
You should use a regular user account.
However, to import data from AD DS, the account must have the right to poll changes from the DirSync control.
If you want your management agent to export data to AD DS, you need to grant the account sufficient rights on the target organizational units.
For more information about this topic, see Configuring the ADMA Account.

To create a group in AD DS, technically, you are required to flow out the object's DN and the groupType.
In addition to this, it is a good practice to flow:

  • display name - Use to make your groups recognizable
  • managedBy - Use to show the owner of the group in FIM
  • member - To track the members of a group
  • sAMAccountName - the NetBIOS name of a security group

In AD DS, it is still common for users to use the sAMAccountName attribute to log on to the directory service.
If you do not specify a value for this attribute, the directory service generates a random value for it.
However, these random values are not user friendly, which is why a user-friendly version of this attribute is typically part of an export to AD DS.

To enable a user to log on to AD DS, you also need to include a password created by using the unicodePwd attribute in your export logic.

  noteNote
  You need to ensure that the value you specify as unicodePwd complies with the password policies of your target AD DS.

 

When you set a password for AD DS accounts, you also need to create an account as an enabled account.
You accomplish this by setting the userAccountControl attribute.

For more information about the userAccountControl attribute, see: Using FIM to enable or disable accounts in Active Directory.

The following table lists the most important scenario specific settings you need to configure:

   Management Agent Designer Page      Configuration
Create Management Agent
  1. Management agent for: Active Directory Domain Service
  2. Name: Fabrikam ADMA
   
Connect to Active Directory Forest
  1. Select directory partitions: “DC=Fabrikam,DC=com”
  2. Click Containers to open the Select Containers dialog and make sure that FIMObjects is the only organizational unit (OU) that is selected.
   
Select Object Types
  • In addition to the already selected Object types, select  group.
   
Select Attributes
  1. Click Show All.
  2. Select the following attributes:
    • displayName
    • groupType
    • managedBy
    • member
    • sAMAccountName

 

  Step 3  
   Create the management agent based on the previous description.  
  Note: For more information, see the following topics in Help:
  • Create a Management Agent
  • Connect to an Active Directory Forest
  • Using the Management Agent for Active Directory
  • Configure Directory Partitions
 
  Important:   Ensure that you have an import attribute flow rule configured for the ExpectedRulesList attribute.  

 

 

Configuring the Fabrikam FIMMA

When you configure a FIM Service management agent, you need to specify an account that is used by the management agent in the data exchange with the FIM Service.
You should use a regular user account.
The account must be the same account as the one you specified during the installation of FIM.
Using Windows PowerShell to Do a FIM MA Account Configuration Quick Test contains a script that you can use to determine the name of the FIMMA account name that you specified during setup and to test whether this account is still valid.

The following table lists the most important scenario specific settings you need to configure.:

   Management Agent Designer Page      Configuration
Create Management Agent
  1. Management agent for: FIM Service Management Agent
  2. Name: Fabrikam FIMMA
   
Connect to Database
  1. Use the following settings:
    • Server: localhost
    • Database: FIMService
    • FIM Service base address: http://localhost:5725
  2. Provide the information about the account you created for this management agent.
   
Select Object Types
  • In addition to the already selected Object types, select Group and Person.
   
Configure Object Type Mappings
  1. In addition to the already existing object type mappings, add the following mappings:
    Data Source Object Type     Metaverse Object Type
    Group     group
    Person     person
   
Configure Attribute Flow
  1. In addition to the already existing attribute flow mappings, add the following attribute flow mappings:

 

  Step 4  
   Create the management agent based on the previous description.  
  Note: For more information, see the following topics in Help:
  • Create a Management Agent
  • Connect to an Active Directory Forest
  • Using the Management Agent for Active Directory
  • Configure Directory Partitions
 
  Important:  Ensure that you have an import attribute flow rule configured for the ExpectedRulesList attribute.  

 

Creating the run profiles

The following table lists the run profiles you need to create for the scenario in this guide:

  Management agent    Run profile
Fabrikam ADMA
  1. Full Import
  2. Full Synchronization
  3. Delta Import
  4. Delta Synchronization  
  5. Export
   
Fabrikam FIMMA
  1. Full Import
  2. Full Synchronization
  3. Delta Import
  4. Delta Synchronization
  5. Export

 

  Step 5  
   Create for each management agent run profiles according to the previous table.   
  Note: For more information, see the Create a Management Agent Run Profile in FIM Help  
  Important:   Verify that provisioning is enabled in your environment.
You can do this by running the script: Using Windows PowerShell to Enable Provisioning.
 

 

Configuring the FIM Service

For the scenario in this guide, you need to configure a provisioning policy:

The objective of this provisioning policy is to bring groups into the scope of the AD User Outbound Synchronization Rule.
By bringing your resource into the scope of the synchronization rule, you enable the synchronization engine to provision your resource to AD DS according to your configuration.

To configure the FIM Service, navigate in Windows Internet Explorer® to http://localhost/identitymanagement.
On the FIM Portal page, to create the provisioning policy, go to the related pages from the Administration section.
To verify your configuration, you should run the Windows PowerShell Script to Document Your Synchronization Triple Configuration:

Creating the synchronization rule

In AD DS, each group has a type and a scope. The group type is either security or distribution. Each group type can have three different scopes:

  • Domain local
  • Global
  • Universal

The following illustration shows the related configuration dialog for groups in AD DS:

The FIM schema defines two separate attributes to track the type and the scope information of a group.
However, in AD DS, only one attribute, groupType, is used to track this information.
When you configure an outbound synchronization rule for AD DS, you need to configure an outbound attribute flow mapping that merges the values for the type and the scope into one attribute value.

To calculate the required groupType value, you can use the following table:

   Type    Scope    GroupType
   Distribution        Global    2
     Domain Local        4
     Universal    8
   Security    Global    - 2147483646  
     Domain Local    - 2147483644  
     Universal    - 2147483640  

In your export attribute flow mapping, you can use this table to define a universal custom expression that handles all cases for groups.
This custom expression consists of a nested IIF statement that differentiates on the first level between the two possible group types.
In a second step, the related scope value is determined within another nested IIF statement.

The following table shows the configuration of the related outbound synchronization rule:

Synchronization Rule Configuration
Name Fabrikam Group Outbound Synchronization Rule
Description
Created Time 3/22/2010
Precedence 1
Data Flow Direction Outbound
Dependency
Scope
Metaverse Resource Type group
External System Fabrikam ADMA
External System Resource Type group
Relationship
Create Resource In External System True
Enable Deprovisioning False
Relationship Criteria
ILM Attribute Data Source Attribute
accountName sAMAccountName
Initial Outbound Attribute Flows
Allow Nulls Destination Source
false dn +("CN=",displayName,",OU=FIMObjects,DC=fabrikam,DC=com")
Persistent Outbound Attribute Flows
Allow Nulls Destination Source
false sAMAccountName accountName
false managedBy displayedOwner
false displayName displayName
false member member
false groupType CustomExpression(IIF(Eq(type,"Distribution"),IIF(Eq(scope,"Universal"),8,IIF(Eq(scope,"Global"),2,4)),IIF(Eq(scope,"Universal"),-2147483640,IIF(Eq(scope,"Global"),-2147483646,-2147483644))))

 

  Step 6  
   Create a synchronization rule according to the data in the previous table.  
  Important:   Verify, that you have selected Initial Flow Only for the attribute flow that has the DN as the destination.  

 

Creating the workflow

The objective of the AD Provisioning Workflow is to bring the group into the scope of the Fabrikam Group Outbound Synchronization Rule.
The following table shows the configuration:

Workflow Configuration
Name Active Directory Group Provisioning Workflow
Description
Workflow Type Action
Run On Policy Update False
Synchronization Rule
Name Fabrikam Group Outbound Synchronization Rule
Action Add

 

  Step 7  
   Create a workflow according to the data in the previous table.  

 

Creating the management policy rule

The required MPR is of type Set Transition and triggers when a resource becomes a member of the All Groups  set.
The following table shows the configuration:

Management Policy Rule Configuration
Name AD Group Provisioning Management Policy Rule
Description
Type Set Transition
Grants Permissions False
Disabled False
Transition Definition
Transition Type Transition In
Transition Set All Groups
Policy Workflows
Type Display Name
Action Active Directory Group Provisioning Workflow

 

  Step 8  
   Create an MPR according to the data in the previous table.  

 

Initializing Your Environment

The objective of the initialization phase is to bring your:

  • Enable the required MPRs for group synchronization
  • Synchronization rule into the metaverse.
  • Active Directory structure into the Active Directory connector space.

To synchronize group objects in your environment, you need to enable the following management policy rules:

Display Name
Synchronization: Synchronization account can read group resources it synchronizes
Synchronization: Synchronization account controls group resources it synchronizes

 

  Step 9  
   Enable the MPRs listed in the previous table.  

 

The following table lists the run profiles that are part of the initialization phase.

 

  Run       Management agent     Run profile
1 Fabrikam FIMMA    Full Import
2      Full Synchronization   
3      Export
4      Delta Import
5 Fabrikam ADMA    Full Import
6      Full Synchronization

 

  Step 10  
   Run the run profiles according to the previous table.  
     Note:     You should verify that your outbound synchronization rule has been successfully projected into the metaverse.  

 

Testing the Configuration

The objective of this section is to test your actual configuration.
To test the configuration, you:

  • Create a sample security group in the FIM Portal.
  • Verify the provisioning requisites of the sample group.
  • Provision the sample group to AD DS.
  • Verify that the group exists in AD DS.

 

Creating a sample security group in FIM

The following table lists the properties of the sample security group:

Attribute Value
   Display Name    Test Security Group
   Domain    Fabrikam
   Account Name    TSGroup
   Scope    Universal
   Member Selection      Manual

 

  Step 11  
   Create a sample security group according the data in the previous table.  

 

Verify the provisioning requisites of the sample user

To provision the sample user to AD DS, two prerequisites must be satisfied:

  1. The user must be a member of the All Contractors set.
  2. Set user must be in the scope of the outbound synchronization rule.

To verify, whether the user is a member of the All Groups Set, you open the Set, and then click View Members.

  Step 12  
   Verify that the user is a member of the All Groups set.  

 

To verify, whether the group is in the scope of the synchronization rule, you should open the group's properties in Advanced View.
The Expected Rules List attribute should list the Fabrikam Group Outbound Synchronization Rule. 

The following illustration shows an example for this:

 

As an alternative, you can also use the script in Using Windows PowerShell to Display the Value of the ERL Attribute of a Group from the FIM ScriptBox.

 

  Step 13  
   Verify that the user is in the scope of the Fabrikam Group Outbound Synchronization Rule.  

 

Synchronizing the sample group

Before you start a first synchronization cycle for a test object, you should track the expected state of your object after each run profile that you run in a test plan.
Your test plan should include next to the general state of your object (created, updated, or deleted) also the attribute values that you expect.
Use your test plan to verify your test plan expectations.
If a step does not return the expected results, do not proceed with to the next step until you have resolved the discrepancy between your expected result and the actual result.

To verify your expectations, you can use the synchronization statistics as a first indicator.
For example, if you expect new objects to be staged in a connector space, but the import statistics returns no "Adds", there is obviously something in your environment that does not work as expected.

 

While the synchronization statistics can give you a first indication of whether your scenario works as expected, you should use the Search Connector Space and the Metaverse Search feature of the Synchronization Service Manager to verify the expected attribute values.

To synchronize the user to AD DS, follow the steps below:

  1. Import the security group into the FIM MA connector space.
  2. Project the security group into the metaverse.
  3. Provision the security group to the Active Directory connector space.
  4. Export status information to FIM.
  5. Export the security group to AD DS.
  6. Confirm the creation of the security group.

To accomplish these tasks, you run the following run profiles.:

  Management agent    Run profile
Fabrikam FIMMA
  1. Delta Import
  2. Delta Synchronization
  3. Export
  4. Delta Import
   
Fabrikam ADMA
  1. Export
  2. Delta Import

After the import from the FIM Service database, Test Security Group and the ExpectedRuleEntry object that links Test Security Group to the AD Group Outbound Synchronization Rule are staged in the Fabrikam FIMMA connector space.
When you review the Test Security Groups' properties in the connector space, next to the attribute values that you have configured in the FIM Portal, you also find a valid reference to the ERE object.

The following screenshot shows an example for this:.

The objective of the delta synchronization run on your Fabrikam FIMMA is to perform several operations:

  • Projection – The new security group object and the related Expected Rule Entry object are projected into the metaverse.
  • Provisioning – The newly projected TSGroup object is provisioned into the connector space of the Fabrikam ADMA.
  • Export Attribute Flows – Export attribute flows occur on both management agents.
    On the Fabrikam ADMA, the newly provisioned TSGroup object is populated with new attribute values.
    On the Fabrikam FIMMA, the existing TSGroup object and the related ExpectedRuleEntry object are updated with attribute values that are a result of the projection.

 

As already indicated by the synchronization statistics, a provisioning activity has taken place on the connector space of the Fabrikam ADMA.
When you review the metaverse object properties of Britta Simon, you find that this activity is a result of the expectedRulesList attribute that has been populated with a valid reference:

During the following export on the Fabrikam FIMMA, the synchronization rule status of Test Security Group is updated from Pending to Applied, which indicates that your outbound synchronization rule is now active on the object in the metaverse:

 

Because a new object has been provisioned to the ADMA connector space, you should have one pending export Add on this management agent.
By using the script called "Using Windows PowerShell to Display the Export Statistics of a Management Agent", you get one reported pending export Add for the Fabrikam ADMA:

In FIM, each export run requires a following delta import to complete the export operation.
The delta import that you run after a previous export run is known as a confirming import.
Confirming imports are required to enable the FIM Synchronization Service to make appropriate update requirements during successive synchronization runs.

 

  Step 14  
   Run the run profiles according to the previous table.  
  Caution:   Each run profile run must succeed without an error.  

 

Verify the provisioned user in AD DS

To verify that your sample user has been provisioned to AD DS, you open the FIMObjects organizational unit.
Test Security Group should be located in it.

 

  Step 15  
   Verify that your sample user exists in the FIMObjects organizational unit.  

 

Extending Your Group Synchronization Logic

Because you have successfully synchronized a group object to AD DS, you are now ready to add more components to your synchronization logic.
This includes the:

  • Owner of a group
  • Members of a group

The owner of a group and the member of a group have one thing in common—both attributes are reference attributes.
When you synchronize reference attributes in FIM, you need to ensure that both objects, the referencing attribute and the referenced attribute, are available in all layers of the synchronization service.
The synchronization service preserves existing reference relationships and also enforces referential integrity.
This means that the synchronization service ensures that the references of referencing objects are pointing to valid objects.

The following illustration outlines this process using the member attribute of a group:

 

 

Keeping references intact across the various data layers (connector space, metaverse, external system) involves a transformation of the reference value into a format that is used by each layer.
For example, in FIM, references are expressed in form of GUID values.
However, in AD DS, reference values are implemented in form of DNs.
During a synchronization run and also during an import from and an export to a data source, the synchronization engine applies the necessary transformation of the reference values.

While groups can contain groups as members, which is also known as group nesting, a group can also have users as members.
To preserve the references that point to user objects, you need to extend your synchronization logic with the components that are required to synchronize user objects.
In How Do I Provision Users to Active Directory Domain Services, you find the required deployment instructions for synchronizing user objects in your environment.
You should extend your group synchronization scenario with the user synchronization logic that is outlined in this document.

After implementing the synchronization logic for users, you should add the sample user Britta Simon as a member to the security group, add Britta to the owners of the groups, and make her the displayed owner.
After a synchronization cycle to AD DS, you find that Britta Simon is the new owner of the group:

 

In addition, you also find that Britta is a member of your sample security group:

 

For more information about reference attributes, see Design Concepts for Managing Reference Attributes.

 

Summary

The objective of this document is to introduce you to the main building blocks for synchronizing a group in FIM to AD DS.
In your initial testing, you should first start with the minimum of attributes that are required to complete a task and add more attributes to your scenario when the general steps work as expected.
Keeping the complexity to a minimal level simplifies the process of troubleshooting.

When you test your configuration, it is very likely that you delete and recreate new test objects.
For objects with a populated ExpectedRulesList attribute, this can result in orphaned ERE objects.
The article called "A method to remove orphaned ExpectedRuleEntry objects from your environment", describes how you can remove these objects from your test environment.

For a production environment, when you manage Active Directory groups by using FIM, you should consider including the following attributes into your synchronization logic:

 

 FIM Attribute Active Directory Attribute Description
  -  dn Attribute that is used in AD DS to store the location of an object
 displayName  displayName User-friendly name to identify an object in the user interface
 accountName  sAMAccountName NetBIOS name of the object in AD DS
 displayedOwner  managedBy Single-valued attribute to store the owner of a group in AD DS
 scope and type  groupType Attribute used to store the scope and the type of a group in AD DS
 member  member  Multivalued attribute
 alias  Alias  Mail nickname for a mail-enabled group

 

Recommended Reading 

Sort by: Published Date | Most Recent | Most Useful
Comments
  • Excellent work Markus!

  • Markus,

    As it seems, I think you have one too many right parenthesis at the end of the following line:

    false groupType CustomExpression(IIF(Eq(type,"Distribution"),IIF(Eq(scope,"Universal"),8,IIF(Eq(scope,"Global"),2,4)),IIF(Eq(scope,"Universal"),-2147483640,IIF(Eq(scope,"Global"),-2147483646,-2147483644))))

    Kind Regards,

    Stefan

Page 1 of 1 (2 items)