Active Directory Integration

Introduction

nevisAdmin 4 supports secure authentication against LDAP servers such Active Directory. This is the recommended setup for enterprises that want to control access to nevisAdmin 4 in a centralized fashion.

When Active Directory Integration is configured, nevisAdmin 4 creates users in its database as soon as they log in. During the login process, nevisAdmin 4 also updates the user's group memberships within the database.

The main steps to integrate Active Directory are as follows:

1. Define groups and their permissions within nevisAdmin 4. This is covered in Managing Users and Groups via REST.
2. Follow the steps further below to configure the Active Directory, including the user selection criteria (base DN and filter query).
3. In the Active Directory, configure your users to match the criteria you defined in the previous step. Put the users into the groups (DNs) configured in the first step.

How to Change the Configuration

The settings below are configured in /var/opt/nevisadmin4/conf/nevisadmin4.yml.

Restart nevisAdmin 4 after making changes to the .yml (YAML) file:

nevisadmin4 stopService
nevisadmin4 startService

Enable LDAP Authentication

After the installation of nevisAdmin 4, local authentication is enabled by default, using the users and credentials that are stored in the database.

To additionally query LDAP during the login process, set the following property:

### Authentication Realms
authentication:
  realm:
#    ...
    ldap:
      enabled: true

You can disable local authentication by setting authentication.realm.local.enabled to false. This means that only Active Directory users can log in. Because the default admin user is local, this account will be disabled as well. To give LDAP users global administration permissions, see Users and Groups.

Authentication

To enable authentication against an Active Directory instance, set the LDAP(s) connection URL. In case of LDAPS, also set the truststore attributes. These properties can be found in the default configuration file /var/opt/nevisadmin4/conf/nevisadmin4.yml:

### Authentication Realms
authentication:
#  ...
### LDAP
  ldap:
    context:
      url: ldaps://ldap.siven.ch:636
      principal-suffix: "@siven.ch"
    truststore: /var/opt/nevisadmin4/keys/cacerts.jks
    truststore-passphrase: truststorePassword
    truststore-type: pkcs12

Note that the LDAP properties are part of the authentication property block. Therefore make sure that authentication (a few lines above) is uncommented.

Synchronization During Login

In addition to the actual authentication against Active Directory, you can enable automated synchronization of user attributes and groups. Based on the provided search configuration, nevisAdmin 4 then extracts the following user attributes during login:

• memberOf
• givenname
• sn
• mail

The memberOf entries are mapped against the ldap-DNs list configured for existing nevisAdmin 4 user groups. See Managing Users and Groups via REST for instructions on how to configure groups and permissions. The matching groups are stored in the nevisAdmin 4 database, in addition to the following user properties:

• given name
• family name
• email

To enable this synchronization, configure the following additional LDAP properties:

### Authentication Realms
authentication:
#  ...
### LDAP
  ldap:
    context:
#     ...
      system-user-name: systemUserName
      system-user-password: systemUserPassword
#     ...
    search:
      base-dn: dc=siven,dc=ch
      filter: (&(objectClass=*)(userPrincipalName={0}))
#   ...

If you have to map the user properties to different LDAP attribute names, check the detailed description of the properties in the table Supported LDAP properties below.

Troubleshooting

To debug your LDAP setup, perform the next steps:

1. Add the lines from the next code block to the logback.xml file. You will find this file here: /var/opt/nevisadmin4/conf/logback.xml

<logger name="org.apache.shiro" level="debug" additivity="false">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
</logger>
<logger name="ch.nevis.admin.v4.infra.shiro.jwt.realm.ldap" level="debug" additivity="false">
        <appender-ref ref="STDOUT" />
        <appender-ref ref="FILE" />
</logger>

2. Configuration is automatically synchronized every 5 seconds.
3. Try to log in with an LDAP account.
4. Check the nevisAdmin 4 log file, which you find here: /var/opt/nevisadmin4/logs/nevisadmin4.log

Supported LDAP Properties

Property Name	Default	Description
authentication.ldap.context.url	-	The LDAP / LDAPS URL used to connect to the Active Directory instance.
authentication.ldap.search.base-dn	-	The base distinguished name (DN) from which the directory search starts. Mandatory for the synchronization of user attributes and group assignments with LDAP.
authentication.ldap.search.filter	-	The LDAP search filter expression {0} is being replaced with the encoded user ID. Occurrences of {1} are replaced with the username only (without domain). Mandatory for the synchronization of user attributes and group assignments with LDAP.
authentication.ldap.context.principal-suffix	-	Appended to the user ID, to simplify the logon information that users must use to log in. If not set, AD requires a user ID fully qualified with domain information. Note: Also appended to the system username.
authentication.ldap.truststore	JRE cacert	The path to the truststore that contains the CA certificate for the LDAPS connection.
authentication.ldap.truststore-passphrase	-	The truststore password. To avoid having a plain text password in this file, set the environment variable AUTHENTICATION_LDAP_TRUSTSTORE_PASSPHRASE instead.
authentication.ldap.truststore-type	pkcs12	The type of truststore.
authentication.ldap.context.system-user-name	-	Sets the LDAP system user name. Only needed if groups have to be retrieved from the Active Directory.
authentication.ldap.context.system-user-password	-	Sets the LDAP system user password. Only needed if groups have to be retrieved from the Active Directory.To avoid having a plain text password in this file, set the environment variable AUTHENTICATION_LDAP_CONTEXT_SYSTEM_USER_PASSWORD instead.
authentication.ldap.user.dn.template	{0}	The LDAP query string that is used for the authentication request to the LDAP server, with the place holder {0} for the user ID. For example: uid={0},ou=people,o=siven,c=ch You normally do not need to set this property if you use Active Directory.
authentication.ldap.attribute.givenname	givenname	Maps the given name user property to a different LDAP attribute name.
authentication.ldap.attribute.familyname	sn	Maps the family name user property to a different LDAP attribute name.
authentication.ldap.attribute.email	mail	Maps the email user property to a different LDAP attribute name.
authentication.ldap.attribute.groups	memberOf	Maps the groups to which a user belongs to a different LDAP attribute.
authentication.ldapMulti.{connectionName}.*		Configures the above listed properties (except the truststore properties), for each additional LDAP connection.

Connecting to other LDAP Systems

Nevis does not test the integration with LDAP systems other than Active Directory. For this reason, we recommend connecting to Active Directory whenever possible. It is possible to use an OpenLDAP instance instead of Active Directory. Synchronization of user attributes with different attribute names is supported using the authentication.ldap.attribute.* properties above.

A sample configuration follows below, using ldap instead of ldaps:

authentication:
  realm:
    local:
      enabled: true
    ldap:
      enabled: true
  ldap:
    user:
      dn:
        template: uid={0},ou=people,o=siven,c=ch
    context:
      url: ldap://ldap.example.com:389
      system-user-name: cn=systemusername,dc=siven,dc=ch
      system-user-password: systemUserPassword
    search:
      base-dn: dc=siven,dc=ch
      filter: (&(objectClass=person)(uid={0}))
    attribute:
      givenname: givenName
      groups: memberOf

Connecting to multiple LDAP Systems

nevisAdmin4 supports the use of multiple LDAP connections. You have to configure these additional connections in the ldapMulti property block. You can use the same properties as described in the above table Supported LDAP properties for the ldap property block, except for the truststore.* properties.

All configured LDAP connections use the same truststore. This means that the truststore property and the related properties truststore-passphrase and truststore-type can only be set in the ldap property block.

The following code block shows a sample configuration with two additional LDAP connections:

### Authentication Realms
authentication:
#  ...
### LDAP
  ldap:
    context:
      url: ldaps://ldap.siven.ch:636
      principal-suffix: "@siven.ch"
    truststore: /var/opt/nevisadmin4/keys/cacerts.jks
    truststore-passphrase: truststorePassword
    truststore-type: pkcs12
  ldapMulti:
    exampleConnectionName:
      context:
        url: ldaps://ldap.example.ch:636
        principal-suffix: "@example.ch"
    anotherConnectionName:
      context:
        url: ldaps://ldap.another.ch:636
        principal-suffix: "@another.ch"