Windows AD authentication (via LDAP)

Canopy can authenticate against a Window Active Directory (AD) server via LDAP as a SSO solution with just in time user creation. Additionally it can populate user fields and role assignments directly from AD attributes and groups.

AD authentication related settings are configured in /etc/canopy/canopy.ini and requires Canopy to be restarted after modification.

Requirements

  • Dedicated user to query AD via LDAP, should only have rights to lookup users and their groups.

  • CA certificate of LDAP server for secure communication.

Optional

  • Client side certificate for Canopy to authenticate to AD server.

SSL/TLS configuration

None of these options are required but since LDAP communication is unencrypted by default it is highly recommended to at least use SSL (via ldaps://uri) and providing the CA certificate via AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CACERTDIR or AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CACERTFILE.

One can then also set AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_REQUIRE_CERT=OPT_X_TLS_DEMAND to ensure that the certificate is verified.

Client side certificate can be configured via AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CERTFILE=/path/file.pem and AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_KEYFILE=/etc/path/file.pem.

If STARTTLS is required then AUTH_LDAP_START_TLS=true can be set.

Attribute mapping

It is recommended to at least map the name attribute to Canopy’s name field. Since Canopy uses the email address attribute as the usernames and it will always be populated.

Additional fields can be mapped via the AUTH_LDAP_USER_ATTR_MAP option, which is a pipe delimited list of key:value pairs, e.g.

# Minimum recommended
AUTH_LDAP_USER_ATTR_MAP=name:name

# Mapping more fields
AUTH_LDAP_USER_ATTR_MAP=name:name|landline:telephoneNumber|department:department

Canopy user profile fields

These Canopy fields can be mapped to LDAP attributes. Since Canopy uses email addresses as usernames, the email address is mapped already.

  • name

  • title

  • bio

  • landline

  • mobile

  • address

  • department

  • public_holiday_country_code

Role assignment

Assigning roles based on AD groups is optional and not all flags need to be mapped. Unmapped flags can be managed via the Canopy admin interface.

Role fields currently supported:

  • is_admin

  • is_technical_managers

  • is_senior_analysts

  • is_analysts

  • is_schedulers

  • is_sales_managers

  • is_account_managers

  • is_custom_pr_reviewers

  • is_custom_qa_reviewers

Role mappings are pipe delimited list of ROLE_FIELD:GROUP_DN pairs. If a user is in the GROUP_DN group then they will be assigned the specified ROLE and visa versa.

Example group to role mapping:

AUTH_LDAP_USER_FLAGS_BY_GROUP=is_admin:CN=Admins,CN=Canopy Users,DC=example,DC=local|is_technical_managers:CN=Technical Managers,CN=Canopy Users,DC=example,DC=local|is_senior_analysts:CN=Senior Analysts,CN=Canopy Users,DC=example,DC=local|is_analysts:CN=Analysts,CN=Canopy Users,DC=example,DC=local|is_schedulers:CN=Schedulers,CN=Canopy Users,DC=example,DC=local|is_sales_managers:CN=Sales Managers,CN=Canopy Users,DC=example,DC=local|is_account_managers:CN=Account Managers,CN=Canopy Users,DC=example,DC=local|is_custom_pr_reviewers:CN=PR Reviewers,CN=Canopy Users,DC=example,DC=local|is_custom_qa_reviewers:CN=QA Reviewers,CN=Canopy Users,DC=example,DC=local

Note

Everything in the above code block is on a single line in the config file.

Example config

[settings]
# Example settings for Windows AD auth
AUTH_LDAP_ENABLE=true
AUTH_LDAP_SERVER_URI=ldap://windows.ad.local
# SSL can be used via the URI ldaps://windows.ad.local

# SSL Options, all of them are optional but some are required for SSL to function
#AUTH_LDAP_START_TLS=true

#AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CACERTDIR=/path/
#AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CACERTFILE=/path/file.pem
#AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_CERTFILE=/path/file.pem
#AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_KEYFILE=/etc/path/file.pem

#AUTH_LDAP_GLOBAL_OPTIONS_OPT_X_TLS_REQUIRE_CERT=OPT_X_TLS_DEMAND
#Possible values for TLS_REQUIRE_CERT: OPT_X_TLS_NEVER, OPT_X_TLS_TRY, OPT_X_TLS_ALLOW, OPT_X_TLS_DEMAND

# User Canopy uses to query the LDAP server
AUTH_LDAP_BIND_DN=CN=Administrator,CN=Users,DC=example,DC=local
AUTH_LDAP_BIND_PASSWORD=password

# Recommended minimum field/attribute mapping
# Format is field1:attribute1|field2:attribute2
# For the mapping field1 -> attribute1 and field2 -> attribute2
# name:name maps the AD attribute `name` to the Canopy field `name` which is minimum recommended for Windows AD
AUTH_LDAP_USER_ATTR_MAP=name:name

# Subtree to search for users and query to use. Canopy uses email addresses as usernames by default
AUTH_LDAP_USER_SEARCH_DN=CN=Canopy Users,DC=example,DC=local
AUTH_LDAP_USER_SEARCH_FILTER=(&(objectClass=user)(mail=%%(user)s))

# Optional user group to Canopy role mapping
# Format is field1:DN1|field2:DN2
# For the mapping field1 -> DN1 and field2 -> DN2
AUTH_LDAP_USER_FLAGS_BY_GROUP=is_admin:CN=Admins,CN=Canopy Users,DC=example,DC=local|is_technical_managers:CN=Technical Managers,CN=Canopy Users,DC=example,DC=local|is_senior_analysts:CN=Senior Analysts,CN=Canopy Users,DC=example,DC=local|is_analysts:CN=Analysts,CN=Canopy Users,DC=example,DC=local|is_schedulers:CN=Schedulers,CN=Canopy Users,DC=example,DC=local|is_sales_managers:CN=Sales Managers,CN=Canopy Users,DC=example,DC=local|is_account_managers:CN=Account Managers,CN=Canopy Users,DC=example,DC=local|is_custom_pr_reviewers:CN=PR Reviewers,CN=Canopy Users,DC=example,DC=local|is_custom_qa_reviewers:CN=QA Reviewers,CN=Canopy Users,DC=example,DC=local
# Subtree to search for user groups used in AUTH_LDAP_USER_FLAGS_BY_GROUP
AUTH_LDAP_GROUP_SEARCH_DN=CN=Canopy Users,DC=example,DC=local