Page tree

Introduction

Compound Registration supports several authentication methods:

  • Local (Database) - users are stored only in Compound Registration's own database, it doesn't require any 3rd party software.
  • LDAP - users and groups are synchronized from an external authentication provider that is maintained by another organization.
  • Active Directory - similarly to LDAP users are synchronized from an external source.
  • SAML - a Single Sign-On system that is using an XML based communication mechanism for communicating identities between organizations.

Since these authentication methods have different characteristics, the way how they are customized are different as well:

  1. SAML provides a Single Sign-On interface. In other words, users won't use Compound Registration's login page, they will log in through the identity provider's login page.
  2. Authentication providers setting are stored in registry.properties file in $REGISTRYCXN_HOME/config directory.
    1. LDAP and Active Directory configuration properties can be edited also on the Administration UI (Administration > Access Control > Authentication Providers)
    2. SAML has to be configured by editing the registry.properties file.
  3. A server restart is required for SAML property changes to take effect.

First steps

As mentioned before authentication-related properties are stored in the registry.properties file, placed at $REGISTRYCXN_HOME/config directory.

The first thing to do is to set the "Client Authentication Mode". This refers to the fact if a user logs in through Compound Registration login page or through an external one. Use the value "local" for Database, LDAP and Active Directory authentication methods.

Authentication mode configuration
# available options: local, samlsso
# default : local
RegAuthClientMode=local


The different authentication methods can be set to be enabled or disabled. Compound Registration allows using more than one authentication method simultaneously. Whenever an authentication fails, the system tries to authenticate the user against the next available authentication mode. If none of them succeed then the authentication fails, otherwise, it is successful. The following properties are responsible for enabling authentication modes:

Authentication mode configuration
# available options: true, false

# Enable Local (DB) authentication
RegAuthDBEnabled=true

# Enable LDAP authentication
RegAuthLdapEnabled=true

# Enable Active Directory authentication
RegAuthADEnabled=false

However, to have a fully functional remote authentication system, there are other options that have to be set. The sections below provide the full list of configuration properties that can be set for each authentication mode.

LDAP

Local and LDAP/AD settings
# Enable LDAP authentication
RegAuthLdapEnabled=false

# LDAP server settings
RegAuthLdapHost=ldaphost.local
RegAuthLdapPort=389

# Distinguished name for the base object from which searches for user objects are conducted
RegAuthLdapBaseDn=DC=test,DC=compary,DC=local

# The LDAP user who has rights to search the tree
RegAuthLdapSearchUserDn=uid=ADMIN,ou=User,ou=Test,dc=test,dc=company,dc=local
RegAuthLdapSearchUserPass=password

# Defines the part of the directory tree under which user searches should be performed.
RegAuthLdapUserSearchBase=cn=users,cn=accounts

# The user filter is a filter in LDAP format that allows you to select only those users under the Base DN that match certain criteria
RegAuthLdapUserSearchFilter=uid={0}

# What search to execute to find the user who wants to log in. The substituted parameter is the login name.
RegAuthLdapUserDnPattern=uid={0},ou=User,ou=Test

# Defines the part of the directory tree under which group searches should be performed.
RegAuthLdapGroupSearchBase=ou=Group,ou=Test

# The filter which is used to search for group membership. Example: uniqueMember={0}, corresponding to the groupOfUniqueMembers LDAP class. In this case, the substituted parameter is the full distinguished name of the user. The parameter {1} can be used if you want to filter on the login name.
RegAuthLdapGroupSearchFilter=memberUid={1}

# The filter which is used to list eligible users for Compound Registration
RegAuthLdapUserListFilter=uid=*

# The filter for groups that should be synchronized during synchronization of all users and groups in Compound Registration
RegAuthLdapGroupListFilter=objectclass=*

# User attributes that can be synchronized to Compound Registration
RegAuthLdapUsernameAttribute=uid
RegAuthLdapGroupAttribute=cn
RegAuthLdapEmailAttribute=mail
RegAuthLdapFullNameAttribute=cn
RegAuthLdapFirstNameAttribute=givenname
RegAuthLdapLastNameAttribute=cn

# A comma separated list of custom attributes that should be synchronized to a user
RegAuthLdapCustomAttributes=location,office

# Convert LDAP group names to uppercase
RegAuthLdapConvertGroupsUppercase=false


Deprecated properties after version 16.07.18-795

Local and LDAP/AD settings
# RegAuthLdapReadGroupFromDB controls whether the group membership configuration of the users exists within LDAP or not. If it does exist, the given group membership information is used, otherwise all the users have to be registered in the local database as well, and the corresponding group membership information configured. # As a side effect there would exist the same users defined in local database, therefore it is highly recommended to switch off the RegAuthDBEnabled setting to be able to authenticate against LDAP in these special cases.
RegAuthLdapReadGroupFromDB=false

Active Directory

Local and LDAP/AD settings
# Enable AD authentication
RegAuthADEnabled=false

# AD server settings
RegAuthADHost=10.0.0.100
RegAuthADPort=389
RegAuthADDomain=adhost.local

# Defines the common part of the directory tree as a root of all searches
RegAuthADBaseDN=dc=chemaxon;dc=local

# Defines the part of the directory tree under which user searches should be performed.
RegAuthADUserSearchBase=cn=Users

# Defines the search user
RegAuthADSearchUserDN=<userpath>
RegAuthADSearchUserPassword=<password>

# Defines the part of the directory tree under which group searches should be performed.
RegAuthADGroupSearchBase=cn=Users

# LDAP filter to apply additional filtering on the defined user search base
RegAuthADUserListFilter=uid=*

# LDAP filter for groups that should be synchronized during synchronization of all users and groups in Compound Registration.
RegAuthADGroupListFilter=objectclass=*

# User attributes that can be synchronized to Compound Registration
RegAuthADEmailAttribute=mail
RegAuthADFullNameAttribute=fullname
RegAuthADFirstNameAttribute=firstname
RegAuthADLastNameAttribute=lastname

# A comma separated list of custom attributes that should be synchronized to a user
RegAuthADCustomAttributes=location,office

Deprecated properties after version 16.07.18-795

Local and LDAP/AD settings
RegAuthADReadGroupFromDB=false

SAML

Compound Registration application can be configured as a SAML service provider.

Required settings

  1. Enable SAML authentication using the RegAuthClientMode property with value samlsso.
  2. Provide the metadata to the Compound Registration, that is configured in your IDP. This can be set using the RegAuthSAMLIdpMetadataFile property. The value can be an URL or a file that is located in the Tomcat library (in this case you have to use “classpath:” prefix. e.g.: classpath:samlIdpMetadata.xml )

  3. Provide an entity ID for the Compound Registration SP (RegAuthSAMLMetadataEntityId property) - this must be a unique name in the IDP.

When you start the Compound Registration application the SAML SP metadata is available on the URL: <HOST>/RegistryCxn/saml/metadata. In most cases, you can import this in your IDP, contains all the necessary information your IDP needs.

Keystore setup

The keystore file must be located in the Tomcat library, and it can be configured using the RegAuthSAMLKeystoreFile property. (you have to use “classpath:” prefix. e.g.: classpath:samlKeystore.jks)
You can provide the necessary password and alias using the properties RegAuthSAMLKeystorePasswordRegAuthSAMLKeystoreAlias and RegAuthSAMLKeystoreAliasPassword

Attribute map settings

You can provide mappings for the user-related attributes with the following properties:

RegAuthSAMLUserNameAttribute - username SAML assertion attribute, if this is not empty, it uses this attribute instead of the SAML NameID
RegAuthSAMLGroupAttribute - groups  SAML assertion attribute 
RegAuthSAMLRoleAttribute - roles  SAML assertion attribute 
RegAuthSAMLEmailAttribute - email  SAML assertion attribute 

Signature settings

You can set which SAML request/response should be signed using the following properties:

RegAuthSAMLMetadataSignMetadata - Metadata Response Signed
RegAuthSAMLMetadataWantAssertionSigned - Assertions Signed
RegAuthSAMLMetadataRequestSigned - Metadata Request Signed
RegAuthSAMLMetadataRequireArtifactResolveSigned - Artifact Response Signed
RegAuthSAMLMetadataRequireLogoutRequestSigned - Logout Request Signed
RegAuthSAMLMetadataRequireLogoutResponseSigned - Logout Response Signed

Example configuration

RegAuthClientMode=samlsso
#SAMLSSO authentication
# Metadata settings. For more detailed documentations check the following URL: http://docs.spring.io/spring-security-saml/docs/1.0.x/reference/htmlsingle/#configuration-metadata 
# RegAuthSAMLIdpMetadataFile=classpath:samlIdpMetadata.xml
RegAuthSAMLIdpMetadataFile= http://openam.yourhost.com:8080/oam/saml2/jsp/exportmetadata.jsp?realm=/yourcompany&entityid=yourcompanyIDP 
RegAuthSAMLMetadataEntityId=com.chemaxon.registry.RegistryService

# Signature settings
RegAuthSAMLMetadataSignMetadata=false
RegAuthSAMLMetadataWantAssertionSigned=true
RegAuthSAMLMetadataRequestSigned=true
RegAuthSAMLMetadataRequireArtifactResolveSigned=false
RegAuthSAMLMetadataRequireLogoutRequestSigned=false
RegAuthSAMLMetadataRequireLogoutResponseSigned=false
RegAuthSAMLMetadataTrustCheck=false
# supported: Artifact, POST, PAOS
RegAuthSAMLMetadataBindingsSSO=Artifact
# http://docs.spring.io/spring-security-saml/docs/1.0.x/reference/htmlsingle/#configuration-security-profiles 
RegAuthSAMLMetadataSecurityProfile=metaiop

# Keystore settings
RegAuthSAMLKeystoreFile=classpath:samlKeystore.jks
RegAuthSAMLKeystorePassword=sysger123
RegAuthSAMLKeystoreAlias=regsys
RegAuthSAMLKeystoreAliasPassword=sysger123
 
# Attribute mappings
RegAuthSAMLUserNameAttribute=uid
RegAuthSAMLGroupAttribute=memberOf
RegAuthSAMLRoleAttribute=
RegAuthSAMLEmailAttribute=mail

Advanced settings

Authentication for trusted 3rd party clients

For trusted 3rd party systems the username/password authentication can be omitted by using a symmetric key authentication. This way 3rd party systems can use our REST API with basic authentication, without the need of SAML tokens:

Step 1: Adding trusted 3rd party system to Compound Registration

This is possible by executing a command in the registration install directory: 

./bin/RegistryCxn add-secret
parameters:
  -client <arg>   The name of the client
  -secret <arg>   The symmetric authentication key

Example:

./bin/RegistryCxn add-secret -client inventory-service -secret Inventory123456P@ssw0rd

Step 2: Access Compound Registration
When accessing Compound Registration from a trusted 3rd party system, use Basic-Authentication by adding the following header entries to the registration webservice call:

  1.  "Grant-Type”: “client_credentials”
    This header tells the server, that this call should use the trusted 3rd party authentication method
  2.  “Reg-User” : <username>
    This header contains the delegated user name. It must be the username of a user that exists in Compound Registration. The service will be called with this user (logs, audit data, etc. will refer to this user)
  3. Basic auth token
    This header is a regular basic authentication token generated from the “client" and the “secret" of the trusted client you provided in the command line application when adding the trusted client. For testing purposes, generate the Basic-Auth header entry here.

Please note, login/logout service calls are not needed, as each service call will authenticate itself each time by using the Basic-Authentication header.

Example call:

This service call retrieves the compound registered with id CXN1:

URL: https://ps-reg-demo.chemaxon.com/RegistryCxn/rest/structureService/registryStructure?id=CXN1&idType=PCN&format=sdf
Method: GET
Headers:
"Grant-Type": "client_credentials"
"Reg-User": "admin"
"Authorization": "Basic Y2xpZW50OnNlY3JldA=="

CSRF protection

The application features a solution against cross-site request forgery attacks, which can be switched on/off.

CSRF setting
#CSRF protection
RegAuthCsrfProtectionEnabled=true

Deprecated settings

Authorization priority is deprecated after Compound Registration version 19.7.1.

Using RegUserRepositoryMode property, the source of roles associated with the authenticated user can be specified. (e.g. if you have a user in both SAML and local DB, upon successful SAML authentication it can keep its roles collected from SAML or it can have the roles stored in the database). Its value is a priority list. (e.g. "auth,db” value means that roles that are collected from authentication are prioritized. If no role is collected from authentication, then roles are collected from the database)