Integrate Active Directory

This tutorial guides you through the process of integrating an Active Directory (AD) service with the Unifyia platform to leverage centralized authentication, user management, and directory services. To learn more about directories refer to the article Integrate Directories.

Prerequisites

  1. An LDAP v3 compliant directory services server.
  2. A read/write on-demand access AD account of your choice.
  3. Allows inbound network access through the firewall (to the AD server).
  4. The external IP address or fully-qualified domain name of the AD server.
  5. For multiple domains, network access for each domain controller.
  6. An AD user to perform binds and queries from the platform to your AD directory. This user must be able to look up users, groups, and user attributes in the Directory Information Tree (DIT).
  7. For the issuance of the derived credential based on the primary credential verification, read access to certain sensitive user attributes to map them in the Unifyia platform.
    • HspdissaunceStatus
    • hspdUpn
    • Others

Integration Steps

To set up a new LDAP configuration, follow these steps:

  1. Log in to the Unifyia platform with administrator credentials.
  2. Navigate Integrations > Data Sources > Directory.
  3. Select + Add Directory.
  4. In the LDAP Settings tab, enter the following information to configure the connection and authentication settings:
    1. Name: Enter a display name for the Active Directory.
    2. Vendor: Select Active Directory.
    3. Connection URL: Enter the LDAP URL of the Active Directory service you want to access. The format is ldaps://server_IP_address:port. For example, ldaps://34.237.137.227:636 or ldaps://utopia-test.utopia.net:636
    4. Use Truststore SPI: Choose the option Only for LDAPs.
    5. Connection Pooling: Disable this setting by moving the toggle button to the left.
    6. Connection Timeout: The recommended minimum is 120000. Specify the value in milliseconds. This set value determines the maximum duration the LDAP client will wait to establish a connection with the LDAP server.
    7. Bind Type: Select as Simple.
      • Bind DN: Enter the Distinguished Name (DN) corresponding to a user or service account within the directory. For example, the LDAP Admin.
      • Bind Credentials: Enter the password corresponding to the user or service account mentioned in the Bind DN.
  5. In the LDAP Searching and Updating section, enter the following information to define the settings for searching and updating the LDAP directory.
    1. Edit Mode: Choose Read Only.
    2. Users DN: For example, DC=utopia,DC=local
    3. Username LDAP Attribute: Value is populated as cn.
    4. RDN LDAP Attribute: Value is populated as cn.
    5. UUID LDAP Attribute: Value is populated as objectGUID.
    6. User Object Classes: Select person, organizationalPerson, user.
    7. User LDAP Filter (Optional): Enter if you require additional LDAP filters.
    8. Search Scope: Choose Subtree.
    9. Read Timeout: Provide a value in milliseconds to specify the maximum amount of time that a client will wait for a response from the server after sending a request. This timeout applies to LDAP read operations.
  6. In the Synchronization Settings, enter the following information to configure how to import the LDAP users and how often to synchronize user data between the LDAP and Unifyia platform:
    1. Import Users: Disable this option. This option is used only when the Edit mode is Read Only. Currently not available.
  7. Select Test Authentication to check if you can authenticate to the directory.
  8. Select Add. The next step is to configure the required LDAP mappers. Once you have completed the LDAP settings, you will find a set of predefined mappers under the Mappers tab.

Mappers

The Mappers feature in the Unifyia platform enables you to add, edit, and delete mappers required for this AD integration with the Unifyia platform. These mappers are listeners triggered by AD when the platform queries about users. Currently, the syncing feature is not supported.

  1. If you need to add additional mappers, select + Add Mapper provide a name for the mapper define the required mappers, and select Save to save the mapper configuration.
  2. If you need to edit and existing mapper, select the Edit icon edit the parameters as required, and select Update to save the mapper configuration. You cannot edit the name and mapper type.
  3. To delete a mapper, select the Delete Select Yes to delete or No to exit the process.

Refer to the tables in the succeeding sections to understand the predefined mappers and mapper types.

Predefined Mappers

The following are the predefined mappers that must not be deleted.

Mapper Name Mapper Type Description
modify date user-attribute-ldap-mapper The modifyTimestamp User Model Attribute (Unifyia) mapped to LDAP Attribute whenChanged.
creation date user-attribute-ldap-mapper The createTimestamp User Model Attribute (Unifyia) mapped to LDAP attribute whenCreated.
username user-attribute-ldap-mapper The username User Model Attribute (Unifyia) mapped to LDAP Attribute cn.
firstname user-attribute-ldap-mapper The firstname User Model Attribute (Unifyia) mapped to LDAP Attribute givenName.
last name user-attribute-ldap-mapper The lastname User Model Attribute (Unifyia) mapped to LDAP Attribute sn.
email user-attribute-ldap-mapper The email User Model Attribute (Unifyia) mapped to LDAP Attribute mail.
MSAD account controls msad-user-account-control mapper Microsoft Active Directory (MSAD) account controls are settings and attributes used to manage and enforce security policies for user accounts within an Active Directory (AD) environment. These controls help administrators enforce password policies, account restrictions, and other security measures. MUSt for password-based login

Additional Mappers Required for PIV and PIV-I Issuance

The following are the additional mappers that must be added if the user is imported from the directory to the Unifyia platform for identity issuance. The fields personAssociation and employeeAffiliation are required for successful identity issuance and the userPrincipalName is a mandatory field if you require the issuance status of the identities to be written back to the directory.

Mapper Type Mapper Type Description

userPrincipalName

user-attribute-ldap-mapper

This mapper is mandatory for the users imported from the directory to the Unifyia platform, especially when the option to write back the issuance status of the credentials is enabled in the workflow. Enter the following details:

  • Name: Enter name as userPrincipalName.
  • Mapper Type: Select mapper type as user-attribute-ldap-mapper.
  • User Model Attribute: Enter value as userPrincipalName
  • LDAP Attribute: Enter value as userPrincipalName.
  • Always Read Value From LDAP: Enable this option.
  • Is Mandatory In LDAP: Enable this option.

personAssociation

hardcoded-ldap-attribute

Person Association indicates the entity or group to which a PIV cardholder belongs. The value may be employee, civil, executive staff, uniformed service, or contractor. This mapper fetches all the users with the given attribute value. Enter the following details:

  • Name: Enter name as personAssociation.
  • Mapper Type: Select mapper type as hardcoded-ldap-attribute.
  • User Model Attribute: Enter value as personAssociation.
  • Attribute Value: Enter Person Association value, for example, as Employee.

employeeAffiliation

hardcoded-ldap-attribute

This refers to the type of affiliation a cardholder has with the agency. This includes whether they are a government employee, contractor, civilian, active duty, or other associated individual like a foreign national. The PIV card itself indicates this affiliation, often through color-coding or printed text. This mapper fetches all the users with the given attribute value. Enter the following details:

  • Name: Enter name as employeeAffiliation.
  • Mapper Type: Select mapper type as hardcoded-ldap-attribute.
  • User Model Attribute: Enter value as employeeAffiliation.
  • Attribute Value: Enter Employee Affiliation value, for example, as Employee.

Available Mapper Types

Below is the list of all mapper types available in the Unifyia platform that you can set as per your organization’s requirements.

Mapper Type Mapper Type Display Name Available Configurations Description
MSAD User Account Mapper (Specific to Microsoft Active Directory (MSAD)) msad-user-account-control-mapper Password Policy Hints Enabled: Enable this option if you wish the users to receive hints or guidance when creating or updating their passwords. Allows to manage and map user account control attributes in MSAD into the Unifyia platform's account state (account enabled, password is expired, etc) by using MSAD attributes such as userAccountControl and pwdLastSet. For example:
  • If pwdLastSet is 0, the platform user is required to update the password.
  • If userAccountControl is 514 (disabled account) the platform user is disabled as well.
This mapper is also able to handle exception code from LDAP user authentication.
MSAD IDs User Account Mapper (Specific to Microsoft Active Directory Lightweight Directory Service (MSAD LDS)) msad-ids-user-account-control-mapper Allows for creating and managing MSAD-LDS user account control mappers for the platform users federated via LDAP. It uses UserAccountDisabled and pwdLastSet MSAD LDS attributes. For example:
  • If pwdLastSet is 0, the platform user is required to update the password.
  • If msDS-UserAccountDisabled is TRUE, the platform user is disabled as well.
This mapper is also able to handle exception code from LDAP user authentication.
LDAP Group Mapper group-ldap-mapper
  • LDAP Groups DN: LDAP DN where the groups of this tree are saved. For example, ou=groups, dc=example,dc=org
  • Group Name LDAP Attribute: The attribute in the LDAP directory that stores the name of the group. This is typically the cn (Common Name) attribute, which identifies the group uniquely within its container. For example, cn=Developers
  • Group Object Classes: Object classes of the group object in the LDAP. If required, you may add more than one object class separated by commas. For groups, common object classes in LDAP are generally groupOfNames.
  • Ignore Missing Groups: Enable this option to ignore and skip over groups that are referenced but not found in the LDAP directory during synchronization processes. This can prevent synchronization errors due to missing groups.
  • Membership LDAP Attribute: The attribute that specifies the members of a group (membership mapping) in the LDAP directory. Usually, it is a member but if the Membership Attribute Type is UID, then use memberUid.
  • Membership Attribute Type: Provide a value to specify the type of value stored in the membership attribute. It may either be a Distinguished Name (DN) or a User ID (UID).
    • DN: DN means that the LDAP group has its members declared in the form of their full DN. For example, member:uid=john,ou=users, dc=example,dc=com.
    • UID: UID means that the LDAP group has its members declared in the form of pure user uids. For example, memberUid: john
  • Membership User LDAP Attribute: Provide this value only if you have provided Membership Attribute Type as UID. It is the name of LDAP attribute on user, which is used for membership mappings. Usually, it will be uid.
  • LDAP Filter: If required, provide an additional custom filter to the whole query to retrieve LDAP groups.
  • Mode: Select an option to specify how group data is managed and synchronized. Currently, only the IMPORT option is supported.
    • READ_ONLY: Groups can only be read. The group mappings are not writable to LDAP.
    • IMPORT: Groups are imported into the platform and can be managed locally.
    • LDAP_ONLY: The specified group mappings are writable to LDAP. Groups exist only in LDAP and are managed there exclusively.
  • User Groups Retrieve Strategy: Select an option to specify how to retrieve groups of a user. Select LOAD_GROUPS_BY_ MEMBER_ATTRIBUTE.
    • LOAD_GROUPS_BY_ MEMBER_ATTRIBUTE: The roles of the user will be retrieved by sending an LDAP query to retrieve all groups where member is our user.
  • Drop non-existing groups during sync: Enable this option to remove groups from the local system (Unifyia platform) that no longer exist in the LDAP directory during synchronization.
  • Groups Path: The Unifyia platform group path to which the LDAP groups are added. The default value is '/' so LDAP groups will be mapped to the Unifyia platform groups at the top level. For example, if value /Unifyia/Application1 is used, then LDAP groups will be available in the Unifyia platform’s database under group Application1, which is a child of the top-level group Unifyia. The configured group path must already exist in the Unifyia platform when creating this mapper.
Allows you to define what and how the group memberships from the LDAP service are to be mapped to Unifyia platform groups.
NOTE: Currently, the Unifyia platform does not support the group syncing feature.
LDAP User Attribute Mapper user-attribute-ldap-mapper
  • User Model Attribute: Enter the name of the user attribute. For example, username.
  • LDAP Attribute: Enter the corresponding LDAP attribute for the user model attribute.
  • Read Only: Select this option if the attribute is read-only and cannot be updated or changed.
  • Always read value from LDAP: Select this option if the mapper value has to be read-only from LDAP.
  • Is Mandatory in LDAP: Select this option if the mapper is mandatory in the LDAP. When an attribute is mandatory the options Attribute Default Value and Force a Default Value apply to this mapper.
  • Attribute Default Value: Enter the default value of the attribute. This value must be specified if the user attribute mapper is mandatory in LDAP.
  • Force a Default Value: Select this option if the default value of the mapper must be enforced. This value must be specified if the user attribute mapper is mandatory in LDAP.
  • Is Binary Attribute: Select this option for binary LDAP attributes.
Allows you to map a single attribute from LDAP user to User Model attribute in the Unifyia platform's database.
Hardcoded LDAP Role Mapper Roles: Select a role to grant to the imported user. Allows you to define which hardcoded role must be automatically assigned to the user imported from LDAP.

Back Next
On this page
Related Links