SSO/LDAP Integration

A Contour node can either keep its own user database or it can connect using the LDAP protocol to an external user directory such as Active Directory. This guide describes how to configure it.

Basics

To enable connecting to an LDAP directory, open the application.properties file and set the following properties:

# Select one of the options
contour.auth.mode=OPENLDAP <or> ACTIVE_DIRECTORY
# The URL for the host. Use ldaps if connecting with TLS. Note the URL should also contain the root entity DN at the end
contour.auth.ldap.host=ldap://directoryserver.com:389/dc=root
contour.auth.ldap.principal=
contour.auth.ldap.password=

Contour will use the directory server to check user authentication and query which groups the user belongs to. Based on the LDAP groups, users will be assigned to Contour roles which specify which actions the user can take. Contour roles are stored inside the Contour’s database and can be edited using the UI or API. Each role has the attribute LDAP-Group which corresponds to the LDAP group name (not the full DN).

For LDAP standards mode

If not connecting to Microsoft Active Directory and using a LDAP compliant server, set below options. Compared with Contour V7, please note the open-ldap parameters change in Contour V8:

# User Search Base
#    Required
#    The base of the DN for user search, omit the partition suffix
#    Example:
#       Given a user's DN: cn=maker,ou=people,dc=contour,dc=network
#       For host without partition: 
#           ou=people,dc=contour,dc=network
#       For host with dc=contour,dc=network partition: 
#           ou=people
contour.auth.ldap.user-search-base=ou=people

#########################
# OpenLDAP
#########################
# User DN Patterns
#   Required
#   If pattern search is not desired, please use the same value as `contour.auth.ldap.user-search-base`
#   For pattern searching, e.g. matching username with the `cn`, {0} will be substituted with the login username
#   e.g.: `cn={0},ou=people`
#   Can separate multiple patterns with |
contour.auth.ldap.open-ldap.userDNPatterns=ou=people

# User Search Filter
#   Optional
#   Determines which attributes to search for and match the user
#   e.g.: `(&(objectClass=person)(mail={0}))` 
#       This will match an entry which is a person, 
#       with `mail` having the value of the login username.
#       This effectively means logging in with email  
contour.auth.ldap.open-ldap.user-search-filter=(&(objectClass=person)(mail={0}))

# Group Search Base
#   Required
#   Where to search for groups. Note that search is not recursive but only one level
#   e.g.:
#       Given this group DN: cn=makers,ou=groups,dc=contour,dc=network
#       If the host partition suffix is empty, then:
#            ou=groups,dc=contour,dc=network
#       If the host partition suffix is `dc=contour,dc=network`, then:
#            ou=groups
contour.auth.ldap.open-ldap.group-search-base=ou=groups,dc=contour,dc=network

# Group Search Filter
#   Optional
#   Normally not required to be configured, unless the groups store membership in another custom attribute. 
#   Determines how to find groups where specific user belongs.
#   {0} will be substituted with the user's DN, and {1} by the username
contour.auth.ldap.open-ldap.group-search-filter=(member={0})

# Group Name Attribute
#   Optional
#   Determines which *attribute* of group is taken as name
#   This name is used for mapping to [UserRole.ldapGroup]
#   E.g.:
#       Given this group entry:
#           dn: cn=makers,ou=groups,dc=contour,dc=network
#           cn: TheMakers
#       The configuration value of `cn` would extract the attribute value `TheMakers`.
#       This would map the members of the group to have all UserRole where `ldapGroup` = 'TheMakers'
contour.auth.ldap.open-ldap.group-name-attr=cn

For Active Directory mode

# required
contour.auth.ldap.ad.domain=bigbank.com
# optional; can specify root entry on top of which all searches will happen
contour.auth.ldap.ad.rootDn=
# optional; the search expression used to find user. {1} will be replaced with username
contour.auth.ldap.ad.userSearchFilter=(&(objectClass=user)(cn={1}))