Iuclid Saml Sso Configuration For Azure Ad en
Iuclid Saml Sso Configuration For Azure Ad en
Legal Notice
The information in this document does not constitute legal advice. Usage of the information
remains under the sole responsibility of the user. The European Chemicals Agency does not
accept any liability with regard to the use that may be made of the information contained in this
document.
Title: IUCLID Configuration for SAML-Based SSO with Azure Active Directory
Issue date: August 2023
Language: en
IUCLID 6 is developed by the European Chemicals Agency in association with the OECD.
© European Chemicals Agency, 2023
Reproduction is authorised provided the source is fully acknowledged in the form
“Source: European Chemicals Agency, http://echa.europa.eu/”, and provided written notification is
given to the ECHA Communication Unit ([email protected]).
If you have questions or comments in relation to this document, please send them to ECHA via the
information request form at the address below, quoting the reference and issue date given above:
https://echa.europa.eu/contact
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory ii
Date Modification
23/08/2023 Chapter 4.3: updated the configuration to enable SSO in IUCLID
moving specific parameters from <jvm-options> to <system-property>
01/11/2022 Removed ending slash from the values of Identifier (Entity ID) and
Reply URL
Added extra configuration step to make sure Reply and Assertion are
both signed.
Added Sign-on URL config option to support IUCLID access through
MS application directory.
26/04/2022 First public release.
12/01/2022 First version.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory iii
Table of Contents
Changes to this document ....................................................................................................ii
Table of Contents ..................................................................................................................iii
Table of Figures .....................................................................................................................iii
1. Introduction ......................................................................................................................1
1.1. About SAML ................................................................................................................. 1
1.2. Mapping Azure Active Directory user data to IUCLID user data....................................... 2
2. Prerequisites ....................................................................................................................3
3. Configuring Azure Active Directory ..............................................................................4
3.1. Add the IUCLID application to the Azure AD tenant ........................................................ 4
3.2. Set up SAML-based SSO for IUCLID in the Azure AD tenant.......................................... 6
3.3. Collect information needed to configure SSO in IUCLID ................................................. 8
3.4. Create a group that represents access permission to IUCLID ......................................... 9
3.5. Create groups in Azure AD that map to IUCLID Roles and IUCLID Security Groups ...... 10
3.6. Assign users/groups in Azure AD to the IUCLID application .......................................... 11
4. Configuring IUCLID .......................................................................................................14
4.1. Configure public certificate of the external IDP ............................................................. 14
4.2. Configure user data synchronization from IDP to IUCLID.............................................. 14
4.3. Enable SSO in IUCLID ................................................................................................ 17
Appendix A. Example of the file idp-user-sync-config.yml ....................................19
Appendix B. Documentation of the file idp-user-sync-config.yml ........................21
Table of Figures
Figure 1: The protocol for Identity Provider (IDP) and Service Provider in Single Sign On (SSO). 1
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 1 | 24
1. Introduction
The purpose of this document is to provide instructions regarding the configuration of the IUCLID
application, for SAML-based Single Sign On (SSO) with Azure Active Directory acting as an
external identity provider (IDP).
A successful integration of IUCLID with an external identity provider via SSO requires the
collaboration between business and IT units of your organisation. They should work together to
review existing authorisation policies both at organisation level and at IUCLID level. These policies
should be reviewed to capture a streamlined configuration that’s reflects the desired access to data
and actions in IUCLID.
Figure 1: The protocol for Identity Provider (IDP) and Service Provider in Single Sign On (SSO)
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 2 | 24
Note: In this document the IUCLID application acts as the SAML service provider (above right),
and Azure Active Directory has the role of the SAML identity provider (above left). The client in the
middle of the above diagram is the user acting from a web browser.
The SAML standard defines a set of XML-based messages for security assertions:
• SAML Request, example fields: ID, Issuer, Assertion consumer URL
• SAML Response, example fields: ID, Issuer, In response to (ID), Recipient, Subject
The SAML messages are signed and potentially encrypted.
1.2. Mapping Azure Active Directory user data to IUCLID user data
The authentication and authorisation setup of IUCLID is built upon 4 main concepts:
• Legal entities: Several legal entities can be assigned to a user, however, when logged in,
only one legal entity can be the user’s working legal entity. This working legal entity is
passed to the entities the user creates, e.g. substances, mixtures.
• Roles: Each role includes a set of permissions that determine the actions users can
perform (read, write, delete) with each type of entity (substance, mixtures, dossiers, etc.) or
inventory (reference substances, legal entities, etc.). Special permissions are included for
general operations (print, export, import) and for system administration.
• Security groups: If Instance Based Security (IBS) is enabled, access is defined per
individual entity, and can also be limited to the users belonging to certain security groups.
• Users: Per user, IUCLID stores the basic user information (username, first name, last
name, etc.), and also the legal entities, roles, and security groups assigned to the user.
For more information about these concepts, refer to the document: Functionalities of IUCLID in the
web interface.
The maintenance of user information can be delegated from IUCLID to an external identity provider
(IDP), like Azure Active Directory, that supports Single Sign On (SSO) using the SAML standard.
Thus, a centralised system can hold the user information, including the password. However, the
data objects that will be assigned to users must first exist in IUCLID, e.g. IUCLID Roles, IUCLID
Security Groups, and IUCLID Legal entities.
The main objects which need to be managed in Azure Active Directory are:
• Users: The user object contains information about the individual including password and
logon credentials.
• Groups: Groups are primarily used for the purpose of managing and securing groups of
users. Groups can also be used for representing different access rights of users in different
systems of an organization.
Users are created in Azure Active Directory (AD) and they are assigned to different Azure AD
Groups. An Azure AD user will correspond to a IUCLID user.
During configuring SSO in IUCLID it is possible to do the following mappings:
• Azure AD Groups -> IUCLID Roles
• Azure AD Groups -> IUCLID Security Groups (only if IBS is enabled in IUCLID)
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 3 | 24
Different strategies can be applied when defining Azure AD Groups and IUCLID Roles/Security
Groups/Legal Entities:
• One-to-one mapping: One Azure AD Group can correspond to a single IUCLID
Role/Security Group/Legal Entity
• One-to-many mapping: One Azure AD Group can correspond to multiple IUCLID
Roles/Security Groups/Legal Entities
• Combination of the above
After a successful authentication with a 3rd party SAML IDP provider, the IUCLID application
updates the user information in its local database, and assigns the user to the relevant IUCLID
Roles, IUCLID Security Groups, and IUCLID Legal entities.
2. Prerequisites
IUCLID 6 v6 is installed successfully. If you want to define IUCLID security groups in your SSO
configuration Instance Based Security needs to be manually enabled during the installation
process. See Installation and Update Instructions for IUCLID6 Server for details.
Azure Active Directory is available.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 4 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 5 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 6 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 7 | 24
o user.userprincipalname
o user.groups [SecurityGroup]
• Use user.userprincipalname as the Unique User Identifier
• Add the security groups to User Attributes & Claims
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 8 | 24
Make a record of the values of the following parameters, for later use:
• Login URL
• Azure AD Identifier
• Logout URL
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 9 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 10 | 24
3.5. Create groups in Azure AD that map to IUCLID Roles and IUCLID
Security Groups
Create Azure AD security groups that will be mapped to IUCLID Roles and IUCLID Security
Groups in the IUCLID application. For example, an Azure AD security group that can be mapped to
the IUCLID Role, Full Access.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 11 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 12 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 13 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 14 | 24
4. Configuring IUCLID
The configuration files referred to in this section are in the IUCLID installation at:
<iuclid6-installation-
folder>\glassfish4\glassfish\domains\domain1\config\
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 15 | 24
1. Specifies how to read the SAML XML attributes in the response that is returned from IDP
after a successful authentication. This is required to perform synchronization of user-data
and to validate access, e.g.:
a. A single IDP group or role indicating access permission to this specific IUCLID
instance;
b. User account data that is saved to the IUCLID database: username, first name, last
name, email;
c. List of mappings of groups in IDP, to Roles in IUCLID. This is used to assign
IUCLID roles to the authenticated username;
d. List of mappings of groups in IDP, to security groups in IUCLID. This is used to
assign IUCLID security groups to the authenticated username. This setting is
optional and is relevant only if Instance Based Security (IBS) is enabled in IUCLID;
e. List of mappings of groups in IDP, to Legal entities in IUCLID. This is used to assign
IUCLID Legal entities to the authenticated username. This setting is optional
2. Defines SAML specific configuration parameters:
a. The URL of the external SAML provider;
b. The path to the keystore file where the IDP’s SAML signing certificate is stored;
c. The alias of the IDP’s SAML signing certificate provided when adding it in the
keystore;
d. The alias of IUCLID’s SAML request signing certificate;
e. The password of IUCLID’s SAML request signing certificate;
f. The URL that will be used when performing log-out.
The image below is a screenshot from a text editor showing an example of the configuration file
idp-user-sync-config.yml
It shows the first part of the file, which contains the configuration of how to read the attributes from
the SAML response XML, based on the values in Azure AD, such as group object IDs, and the
settings under Single Sign-On with SAML > User Attributes & Claims.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 16 | 24
In the lower part of the file, configuration parameters specific to SAML are defined.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 17 | 24
Example:
…
<system-property name="iuclid6.admin.user.create" value="false"></system-
property>
<system-property name="iuclid6.admin.user.assignToRole"
value="false"></system-property>
<system-property name="iuclid6.admin.user.assignToGroup"
value="false"></system-property>
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 18 | 24
<system-property name="idp.sso.config"
value="${com.sun.aas.instanceRoot}/config/idp-user-sync-config.yml"></system-
property>
After doing the above steps restart the IUCLID application for the changes to take effect.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 19 | 24
# Configure the IDP Group that represent access to this IUCLID instance.
# In this example 430d72f5-b91d-4902-9f2b-6ce0e54cce40 is the ID of the Group from Azure AD
that is named My_IUCLID_App_Access.
instanceAccess:
samlAttributeName:
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
samlAttributeValue: 430d72f5-b91d-4902-9f2b-6ce0e54cce40
# Configure the SAML attribute that holds the user-name value
userUserName:
samlAttributeName: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
# Configure the SAML attribute that holds the user's first name value
userFirstName:
samlAttributeName:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
# Configure the SAML attribute that holds the user's last name value
userLastName:
samlAttributeName:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
# Configure the SAML attribute that holds the user's email-address value
userEmail:
samlAttributeName:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
# Configure the SAML attribute that holds the list of values that could be mapped to IUCLID Roles. Specify
the one-to-one mappings.
# In this example 4916feac-40d1-4c9d-86ab-63da999d1348 is the ID of the Group from Azure AD
that is named IUCLID6_Full_Access. It is configured to map to a IUCLID Role named Full access.
roles:
samlAttributeName:
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
mappings:
- samlAttributeValue: 4916feac-40d1-4c9d-86ab-63da999d1348
iuclidValue: Full access
- samlAttributeValue: eaf45536-6667-468c-adec-40af5b193291
iuclidValue: Test role
# Configure the SAML attribute that holds the list of values that could be mapped to IUCLID Legal Entities.
Specify the one-to-one mappings and provide fallback values.
# In this example ef469666-9752-4459-8dab-0bebe70b2f74 is the ID of the Group from Azure AD
that is named Test Group for a IUCLID LE. It is configured to map to a IUCLID Legal Entity named
Test Legal Entity. If no corresponding IUCLID Legal entity is found then the user will be assigned to a
default/fallback Legal entity, named My LE.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 20 | 24
legalEntities:
samlAttributeName:
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
mappings:
- samlAttributeValue: ef469666-9752-4459-8dab-0bebe70b2f74
iuclidValue: Test Legal Entity
fallbacks:
- My LE
# Configure the SAML attribute that holds the list of values that could be mapped to IUCLID Security
Groups. Specify the one-to-one mappings and provide fallback values.
# In this example b97cc4dc-8d5d-425d-8ddd-c3763970a935 is the ID of the Group named Test
Group for a IUCLID Group which comes from Azure AD. It is configured to map to a IUCLID Security
group named Test group. If no corresponding IUCLID Security group is found then the user will be
assigned to a default/fallback group, named Common.
groups:
samlAttributeName:
http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
mappings:
- samlAttributeValue: b97cc4dc-8d5d-425d-8ddd-c3763970a935
iuclidValue: Test group
manager: true
fallbacks:
- Common
# Configure the URL of the SAML IDP provider
# In this example it is the value of the Login URL as specified in Azure AD under SAML based SSO
settings
idp.saml.provider.url: https://login.microsoftonline.com/26f31e25-c550-40cc-
8af6-449e72b90388/saml2
# Configure the alias of the 3rd party identity provider certificate you provided when adding it in the keystore
idp.certificate.alias: SamlSigningCertificate
# Configure the location of the keystore file containing the 3rd party identity provider certificate. It is
recommended to keep the below default value.
keystore.file: ${com.sun.aas.instanceRoot}/config/sso-default-third-party.jks
# Configure the keystore password. Default value is admin12345_.
keystore.pass: admin12345_
# Configure the alias of IUCLID's own certificate. It is recommended to keep the below default value.
sp.certificate.alias: sso-sp
# Configure the URL that will be used when performing log-out
slo.redirect.path: /iuclid6-web/index.html
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 21 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 22 | 24
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 23 | 24
There is one
instance of
these per
mapping.
There can be
more than one
legal entity
Defines an entry of a SAML
with the same
legalEntities.mappings.samlAttributeValue response legal entity name
name in a
/ and the corresponding
legalEntities.mappings.iuclidValue IUCLID
IUCLID legal entity to which it
database. All
will mapped.
matching legal
entities are
assigned to
the user, but
the first one is
set as working
legal entity.
iuclid_saml_sso_configuration_for_azure_ad_en.docx
IUCLID Configuration for SAML-Based SSO with Azure Active Directory Page 24 | 24
Mandatory
The password of the
(Predefined
keystore.pass certificate of the service
value:
provider.
admin12345_)
Mandatory
The alias of the certificate of
sp.certificate.alias (Default
the service provider (IUCLID)
Value: sso-sp)
iuclid_saml_sso_configuration_for_azure_ad_en.docx