Step 3: Active Directory Prerequisites

In this step, you'll gather and configure prerequisite items for deploying CLICK with an AD Gateway integration. We recommend you download our checklist document and use it to record each of the numbered configuration items to ensure all the data is handy at deployment time.

1. Instance Configuration

CLICK uses Active Directory group membership for authorization, determining what a user is allowed to do. Part of the process of setting up a CLICK instance is identifying the groups that will control CLICK's three major permission sets:

  • Administrators - Have rights to perform all setup and configuration within CLICK and take actions on WorkSpaces.
  • Self-Service Users - Have the ability to start, stop, and reboot WorkSpaces that are assigned to them.
  • Self-Service Rebuild Users - Have the ability to rebuild WorkSpaces that are assigned to them.

You will need to create or select an Active Directory group for each of these roles. The first three configuration items you will capture are the Globally Unique Identifiers (GUIDs) of these groups.

πŸ‘

We recommend

Placing all CLICK-specific users and groups into their own Organizational Unit (OU) for role separation purposes.

1.1 Admin Group GUID

  1. From your company's Domain Controller Active Directory, select or create the CLICK Administrators security group. We recommend naming the group CLICKAdminUsers.
  2. Create or select at least one user and add them to this group so you can verify administrative access to CLICK later.
  3. Capture the objectGUID attribute for the CLICK Administrators group and record it in Item 1.1 of the checklist document. (Finding an Active Directory Group's GUID)

1.2 Self-Service Group GUID

  1. From your company's Domain Controller Active Directory, select or create the CLICK Self-Service Users security group. We recommend naming the group CLICKSelfServiceUsers.
  2. Create or select at least one user and add them to this group so you can verify self-service access to CLICK later.
  3. Capture the objectGUID attribute for the CLICK Self-Service Users group and record it in Item 1.2 of the checklist document. (Finding an Active Directory Group's GUID)

1.3 Self-Service Rebuild Group GUID

  1. From your company's Domain Controller Active Directory, select or create the CLICK Self-Service Rebuild Users security group. We recommend naming the group CLICKSelfRebuildUsers.
  2. Create or select at least one user and add them to this group so you can verify self-service rebuild functionality in CLICK later.
  3. Capture the objectGUID attribute for the CLICK Self-Service Rebuild Users group and record it in Item 1.3 of the checklist document. (Finding an Active Directory Group's GUID)

The CLICK Dashboard authenticates users via SAML Federation. You will need to configure your IdP to integrate properly with CLICK.

2. CLICK AD Gateway

CLICK receives information about your Active Directory environment through a component called the CLICK AD Gateway. This component is deployed into your account using a CloudFormation template. This third section involves preparing the configurations and gathering the data necessary to populate the template parameters at deployment time.

3.1 CloudFormation Template Parameters

The template has a number of optional parameters. In this guide, we will only focus on the required ones, but you can review the AD Gateway Stack Parameters page for detailed information about every parameter.

3.1.2 AdGroupsOUs

CLICK only queries the OUs you tell it to look at. Identify the OUs you would like CLICK to query when searching for groups and capture their Distinguished Names in Item 3.1.2 on the checklist document.

πŸ“˜

If you are entering multiple values, separate them with the pipe (|) character.

3.1.4 AdHost

You will need to specify one or more Domain Controllers for the CLICK AD Gateway to send its queries to. Capture the IP address or Fully Qualified Domain Name (FQDN) of each Domain Controller you would like CLICK to query, and capture them in Item 3.1.4 of the checklist document.

πŸ“˜

If you are entering multiple values, separate them with a comma (,).

3.1.5 AdPeopleOUs

πŸ‘

We recommend

If only a subset of your users will have WorkSpaces, only have CLICK query the OU or OUs where those users reside. You can also make use of the optional AdPeopleQuery parameter to further filter the users CLICK can see.

CLICK only queries the OUs you tell it to look at. Identify the OUs you would like CLICK to query when searching for users and capture their Distinguished Names in Item 3.1.5 on the checklist document.

πŸ“˜

If you are entering multiple values, separate them with the pipe (|) character.

3.1.7 AdPort

You must tell CLICK which port to use when querying your Domain Controllers. The default value for this parameter is 389, the standard port for LDAP communication. Secure LDAP uses port 636 by default, but your organization may have things configured differently. Capture this value in Item 3.1.7 of the checklist document.

3.1.8 AdUser

The AD Gateway Lambda function needs to authenticate its LDAP calls to your Active Directory Domain Controller. Create or select a service account to use for this purpose, and capture its User Principal Name in Item 3.1.8 in the checklist document.

πŸ‘

We recommend an account that

  • Is not used for any other purpose,
  • Has read-only access to Active Directory data, and
  • Has a strong, non-expiring password.

3.1.9 ClickKMSKeyAdminArn

The CLICK AD Gateway CloudFormation template creates a KMS key that will be used to encrypt AWS Systems Manager parameters. You must specify the ARN of an IAM user or role that will be given rights to administer the key. This should be the ARN of the IAM user who will be performing the deployment or the IAM role they will assume while performing the deployment.

If you are using an IAM user, the ARN will be in the format displayed below. Replace 123456789012 with your AWS Account ID, and UserName with your username.

arn:aws:iam::123456789012:user/UserName

If you are using an IAM role, the ARN will be in the format displayed below. Replace 123456789012 with your AWS Account ID, and RoleName with your role's name.

arn:aws:iam::123456789012:role/RoleName

🚧

IAM resource ARNs may also contain path values immediately before the user or role name (e.g. arn:aws:iam::123456789012:role/SomePath/RoleName). Check with your AWS administrator to be sure you have the correct ARN for your user or role.

Capture this value in Item 3.1.9 in the checklist document.

3.1.10 ClickKMSKeyEncrypterArn

Record the same value from Item 3.1.9 into Item 3.1.10 in the checklist document as well.

πŸ“˜

We use the same value in two places because

You can later create an update set for the CloudFormation stack and remove the value for ClickKMSKeyEncrypterArn, ensuring the CLICK AD Gateway is the only resource allowed to decrypt and read your secure AWS Systems Manager parameters.

3.1.11 CodeDeployBucket

You will most likely not need to change the default value of click-ad-gateway in item 3.1.11 in the checklist document. This specifies the S3 bucket that will be used for the CLICK AD Gateway Lambda source code. If you are doing a custom or complex deployment, you may need to specify a different bucket.

3.1.12 Endpoint

Leave Item 3.1.12 in the checklist document blank. The endpoint is a URL that will be provided by CLICK during deployment where the CLICK AD Gateway will send the encrypted AD data it queries.

3.1.14 SSMPrefix

Leave Item 3.1.14 in the checklist document at its default value of /click/. This value specifies the prefix the CLICK AD Gateway will use when looking up the SSM parameters it needs to use to retrieve sensitive information. You should only need a different value if you are performing a custom or complex deployment.

3.1.15 ScheduleRate

Item 3.1.15 in the checklist document has a default value of rate(1 hour). This value determines how often the CLICK AD Gateway will query your AD environment and send updated values to CLICK. If you have a different desired schedule, change the expression accordingly. This expression follows the CloudWatch Schedule Expression format.

3.1.16 SecurityGroupIds

The CLICK AD Gateway's network permissions will be determined by a security group you assign to it. Select or create one or more security groups that meet the following conditions and make a note of its ID in Item 3.1.16 the checklist document.

🚧

The security group(s) must

  • Allow outbound requests on your LDAP port (see Item 3.1.7) and
  • Allow outbound requests on port 443.

more detail

3.1.17 SubnetIds

Since the CLICK AD Gateway must communicate with your Active Directory Domain Controller, it must be launched in a subnet inside one of your VPCs. Identify one or more subnets (we recommend at least two) that meet the following requirements and make note of their IDs in Item 3.1.17 in the checklist document.

🚧

The subnets must

  • Have a route to your Active Directory Domain Controller,
  • Have a route to the Internet, and
  • Allow outbound Internet traffic on port 443.

more detail

3.1.19 TrustRoleArn

Leave Item 3.1.19 in the checklist document at its default value. This ARN value is provided by CLICK at deployment time and is used to secure cross-account connections between CLICK and the CLICK AD Gateway.

3.1.20 UseSecureLdap

The default value for Item 3.1.20 is false. If you are using Secure LDAP to query your Domain Controllers, change the value to true.

3.2 AWS Systems Manager Secure Parameters

Once you deploy the CLICK AD Gateway CloudFormation template, you will need to create two AWS Systems Center Secure Parameters (three if you are using Secure LDAP).

πŸ“˜

Note that the /click/ in each of these values corresponds to the value you specify in Item 3.1.14 in the checklist document. If you have specified a different SSM Prefix, the names of these values must also change accordingly.

3.2.1 /click/ad/password

This item represents the password for the AD service account you specified in Item 3.1.8 in the checklist document. We recommend you do not write down the password in plaintext. Store it somewhere securely, knowing that you will need it at this stage of your deployment.

3.2.2 /click/ad/cert

If you are using Secure LDAP, you will need to provide the CLICK AD Gateway with the public key of the SSL Certificate used to secure the LDAP communication. We recommend you do not write down the key in plaintext. Store it somewhere securely, knowing that you will need it at this stage of your deployment.

3.2.3 /click/shared_secret

Leave Item 3.2.3 in the checklist document at its default value. This value is provided by CLICK at deployment time and used to secure the transmission of AD data back to CLICK.

4. Checklist Verification

At this point, you should have performed all the necessary configuration to enable a straightforward deployment of CLICK into your environment. Before continuing, take a moment to review your completed checklist document.

In order to integrate CLICK with your Active Directory, at a minimum, you should have values for the following items (some of these may be defaults, and that is fine):

Item No.NameSample Value
1.1Admin Group GUIDfecc3121-13ab-485a-9760-c5befeb9ae92
1.2Self-Service Group GUIDff5124d4-9144-4885-837e-5410f7d5bebc
1.3Self-Service Rebuild Group GUID9ea3e96b-cfc3-4e93-acdc-e9e4b6c7b74f
3.1.2AdGroupsOUsou=Groups,DC=ad,DC=yourcompany,DC=com
3.1.4AdHostdc1.ad.yourcompany.com
3.1.5AdPeopleOUsou=People,DC=ad,DC=yourcompany,DC=com
3.1.7AdPort389
3.1.8AdUser[email protected]
3.1.9ClickKMSKeyAdminArnarn:aws:iam::123542123542:role/yourcompany-admin
3.1.10ClickKMSKeyEncrypterArnarn:aws:iam::123542123542:role/yourcompany-admin
3.1.11CodeDeployBucketclick-ad-gateway
3.1.14SSMPrefix/click/
3.1.15ScheduleRaterate(1 hour)
3.1.16SecurityGroupIdssg-0f8cc6fd8712ff1cd
3.1.17SubnetIdssubnet-daf6cfc31bbd0ffff
subnet-0c56cdca1b6d0f8d4
3.1.20UseSecureLdapfalse
3.2.1/click/ad/passwordshould be securely stored elsewhere

As long as you've got all of these values, congratulations, you are ready to deploy CLICK!


What’s Next