Active Directory (AD) integration lets you manage user access to the On-Prem Management Console through your organisation's existing Active Directory, rather than through user accounts added directly to the console. This article explains how to set up, edit, disable and remove the integration.

Before you begin

Before you start configuring the integration in the Management Console, make sure that LDAPS (LDAP over SSL) is configured in your Active Directory. Please also have the following details to hand.

Required details

• The fully qualified domain names (FQDNs) of your Domain Controller(s)
• The LDAPS port shared by all Domain Controller(s) - for example, 636
• The credentials (username and password) for an Active Directory user account
• The Base Distinguished Name (DN) for your AD domain
• The public key for the certificate authority (CA) used to sign the SSL certificate(s) used by LDAPS

Optional details

These are only needed if you want to narrow the scope of the security group search to specific folders:

• The Group Search Base
• The User Search Base
• The User ID Attribute

Where to find this information in Active Directory

The details you need for the configuration form live in your Active Directory. This section explains where to find each one. If you are unsure about any value, please contact your organisation's IT Windows Administrator.

For Microsoft's guidance on managing security groups in Active Directory, see Active Directory security groups on Microsoft Learn.

Domain Controller URL

The Domain Controller URL is the URL of the server where your organisation's Active Directory is hosted. If you are unsure what this is or where to find it, please contact your organisation's IT Windows Administrator.

The credentials for an AD user account

This must not be a Managed Service Account.

To find the username, first locate the user in Active Directory. In the form, you can provide either the User logon name with the domain suffix or the distinguished name (DN) of the user.

You can find the User logon name in the user's properties under Account details.

You can find the distinguished name (DN) in the user's Properties, under the Attribute Editor tab.

The Base Distinguished Name (DN) for the AD domain

The Base Distinguished Name (DN) is the base folder in Active Directory that the Management Console links to and searches within for user mapping.

You can find it in the Properties of the root folder, under the Attribute Editor tab:

1. Right-click the root folder and select Properties.

2. Open the Attribute Editor tab.

3. Double-click the field to open the editor, where you can copy the value.

The public key for the CA used to sign the LDAPS SSL certificate(s)

This is the certificate authority (CA) .pem file used to sign your Active Directory's SSL certificate. It is typically available on the server where Active Directory is hosted. The file must be in .pem or base64 encoded format.

Group Search Base (optional)

The Group Search Base defines where the LDAP query searches from. This optional field narrows the scope of the search to specific Organisational Units (OUs) within your Active Directory.

You provide the distinguished name (DN) of the OU you want to search in. Find it in the Properties of the OU, under the Attribute Editor tab:

1. Right-click the OU and select Properties.

2. Open the Attribute Editor tab.

3. Double-click the field to open the editor, where you can copy the value.

User Search Base (optional)

The User Search Base defines where the LDAP query searches from. This optional field narrows the scope of the search to specific folders within your Active Directory.

You provide the distinguished name (DN) of the folder(s) you want to search in. Find it in the Properties of the folder, under the Attribute Editor tab, then double-click the field to open the editor and copy the value.

User ID Attribute

This value defaults to sAMAccountName in the Management Console's AD Integration form. This defines the User logon name that a user will use to log into the Management Console. 

If you would rather your users be required to login with their User Principal Name (UPN) you can update this value to "userPrincipalName". This will require the user to login to the Management Console with their User logon name and the domain suffix for the your organisation's AD.

Configure the Active Directory integration

Only a user with the ADMIN role can configure the Active Directory integration.

1. Log into your On-Prem Management Console.
2. Navigate to the Active Directory tab.
3. Select Configure Integration to open the AD configuration form.

Complete the configuration form

Enter the following required details. These are the fields needed to test and enable the integration.

You can connect to your Active Directory with just the required fields completed. If you also want to reduce the scope of the security group search to specific folders, complete the optional fields below.

Test the connection

Once the required information is complete, the Continue button becomes available. Select it to test the connection using the details you have provided.

If the connection is successful, a warning message explains that enabling Active Directory will disable standard accounts and revoke all existing sessions. Select Proceed to move on to security group configuration.

If the connection fails, an error message flags the invalid fields. Correct those fields with valid values, then select Continue again to retest.

Configure security groups

Once your core Active Directory details have been validated, you can map Active Directory security groups to Management Console roles.

1. In the role dropdown, select the role the group will map to: ADMIN or USER. This defaults to ADMIN.

2. To identify the security group, either enter its distinguished name (DN) directly into the text box, or select Search.

3. If you select Search, a modal opens where you can search your Active Directory for security groups. The search returns groups whose names match the value you enter.

4. Select Add next to a group to map it to the chosen role. You can assign multiple groups to the same Management Console role.

When a security group is assigned, it appears on the Overview page. To change the role a configured group is mapped to, go to the Overview tab, select the Edit icon and choose a different role.

Once you have configured all the security groups you need, select Finish. Your Active Directory integration is now fully enabled.

Edit the Active Directory integration

To change your Active Directory details, select Edit Configuration in the Active Directory tab. This opens an editable version of the form with the existing values pre-filled.

Disable the integration

To temporarily disable the Active Directory integration, select Disable Integration in the Active Directory tab. This option only appears when Active Directory is enabled. You will be prompted to confirm the action.

Once disabled, the integration shows in a disabled state and all new logins using Active Directory credentials are blocked. To re-enable it, select the Enable Integration option.

Delete the integration

To remove the Active Directory integration completely, open the edit configuration page and select Delete Configuration. You will be prompted to confirm the action.

Deleting the configuration removes all Active Directory details from the Management Console and returns you to the first-time configuration page, where you can add Active Directory details again as required.

Next steps

• For the full list of changes in this release, see the On-Prem Management Console 4.0.0 release notes.