Active Directory (AD) and LDAP authentication

Introduction

IriusRisk is able to integrate with a corporate Active Directory (AD) / LDAP for authentication and authorization. The authentication is performed by challenging the user to authenticate against the AD / LDAP service. The authorization is then performed by retrieving the groups the user belongs to and mapping them onto IriusRisk permissions.

For example, if we have an LDAP with the following data: 

• All the users with their roles
  

# user1, Employees, cs-ldap.com dn: CN=user1,OU=Employees,DC=cs-ldap,DC=com memberOf: CN=ROLE_ADMIN,CN=Users,DC=cs-ldap,DC=com # user2, Employees, cs-ldap.com dn: CN=user2,OU=Employees,DC=cs-ldap,DC=com memberOf: CN=ROLE_DEVELOPER,CN=Users,DC=cs-ldap,DC=com # user3, Employees, cs-ldap.com dn: CN=user3,OU=Employees,DC=cs-ldap,DC=com memberOf: CN=ROLE_DEVELOPER,CN=Users,DC=cs-ldap,DC=com # user4, Employees, cs-ldap.com dn: CN=user4,OU=Employees,DC=cs-ldap,DC=com

• All the attributes used by Irius to Authenticate a user for all the users

# user1, Employees, cs-ldap.com dn: CN=user1,OU=Employees,DC=cs-ldap,DC=com sn: lastname1 givenName: firstname1 memberOf: CN=ROLE_ADMIN,CN=Users,DC=cs-ldap,DC=com mail: user1@example.com # user2, Employees, cs-ldap.com dn: CN=user2,OU=Employees,DC=cs-ldap,DC=com sn: lastname2 givenName: user2 memberOf: CN=ROLE_DEVELOPER,CN=Users,DC=cs-ldap,DC=com mail: user2@cs.com # user3, Employees, cs-ldap.com dn: CN=user3,OU=Employees,DC=cs-ldap,DC=com sn: lastname3 givenName: user3 memberOf: CN=ROLE_DEVELOPER,CN=Users,DC=cs-ldap,DC=com mail: user3@cs.com # user4, Employees, cs-ldap.com dn: CN=user4,OU=Employees,DC=cs-ldap,DC=com sn: user4 lastname givenName: user4 mail: user4@cs.com

The available roles in IriusRisk are listed below.  

• ROLE_TEST_ONLY
• ROLE_ADMIN
• ROLE_PORTFOLIO_VIEW
• ROLE_DEVELOPER
• ROLE_FULL_ACCESS_USER
• ROLE_MANAGE_USERS_BU
• ROLE_RISK_MANAGER
• ROLE_RULES_EDITOR
• ROLE_TEMPLATE_EDITOR
• ROLE_REQUIREMENTS_MANAGE
• ROLE_TESTER
• ROLE_QUESTIONNAIRE_ONLY
• ROLE_LIBRARY_EDITOR

To map the LDAP groups to the IriusRisk groups you have three options available:

NOTE: When configuring the LDAP groups within AD please ensure the case sensitivity aligns with what is set in the configuration file as this will cause the role bindings to fail.

1. Create the groups mentioned above on the LDAP server.
   

2. Change the names of the ROLES in IriusRisk to match those already created on the LDAP server. For example, if you already have a user group DEVS on LDAP and you want to map those users to the ROLE_DEVELOPER group in IriusRisk you would just have to change the name in IriusRisk from ROLE_DEVELOPER to DEVS and those users would be automatically assigned these role when they log into IriusRisk.

3. Create a complete new set of ROLES in IriusRisk that matches your current LDAP configuration for groups and individually assign to them the required permissions. The ROLE names you set up inside IriusRisk must be the same as those on your LDAP server. 

4. Use LDAP for authentication and IriusRisk for authorization: You can use LDAP to authenticate your users without considering the groups they belong to by setting up the new set of roles in IriusRisk and manually assign them to the users. See the configuration section below. 

Option #1 requires LDAP server configuration, options #2 and #3 can be done by just configuring IriusRisk properly if the LDAP server has a reasonable authorization scheme regarding groups.

Configuration

To enable AD / LDAP integration, you need to specify a configuration file. This file is read from the path indicated by the property "ldap.config.path". This property must be passed to the start up process (i.e. through the catalina.properties file on Tomcat).

#Example of passing the property through catalina.properties: 
$ cat /usr/local/tomcat/conf/catalina.properties 
#[...] 
ldap.config.path=/etc/irius/LDAP-config.groovy 
#[...]

This file should contain the following configuration sections, (see the comments on the file): 

// Change the value to true to let the system authenticate with AD/LDAP or false to use the local database
grails.plugin.springsecurity.ldap.active = true 
if (grails.plugin.springsecurity.ldap.active) { 
grails.plugin.springsecurity.providerNames = ['ldapAuthProvider']
} else { 
grails.plugin.springsecurity.providerNames = ['daoAuthenticationProvider'] 
} 

// DN to authenticate with 
grails.plugin.springsecurity.ldap.context.managerDn = 'cn=ldapbinduser,cn=Users,DC=cs-ldap,DC=com' 

// Password to authenticate with 
grails.plugin.springsecurity.ldap.context.managerPassword = 'password' 

// Address of the LDAP server 
grails.plugin.springsecurity.ldap.context.server = 'ldap://ldap_server_ip_or_name:389/' 

// The base DN from which the search for group membership should be performed 
grails.plugin.springsecurity.ldap.authorities.groupSearchBase = 'CN=Users,DC=cs-ldap,DC=com' 

// The pattern to be used for the user search. {0} is the user's DN 
grails.plugin.springsecurity.ldap.authorities.groupSearchFilter = 'member={0}' 

// Mapping User fields to ldap fields e.g . [firstName:givenName] ,firstName is the user field , do not change , givenName is ldap field 
grails.plugin.springsecurity.ldap.fields.mapping = [firstName: 'givenName', lastName: 'sn', email: 'mail'] 

// Context name to search in, relative to the base of the configured ContextSource, e.g. 'ou=users,dc=example,dc=com' 
grails.plugin.springsecurity.ldap.search.base = 'OU=Employees,DC=cs-ldap,DC=com' 

// The filter expression used in the user search 
grails.plugin.springsecurity.ldap.search.filter = 'sAMAccountName={0}' 

// Defines which permission system to use: 'ldap' (LDAP server) or 'iriusrisk'(database)
grails.plugin.springsecurity.ldap.authorities.source = 'ldap'
 
if ('iriusrisk' == grails.plugin.springsecurity.ldap.authorities.source) {
 // If 'iriusrisk' option is selected, please disable retrieveGroupRoles option (enabled by default)
 grails.plugin.springsecurity.ldap.authorities.retrieveGroupRoles = false
 
 // Set default admin user. The value must be a valid username or email
 // This is only used when property ldap.authorities.source is set to 'iriusrisk'
 grails.plugin.springsecurity.ldap.authorities.adminUser = 'ldapbinduser'
 
 // An optional default role to be assigned to all users
 // Used when we create a new user through API or when a new user do login with LDAP and IRIUS management the roles in the system
 grails.plugin.springsecurity.ldap.authorities.defaultRole = 'ROLE_PORTFOLIO_VIEW'
 
}else if ('ldap' == grails.plugin.springsecurity.ldap.authorities.source){
 // If you want to set an extra default role for all your user in LDAP, you must set up a role in this property. If you don't want a default role don't set this property.
 //grails.plugin.springsecurity.ldap.authorities.defaultRole = 'ROLE_PORTFOLIO_VIEW'
}

(NOTE: Under the section: // Address of the LDAP server, you might have to use port 3268, this change was noticed in an upgrade from tomcat 8 on IriusRisk v3 to tomcat 9 IriusRisk v4).

To enable ldap via SSL, the value of the property grails.plugin.springsecurity.ldap.context.server has to start with ldaps instead of ldap. Also, a certificate for the LDAP has to be generated. Then, the public key of that certificate has to be added to the java keystore. This can be done with Portecle, which has a GUI (https://sourceforge.net/projects/portecle/) or with the built-in command keytool:

First, check if the java keystore has a certificate for ldap with the following command, and check if there is any entry for LDAP:
keytool -v -list -keystore ../java/8u131-zulu/jre/lib/security/cacerts

After that, import the generated public key of the certificate to the java keystore:
keytool -importcert -file certificate.cer -keystore ../java/8u131-zulu/jre/lib/security/cacerts -alias "LDAP"

Docker based deployments

LDAP.config file mapping 

When using docker it is advisable to map the LDAP.config file from an external source so it will not be overridden on each container recreation, to do this you have perform the following steps:

 1. Open your terminal in the directory where you have the IriusRisk docker-compose.yml file.

 2. Copy the catalina.properties from the tomcat container to your docker host. You must have the container running in order to extract it. You can do so with this command (with the final dot also)

docker cp iriusrisk-tomcat:/usr/local/tomcat/conf/catalina.properties .

 3. Add the "ldap.config.path=/etc/irius/LDAP-config.groovy" to the end of the catalina.propertiesfileyou you have in your docker host

 4. Create the "LDAP-config.groovy" in that same folder with the configuration you will use for your deployment.

 5. Add to your docker-compose.yml the volume mappings in the iriusrisk-tomcat section (at the same indentation as the "image" section) like this:

     volumes:

      - "./catalina.properties/:/usr/local/tomcat/conf/catalina.properties"
      - "./LDAP-config.groovy:/etc/irius/LDAP-config.groovy"

 6. Restart your stack with:

     docker-compose down && docker-compose up -d

     If everything is correctly configured you will be able to authenticate with your LDAP users.

 7. To check if everything is done correctly, you can check the logs with this command:

    docker logs -f iriusrisk-tomcat

 8. If you need SSL for LDAP, follow the instructions below.

LDAP over TLS configuration

If the desired architecture requires docker, the public key has to be added to a user-defined keystore in order to overwrite the empty keystore that tomcat generates in /usr/local/tomcat/conf/default.keystore. This can be done by setting the following environment variables in the docker-compose.yml file:

tomcat8:
# ...
environment:
- TOMCAT_KEYSTORE_PATH=<PATH_TO_KEYSTORE> # e.g. /etc/irius/new.keystore
- TOMCAT_KEYSTORE_PASSWORD=newpassword

We'll also need to map a local volume as /etc/irius/ new.keystore won't exist on the container and is needed: 
(i.e.)
[...]
volumes:
- ./irius/:/etc/irius/
[...]

LDAP user attributes

All LDAP users who want to login to IriusRisk must have the next attributes set:

• givenName: First Name

• sn: Last Name

• mail: e-mail

If any of these attributes are not set the login will not succeed. The mapping can be changed with the property grails.plugin.springsecurity.ldap.fields.mapping.