Authentication

    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/configdirectory.

      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.propertiesfile.

    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 protocol. Possible values are LDAP or LDAPS. If LDAPS is used, the RegAuthLdapTrustedCertificate property has to be set.
RegAuthLdapProtocol=LDAP

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

# LDAPS server certificate to trust. When LDAPS protocol is used, the server certificate has to be provided here in PEM format. New line characters has to be replaced by '\n' strings.
RegAuthLdapTrustedCertificate=-----BEGIN CERTIFICATE-----\nMIIDdzC......\n.......\n.......\n.......\n.......\n-----END CERTIFICATE-----\n

# 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 protocol. Possible values are LDAP or LDAPS. If LDAPS is used, the RegAuthADTrustedCertificate property has to be set.
RegAuthADProtocol=LDAP

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

# LDAPS server certificate to trust. When LDAPS protocol is used, the server certificate has to be provided here in PEM format. New line characters has to be replaced by '\n' strings.
RegAuthADTrustedCertificate=-----BEGIN CERTIFICATE-----\nMIIDdzC......\n.......\n.......\n.......\n.......\n-----END CERTIFICATE-----\n

# 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

# The filter to search for the user being authenticated.
RegAuthADSearchFilter = (&(objectClass=user)(sAMAccountName={1}))
These special tokens can be used in the search filter to fill in the data that the user provides as username on the login page.
Occurrences of {0} are replaced with the username@domain. The domain comes from the RegAuthADDomain attribute.
Occurrences of {1} are replaced with the username only. That is entered as username on the login page.

Since version 20.16.0-2008281630 the default Search Filter is the following: (&(objectClass=user)(sAMAccountName={1})).
This configuration allows users to log in with using their usernames only. e.g: testuser.
However users cannot log in with their full username. e.g: testuser@company.local.
This configuration also allows users that have alternate UPN suffix set in the Active Directory system to enter.
Please find an example below this code block.

Before version 20.16.0-2008281630 the default configuration was: (&(objectClass=user)(userPrincipalName={0})).
Using this configuration allows users to log in with entering their domain ending username. e.g: testuser@company.local
However if the RegAuthADDomain is set, then users that have the default domain ending can also log in just using their usernames.
This configuration does not allow users that have alternate UPN suffix set in the Active Directory system to enter.
Please find an example below this code block.

Also when customising the Search Filter please keep in mind that Compound Registration expects only one user to be returned from the Active Directory system upon authentication. If multiple users would be returned, the login will not be allowed.

# 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

    Examples for 'The filter to search for the user being authenticated':

    Alternate UPN suffix can be set per user in Active Directory.

    In this example, testuser12 has the default system suffix, company.local, and john12 has an alternate suffix, company.com configured.

    RegAuthADSearchFilter = (&(objectClass=user)(sAMAccountName={1}))

    Login name Can log in?
    testuser12 yes
    testuser12@company.local no
    john12 yes
    john12@company.com no

    RegAuthADSearchFilter = (&(objectClass=user)(userPrincipalName={0}))

    Login name Can log in?
    testuser12 yes
    testuser12@company.local yes
    john12 no
    john12@chemaxon.com no

    Deprecated properties after version 16.07.18-795 Local and LDAP/AD settings

    
RegAuthADReadGroupFromDB=false

    SAML before version 23.14.0

    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 ( RegAuthSAMLMetadataEntityIdproperty) - 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 RegAuthSAMLKeystoreFileproperty. (you have to use “classpath:” prefix. e.g.: classpath:samlKeystore.jks)

    You can provide the necessary password and alias using the properties RegAuthSAMLKeystorePassword, RegAuthSAMLKeystoreAlias 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

    Consumer settings

    Since version 22.11.0 the expiration time of the SAML authentication statement is configurable with a new parameter: RegAuthSAMLMaxAuthenticationAge (default value is 7200 seconds).

    
RegAuthSAMLMaxAuthenticationAge - Sets the maximum time between users authentication and processing of an authentication statement in seconds

    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

# Consumer settings
RegAuthSAMLMaxAuthenticationAge=7200

    SAML after version 23.14.0

    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 RegAuthSAMLIdpMetadataURL 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 ( RegAuthSAMLMetadataEntityIdproperty) - this must be a unique name in the IDP.
    4. In your authorization provider set <scheme>://<host>:<port>/RegistryCxn/login/saml2/sso/compreg as the login URL

    When you start the Compound Registration application the SAML SP metadata is available on the URL: <HOST>/RegistryCxn/saml2/service-provider-metadata/{registrationId}(registrationId - is a fixed value, it represents the SP-IDP relation, in this case, its value is compreg). 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 RegAuthSAMLKeystoreFileproperty. (you have to use “classpath:” prefix. e.g.: classpath:samlKeystore.jks)

    You can provide the necessary password and alias using the properties RegAuthSAMLKeystorePassword, RegAuthSAMLKeystoreAlias 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:

    RegAuthSAMLMetadataWantAssertionSigned - Assertions Signed
RegAuthSAMLMetadataRequestSigned - Metadata Request 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
RegAuthSAMLIdpMetadataURL=classpath:samlIdpMetadata.xml
RegAuthSAMLMetadataEntityId=com.chemaxon.registry.RegistryService

# Signature settings
RegAuthSAMLMetadataWantAssertionSigned=true
RegAuthSAMLMetadataRequestSigned=true
# supported: Artifact, POST, PAOS
RegAuthSAMLMetadataBindingsSSO=Artifact

# 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)