Configure Active Directory

Active Directory can be configured using the VM Squared wizard or by directly editing the configuration file.

Assumptions#

• Have followed the steps in Installation and have a working VM Squared cluster.
• Have added SSH key to the Cluster SSH Authorized Keys outlined in Dashboard Console
• Knowledge of the AD configuration and credentials

Gather pre-requisite information#

You will need several pieces of information from your Active Directory domain before proceeding with the configuration:

• The IP of a domain controller that is accessible by the dashboard
• The credentials of a user account with permissions to read AD objects (typically a dedicated “bind” user is recommended)
• The distinguished name of the base location within your AD domain from which you wish to search for users and groups
• The distinguished name of the security group which contains the users to whom you wish to grant access

Distinguished Names#

The distinguished names be easily obtained through the use of a simple PowerShell script run on a domain controller or a domain-joined machine:

PowerShell script to collect AD information#

$basedn = (get-addomain).distinguishedname
$groupname = Read-Host "Please enter the group name"
$group = (Get-ADGroup -Identity $groupname).distinguishedname
$domaincontrollers = (Get-ADDomainController) | Select Name,IPv4Address
Write-host "Domain Controller Information:"
write-host $domaincontrollers
Write-host "Base DN:         $basedn"
Write-host "Group DN:        $group" 

If desired, the distinguished names can also be obtained directly from the Active Directory Users and Computers MMC

1. Ensure that the Advanced Features view is enabled

2. Navigate to the desired location to grab the base DN, (typically this is just your root domain), right-click, and under Properties, select “Distinguished Name” under Attribute Editor

3. Navigate to the desired group that contains the users you wish to grant access to, and under Properties, select “Distinguished Name” under Attribute Editor

AD Configuration#

Active Directory is configured on VM Squared through the dashboard console.

AD Configuration Wizard#

This guide illustrates the use of the AD configuration wizard to create and test the configuration file prior to it being applied to the VM Squared cluster.

1. SSH onto the VM Squared dashboard console and run the manage-ldap command

VMsquared:vmsquared\dashboard> manage-ldap

Configuration Creation
----------------------
1) Create new AD configuration with wizard
2) Create new AD configuration
3) Create new LDAP configuration
4) Quit

Please select [1-4]:

2. Select option 1 to create a new AD configuration with the wizard, and hit enter.

VMsquared:vmsquared\dashboard> manage-ldap

Configuration Creation
----------------------
1) Create new AD configuration with wizard
2) Create new AD configuration
3) Create new LDAP configuration
4) Quit

Please select [1-4]: 1

3. Enter the hostname or IP address of a domain controller accessible by the dashboard.

Enter hostname or address of the AD server: X.X.X.X

4. Enter the username of the bind account that has permissions to read AD objects in the format of “username@domain”, followed by its password.

Enter username for the AD authentication account (eg. username@domain): bind-user@test-labs.sa.test.com
Enter the password of the AD authentication account: S3cur3Password!

5. Enter the base distinguished name to search for target users and groups, for the example above:

Enter the Base Distinguished Name of where to search for users (eg. cn=users,dc=domain,dc=com): DC=TEST-LABS,DC=sa,DC=test,DC=com

6. Enter the distinguished name of the security group you wish to use, for the example above: CN=normal-users,OU=Groups,OU=TEST-LABS,DC=TEST-LABS,DC=sa,DC=test,DC=com

Enter the Distinguished name of the AD group you wish to map from (eg. cn=normal-users,ou=groups,dc=domain,dc=com): CN=normal-users,OU=Groups,OU=TEST-LABS,DC=TEST-LABS,DC=sa,DC=test,DC=com

7. Select the group in the dashboard (or create a new one) to which you wish to map the AD group

test group to map to
------------------------
1) users
2) admin
3) Create new test group

Please select [1-3]: 1

8. You may add additional mappings at this time if desired, but if you are only adding one group, select n and hit enter

Add further group mappings? (y/n): n

9. At this time, you can choose to test the configuration by selecting the Test option and entering the credentials of a user that exists in the security group selected previously.

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 4
Enter the username: normal-user
Enter the password: N0rmalUs3r!

Trying LDAP server 'server1'
'normal-user' (CN=Normal%20User,OU=Users,OU=TEST-LABS,DC=TEST-LABS,DC=sa,DC=test,DC=com) => groups: 0
Success

10. Once the test is successful, commit the changes to save the configuration.

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 5
Committed

11. Once changes have been committed, select Quit.

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 6
VMsquared:vmsquared\dashboard>

At this point Active Directory has been enabled on the VM Squared cluster.

Manually Editing the AD Configuration#

In some cases it may be preferable to manually define the Active Directory configuration file. The steps below will guide you through the manual configuration process.

1. Connect to the dashboard via SSH and run the manage-ldap command.

VMsquared:vm2\dashboard> manage-ldap

Configuration Creation
----------------------
1) Create new AD configuration with wizard
2) Create new AD configuration
3) Create new LDAP configuration
4) Quit

Please select [1-4]:

2. Select the “Create new AD configuration” option

Configuration Creation
----------------------
1) Create new AD configuration with wizard
2) Create new AD configuration
3) Create new LDAP configuration
4) Quit

Please select [1-4]: 2

3. A sample file will be opened in a text editor. First, you’ll want to change the values for :user: and :password: to reflect that of the bind user that has permissions to read your AD domain.

    # Enter credentials for a user account able to query AD
    :user: 'bind-user@test-labs.sa.test.com'
    :password: 'S3cur3Password!'

4. Next, change the value of :host: to reflect either the IP or FQDN of the desired domain controller. In most cases, the value of :port: should stay the same, but can be changed if applicable.

    # Server Address and Port
    :host: '192.168.1.2'
    :port: 389

5. If needed, you can change the value of :timeout:, but in most cases the default should suffice. If a change is needed, uncomment the line and change the value.

    # :timeout: 15

6. Define the base DN in which users and groups are located. Typically this is the root of the domain

    # base hierarchy where to search for users and groups
    :base: 'DC=TEST-LABS,DC=sa,DC=test,DC=com'

7. In most cases, the :user_field: value should be set to ‘sAMAccountName’. This allows users to log in as simply “username” instead of “username@domain.com”

    # field that holds the user name, sAMAcountName is recommended for Active Directory
    :user_field: 'sAMAccountName'

8. The value of :mapping_timeout: should remain set to the default value

    # Seconds a mapping file remain untouched until the next regeneration
    :mapping_timeout: 300

9. Set a value for the name of the mapping file. This is typically recommended to be left as mapping.yaml, but if the name is changed you must remember to specify that in a later step in which group mapping is defined.

    # Name of the mapping file to use for this server.
    # Multiple servers can share the same mapping file, or they can use
    # different ones, as appropriate.
    :mapping_filename: mapping.yaml

10. The :order: value should be left at its default unless you’ve added an additional authentication server. You can add an additional server if needed, just ensure that the next one is defined as server2, then server3, etc.

:order:
    - server1

Below is an example of a complete configuration file based on the information provided in the steps of using the Configuration Wizard.

# We can define a collection of servers to be
# called when attempting to authenticate a user

server1:
    # Enter credentials for a user account able to query AD
    :user: 'bind-user@test-labs.sa.test.com'
    :password: 'S3cur3Password!'

    # Authentication method
    :auth_method: :simple

    # Server Address and Port
    :host: '192.168.1.2'
    :port: 389

    # Connection and authentication timeout in seconds
    # :timeout: 15

    # base hierarchy where to search for users and groups
    :base: 'DC=TEST-LABS,DC=sa,DC=test,DC=com'

    # field that holds the user name, sAMAcountName is recommended for Active Directory
    :user_field: 'sAMAccountName'

    # Seconds a mapping file remain untouched until the next regeneration
    :mapping_timeout: 300

    # Name of the mapping file to use for this server.
    # Multiple servers can share the same mapping file, or they can use
    # different ones, as appropriate.
    :mapping_filename: mapping.yaml

:order:
    - server1

11. Now that the configuration file has been edited, save your changes with CTRL + S, and then hit CTRL + Q to exit the editor.

12. At the configuration management menu, select the option for Group Mappings

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 3

13. If you left the value of :mapping_filename: the default value in step 9 above, select option 2. Otherwise, select option 1 to create a new mapping file

Group Mappings
--------------
1) Create new mapping file
2) Edit mapping.yaml
3) Delete mapping.yaml
4) Back ...
5) Quit

Please select [1-5]: 2

14. Replace “cn=example_group,ou=Groups,dc=my_company,dc=com” with the distinguished name of the AD group you wish to map, and replace “1” with the ID of a group within the dashboard that you wish to map to the AD group. In some cases, the value 1 may be accurate and can be left in place.

# A mapping file maps from a directory group to a cloud group.
"CN=normal-users,OU=Groups,OU=TEST-LABS,DC=TEST-LABS,DC=sa,DC=test,DC=com": "100"

15. Add lines as-needed to map additional groups. When finished save your changes with CTRL + S, and then hit CTRL + Q to exit the editor.

16. At the Group Mappings menu, select the option to go Back, and then commit your changes at the Configuration Management Menu

Group Mappings
--------------
1) Create new mapping file
2) Edit mapping.yaml
3) Delete mapping.yaml
4) Back ...
5) Quit

Please select [1-5]: 4

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 5
Committed

17. Prior to testing the connection, follow the steps in the “Adding Users” section to ensure all of the requisite users have been created in the dashboard.

18. At the Configuration Management menu, select the Test option, and follow the prompts to confirm the connection is valid.

Configuration Management
------------------------
1) Edit configuration
2) Delete configuration
3) Group Mappings ...
4) Test
5) Commit changes
6) Quit

Please select [1-6]: 4
Enter the username: normal-user
Enter the password: N0rmalUs3r!

Trying LDAP server 'server1'
'normal-user' (CN=Normal%20User,OU=Users,OU=TEST-LABS,DC=TEST-LABS,DC=sa,DC=test,DC=com) => groups: 0
Success

19. Select the Quit option to exit the manage-ldap menu

At this point Active Directory has been enabled on the VM Squared cluster.

Adding AD Users to VM Squared#

Please note that you must create placeholder users in the UI and associate them with the proper group before they will be able to log in. You can create users via the Glasshouse GUI, Manifold API calls, or the VM Squared Dashboard. This guide will focus on the first two options.

Creating Users With the Glasshouse GUI#

1. After logging in, navigate to System > Users. Click the Create button to create a user.

2. Ensure that the username entered matches the username of a user that belongs to an AD group mapped during the configuration.

• Change the “Authentication Type” to LDAP.
• Enter a random character string in the “Password” and “Confirm Password” fields (it simply needs to match), this is required for user creation but does not need to be remembered and will not be used again.

3. Click next, and ensure that the user’s primary group matches the mapping defined during the AD configuration wizard.

4. Click Finish. The user is now able to log in.

Creating Users Systematically With the Manifold API#

To simplify this process, a PowerShell script (provided below) can be used to create the requisite users based on the desired Active Directory group’s current members. The requirements to run this are as follows:

• This script must be run on a domain-joined machine with proper permissions to read AD objects.
• The machine on which it is run must have the ActiveDirectory PowerShell module installed and loaded.
• It requires credentials of a user account with permissions to create and manage users & groups within VM Squared.

Running the script#

1. Save the code block at the end of this article as a ‘.ps1’ file (for illustration purposes, the file is named ‘Manage-Dashboard-Users.ps1’.

2. Open PowerShell and call the script.

3. Enter the name of the AD group you wish to use to create the VM Squared users (in the form of samAccountName). For the example domain illustrated here, that value is “normal-users”.

4. Enter the IP or FQDN of the dashboard.

5. In the credential window that appears, enter the username and password of a VM Squared user with administrative permissions.

6. Select the number of the VM Squared group to which you wish to map the AD users.

7. This script will now determine if the users in the AD group already exist, and if not, automatically create them. This can be run ad-hoc and it will not overwrite existing users.

PowerShell script to add AD users via Manifold API#

 # Request the name of the AD group
$adgroupname = Read-Host "Please enter the AD group name"

# get the AD group members: 
$adgroupmembers = (Get-ADGroupMember $adgroupname |  Get-ADUser -Properties SamAccountName).SamAccountName
write-host "Current group members:"
foreach ($adgroupmember in $adgroupmembers){write-host $adgroupmember}
write-host " "

# prompt for information about the dashboard
$dashboardip = Read-Host "Please enter the dashboard IP address or FQDN"

$creds = Get-Credential
$dashboarduser = $creds.UserName.ToString()

$authInfo = [System.Text.Encoding]::UTF8.GetBytes((“{0}:{1}” -f $dashboarduser,([Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR($creds.Password)))))
$authInfo = [System.Convert]::ToBase64String($authInfo)

function get-authtoken {
    $loginresponse = Invoke-webrequest -Headers @{Authorization=("Basic {0}" -f $AuthInfo)} -uri "https://${dashboardip}/manifold-api/login" -SessionVariable websession -method get #-SkipCertificateCheck
    $authtoken = ($loginresponse.content | convertfrom-json).token
    
    $global:authHeaders = @{}
    $authHeaders.Add("Authorization","token ${authtoken}")
    $authheaders.Add("Content-Type", "application/json")
    }
get-authtoken

$dashboardgroups =  ((Invoke-webrequest -method GET -uri "https://${dashboardip}/manifold-api/v2/cloud/group" -headers $authHeaders).content | convertfrom-json).groups | Select Id,Name
Write-host " "

$i=0
foreach ($dashboardgroup in $dashboardgroups)
{
    $i++
    Write-Host "$i`: $($dashboardgroup.name)"
}
do
{
    $SelectedIndex=(Read-Host -Prompt "Enter the number of the group desired for mapping").ToInt32($null)
}
while ($SelectedIndex -notin (1..$i))
$SelectedItem=$dashboardgroups[$SelectedIndex-1]
$chosengroupname = ($selecteditem).name
$chosengroupid = ($selecteditem).id
Write-host " "
Write-host "You Have selected: $chosengroupname"
Write-host " "
Write-host "Creating users that do not exist"

#refresh auth token to avoid timeout
get-authtoken
$existingusers = (((Invoke-webrequest -method GET -uri "https://${dashboardip}/manifold-api/v2/cloud/user" -headers $authHeaders).content | convertfrom-json).users) 
$userscreated = @()

foreach ($adgroupmember in $adgroupmembers){
$userexists = $null
$userexists = $existingusers | where {$_.name -eq $adgroupmember}
if ($userexists -eq $null){
    write-host "User: $adgroupmember does not exist in the dashboard. It will be created."

# Create new user
$newusername = $adgroupmember
$newpassword = -join ((65..90) + (97..122) | Get-Random -Count 35 | % {[char]$_})
$authtype = "ldap"
$newuser = @"
{
    "AUTH": "$authtype",
    "GIDS": [
      $chosengroupid
    ],
    "PASSWORD": "$newpassword",
    "USERNAME": "$newusername"
  }
"@
$createuser = invoke-webrequest -method POST -uri "https://${dashboardip}/manifold-api/v2/cloud/user" -Headers $authheaders -Body $newuser -ContentType 'application/json'
$newpassword = $null
write-host "User $newusername created"
    }
else{
    write-host "User: $adgroupmember already exists in the dashboard. Please ensure group membership is accurate"
    }
}

Write-host "Here are the current users in the selected group ${chosengroupname}:"
$existinguseridsingroup = (((Invoke-webrequest -method GET -uri "https://${dashboardip}/manifold-api/v2/cloud/group/${chosengroupid}" -headers $authHeaders).content | convertfrom-json).group).users 
foreach ($existinguseridingroup in $existinguseridsingroup){
(((Invoke-webrequest -method GET -uri "https://${dashboardip}/manifold-api/v2/cloud/user/${existinguseridingroup}" -headers $authHeaders).content | convertfrom-json).user) | Select Id,name,auth_driver
}