Data provisioning
Omada Provisioning Service contains two Active directory connectors:
- Active Directory (legacy)
- Microsoft Active Directory
Enabling provisioning
- In the system onboarding view, select the Enable provisioning task.
- In the Method for accounts field, select Omada Provisioning Service.
- In the Method for assignments field, select Omada Provisioning Service.
- In the Provisioning connector field, select Microsoft Active Directory (Template).
- In the Name field, provide a name to your new connector.
- Decide if the connector should use default configuration by selecting the checkbox. Click OK.
The Use default configuration checkbox influences the task mappings and data objects used by the connector.
- If you choose to use the default configuration, the connector will also use the default provided task mappings. Any changes done to these mappings are then saved within the original data objects overwriting them.
- If you choose not to use the default configuration, any changes to the default task mappings create a copy of the out of-the-box mappings and save them in the copies of the provided data objects, retaining the original ones unchanged.
When you onboard a new system utilizing the Microsoft Active Directory connectivity, Omada Identity automatically creates new default Resource Types, Account Resources, Attributes, and Attribute Sets and assign the Attribute Set to the Resource Type of the AD Account. If you use the default configuration, all the necessary steps to perform basic provisioning of a user account to Microsoft Active Directory (with minimum required attributes) are provided out-of-the-box.
The OPS connector for Active Directory removes backslashes from followed by LDAP special characters object names. Attempts to provision an object with requested name being for example Doe\, John results in backslash removal as it's considered an attempt to escape the comma, which is required.
Provisioning configuration
| Parameter | Description |
|---|---|
| Scope | Type the scope for the provisioning, for example dc=company,dc=com or ou=department,dc=company,dc=com. This setting is mandatory, so you must type a relevant value in this field. |
| Domain controller | Specify the domain controller to which the connector will connect. |
| Port | The port number used for communication with the Active Directory domain controller. Standard is 389 and 636 for SSL |
| Use SSL | Enable this to use secure communication. |
| Username | Type the name of the user utilized for provisioning. If you leave this field blank, the username specified for importing is used. |
| Password | Type the password of the user, if you have entered a user name in the Username field above. |
| Initial password | Type an initial password for new users. If the Initial password is entered for a system in the Connection settings, this is only applied if there is no other initial password provided elsewhere (for example,if INITIALPASSWORD is not configured in the Attributes). |
| Allow deletion of user leaf objects | Some applications, for example ActiveSync, use the ability to create child objects on, for example, user objects, even if this is not typically understood as a container object. In such cases, OPS may generate errors when it tries to deprovision such user objects. If you want OPS to delete these leaf objects and all other leaf objects attached to user objects, enable this setting. |
| Create missing containers | If one or more OUs in the DN do not exist in AD, they will be automatically created as part of the OPS provisioning job. |
| Enable connection caching | Enable caching and reusing of Active Directory connections in order to increase the performance of the AD connector. |
| Test connection | Enable this setting to allow the system to check if the connection details are correct. If no details are provided, the connection details taken from the collector are used. |
In the case of connectivity with Active Directory stored on a different server than the OPS, it may also be helpful to provide Domain controller hostname as well as Fully Qualified Domain Name to the hosts file on the server that the OPS is located.
Data model
The Data model for Microsoft Active Directory Connectivity supports the following objects.
AdUser
The AdUser object is used to create, update, and delete users in Active Directory.
Bear in mind that actual operations issued by RoPE for accounts in target systems are CreateOrUpdate and DeleteIfExists.
| Parameter | Type | Description |
|---|---|---|
| dn* | stringType | The dn value is the distinguished name of the OU to place new users in, or where to move users to. |
| samAccountName | stringType | The samAccountName of the user. |
| allowReversiblePasswordEncryption | booleanType | |
| accountExpirationDate | dateTimeType | Specify if the user should auto-expire at a specific date. |
| delegationPermitted | booleanType | Specify if the users’ rights can be delegated. |
| displayName | stringType | The user’s display name. |
| Description | stringType | Description. |
| emailAddress | stringType | Email address for the user. Note that this is usually populated by the Exchange Server. |
| employeeId | stringType | The employee’s ID. |
| Enabled | booleanType | Should the user be enabled or not? Default is True. |
| givenName** | stringType | Given name or first name for User. |
| homeDirectory | stringType | |
| homeDrive | stringType | |
| middleName | stringType | Middle name for the user. |
| name** | stringType | The name of the user. The name should be unique in the OU in which it is placed. In AD it is used as the CN attribute. |
| password** | secureStringType | The password for the user. Note: The connector expects a clear-text string. The OPS service creates the necessary decryption. |
| passwordMustChange | booleanType | Set this to True to force the user to change the password on next logon. |
| passwordNeverExpires | booleanType | Set to True to ensure that the password never expires. |
| passwordNotRequired | booleanType | Set to True if a password is not required for the user. This property can cause some issues if you provision new AD users as a non-domain administrator. |
| permittedWorkstations | stringType(**) | Multi-value list of workstations for which to add or remove the user. |
| scriptPath | stringType | |
| surname** | stringType | Surname or last name of the user. |
| smartcardLogonRequired | booleanType | |
| userCannotChangePassword | booleanType | Set to True to make sure that the user cannot change the password directly. |
| userPrincipalName** | stringType | The user principal name, for example, account@contoso.com. |
| voiceTelephoneNumber | stringType | Voice telephone number. |
| groups | stringType** | Multi-value list of the groups for which to add or remove the user. The value should be the CN value of the group. |
The parameters listed in the table above are not all the available parameters but only the commonly used ones. You can extend the object with additional parameters if required. Properties marked with * are required. Properties marked with ** are required on Create actions.
The dn and name parameters are used to form the DistinguishedName of objects in Active Directory. The DistinguishedName in the CN=xxx,OU=xxx,DC=xxx,DC=xxx format. The CN attribute is taken from the name parameter, while the OU and DC sections is taken from the dn parameter. Example:
name is John Smith, dn is OU=Sales,DC=Company,DC=com. In this case, the DistinguishedName formed from these parameters is CN=JohnSmith,OU=Sales,DC=Company,DC=com.
AdAssignment
The AdAssignment object is used to add or remove a user from a group by specifying the keys of the user in addition to the group.
| Parameter | Type | Description |
|---|---|---|
| assignee* | stringType | The name or DN of the user. |
| groupToAssign | stringType | The name or DN of the group. |
Properties marked with * are required.
AdGroup
The AdGroup object is used to create, update and delete Groups in Active Directory.
| Parameter | Type | Description |
|---|---|---|
| dn | stringType | The dn value is the distinguished name of the OU to place new groups in. |
| isSecurityGroup | booleanType | Set to True to make a security group. The default value is True. |
| groupScope | stringType | Must be a string with one of the following values: Local, Global, or Universal. |
| displayName | stringType | The group’s display name. |
| description | stringType | A description of the group. |
| name | stringType | The name of the group. The value must be unique within the OU in which it is placed. |
| userPrincipalName | stringType | The user principal name, for example, account@contoso.com. |
| samAccountName | stringType | The samAccountName of the group. |
| members | stringType** | A multi-valued list of users to add or remove as members of the group. |
| groups | stringType** | A multi-valued list of groups to add or remove the group as member of. |
The parameters listed in the table above are not all the available parameters but only the commonly used ones. You can extend the object with additional parameters if required. Properties marked with * are required. Properties marked with ** are required on Create actions.
AdOrgUnit
The AdOrgUnit object is used to create, update, and delete Organizational Units in Active Directory.
| Parameter | Type | Description |
|---|---|---|
| name | stringType | The name of the Organizational Unit. |
| parent | stringType | Absolute or relative to the scope (from connector's settings) DN to the parent OU. Organizational Units without parent specified are created in the default scope location. |
| description | stringType | A description of the Organizational Unit. |
| protectedFromAccidentalDeletion | booleanType | Prevents the Organizational Unit from being deleted or moved. |
| managedBy | referenceType | Provides a username that is resolved by the connector into DN required by the Active Directory for this attribute. This is a single value parameter that should be provided as a DN or DN lookup. |
Expressions
Expression helper class which provides functions which makes it easier to write expressions an task mappings. GetDomainFromScope method returns the domain name from a scope string or a distinguished name. The following example:
ADExpressions.GetDomainFromScope("ou=europe,dc=acme,dc=com")
returns acme.com.
The following expression can be used to get the domain name on the domain where OPS is scoped to work in:
ADExpressions.GetDomainFromScope(ConnectorConfiguration.GetValue("adParentNode")))
Task mappings
Omada Microsoft Active Directory Connectivity provides the following mappings out of the box. The mappings are provided as templates and can be adopted to meet customer specific requirements. Attribute names between DataModel and taskMappings are case sensitive.
| Parameter | Description |
|---|---|
| Active Directory - Distribution Group Assignment | Contains mappings of ROPE assignments to AD Distribution Group assignments |
| Active Directory - Distribution Group | Contains mappings of Resource Lifecycle Management resources to AD Distribution Groups |
| Active Directory - Password Reset | Contains mappings for Self-Service Password Reset resources in Active Directory |
| Active Directory - Security Group Assignment | Contains mappings of ROPE assignments to AD Security Group assignments |
| Active Directory - Security Group | Contains mappings of Resource Lifecycle Management resources to AD Security Groups |
| Active Directory - User | Contains mappings of assignments from the ROPE Account to AD User |
| Active Directory - Organizational Unit | Contains sample mappings for organizational units that are not linked by default to the Microsoft Active Directory connector. To enable them follow instruction in the Enabling Organizational Units mapping section. |
Configuration of Task mappings in Omada Identity
To configure and enable task mappings, map the assignments to resources manually:
-
Open the system onboarding view of your Active Directory system.
-
Click Task mappings in the Provisioning section of the view.
-
Click New to create a new task mapping. In the New task mapping window the object types from the Data Model are listed. Select which object you want to create a task mapping for and in the drop-down list, select the corresponding template task mapping.
-
Click OK to go to next page.
-
Select the corresponding Resource type and Mapping type, and optionally a description for the task mapping.
-
Click the Mappings tab to display the default mappings and adjust them according to your requirements.
-
Click OK to confirm and save the changes.
Use the following guidelines when configuring task mappings for group assignments:
- To provision to multiple domains in the same forest, use the DistinguishedName as an assignee.
- To support an external domain trust - one and two-way - use the ObjectSid of the account as assignee.
- If there is only a single domain, use samAccountName.
The default mapping for the assignee is using an expression to cater for those options.
Enabling Organizational Unit mappings
Enabling sample Organizational Unit mappings requires the following manual adjustments:
- The DISTINGUISHEDNAME property needs to be added to organizational unit Data Object Type.
- The MANAGER property has to be limited to users Data Object Type.
The MANAGER property is multivalued. For sample task mappings to work it can only store 0 or 1 users. In case there are two of them stored the OPS task results in failure.
Example:
XML mapping example:
<?xml version="1.0" encoding="UTF-8"?>
<taskMapping xmlns="http://schemas.omada.net/ops/2015/TaskMappingConfigurationML">
<connectorObjectType mappingType="Constant">AdOrgUnit</connectorObjectType>
<mappedObjectType mappingType="Constant">AdOrgUnit</mappedObjectType>
<mappedOperation mappingType="SourceField">Operation</mappedOperation>
<mappedObjectId mappingType="SourceField">ObjectId</mappedObjectId>
<fieldMappings>
<fieldMapping name="name" mappingType="SourceField" action="modify" enabled="true" dataType="stringType" multiValued="false">DOLM_NAME</fieldMapping>
<fieldMapping name="parent" mappingType="Expression" action="modify" enabled="true" dataType="stringType" multiValued="false">DOLM_PARENTOU_Key != null ? NameValuePairExtensions.GetAttributeValue(DOLM_PARENTOU_DISTINGUISHEDNAME, DOLM_PARENTOU_Key) : ""</fieldMapping>
<fieldMapping name="description" mappingType="SourceField" action="modify" enabled="true" dataType="stringType" multiValued="false">DOLM_DisplayName</fieldMapping>
<fieldMapping name="protectedFromAccidentalDeletion" mappingType="Expression" action="modify" enabled="true" dataType="booleanType" multiValued="false">Operation == "Create" || Operation == "CreateOrUpdate" ? "false" : null</fieldMapping>
<fieldMapping name="managedBy" mappingType="SourceField" action="modify" enabled="true" dataType="referenceType" multiValued="false">DOLM_MANAGER_OBJECTGUID</fieldMapping>
</fieldMappings>
</taskMapping>
Defining your own mappings using different source fields does not require additonal configuration.
ProxyAddress mappings
The Active Directory Connector allows you to handle proxyAddresses by easily converting a primary address to a historical address and adding a new primary address. To prevent any unwanted regression on existing configurations, this feature must be enabled manually, by adding the following line to the Connector configuration property of the Active Directory Connector:
EnableProxyAddressHandling=true
Then, two mappings for the proxyAddresses property need to be added:
The first mapping must have action=remove, which can be set in the Edit section. The value "SMTP:*" instructs the AD Connector to convert the primary address to a historic address, for example, SMTP:someone@acme.com to smtp:someone@acme.com. If there are multiple primary addresses, they are all converted. Apart from smtp, other protocols are also supported (such as sip). You can specify the protocol name in the mapping (for example: SIP:*).
The second mapping must have action=add. This mapping adds the new primary address. The functionality is idempotent and ensures that the new address is not added multiple times.