ADOIT SAML Guide

Introduction

Welcome to the ADOIT SAML Guide, your go-to resource for setting up SAML-based authentication in ADOIT to streamline authentication processes and synchronise user details.

SAML 2.0 offers a robust framework to manage authentication and authorisation within ADOIT. By leveraging SAML Identity Providers (IdP) like Microsoft Entra ID, Single Sign-On (SSO) can be implemented quickly.

Here's what you can expect from this guide:

• Introduction: Right where you are now. Get acquainted with essential terms and grasp the basics of the SAML authentication flow. Feel free to skip if you're already familiar.
• Prerequisites: Learn what you need to have in place before diving into SAML configuration.
• Configure SAML IdP: General information on the SAML IdPs that ADOIT supports and how to configure Microsoft Entra ID step by step.
• Configure ADOIT: How to adapt ADOIT to your chosen IdP.
• More: Extra resources to help you navigate authentication challenges, from handling certificate rollover to managing login name changes.

Some Terms You Should Know

Term	Acronym	Definition
Active Directory	AD	Microsoft's directory service for managing domain resources. It stores information about users, computers, and other resources within a network and allows for centralised authentication and authorisation.
Identity Provider	IdP	In the context of SAML, the Identity Provider is the entity responsible for authenticating users and providing identity information to Service Providers (SPs). It manages information about users and their authentication statuses.
Lightweight Directory Access Protocol	LDAP	LDAP is a standardised protocol used for accessing and managing directory services, such as Active Directory. It provides a way for clients to query and modify directory information over a network.
Microsoft Entra ID	ME-ID	Microsoft Entra ID is Microsoft's cloud-based identity provider service that enables organisations to manage user authentication and access to applications and services. It supports Single Sign-On (SSO) functionality and integrates with various Microsoft products and third-party applications.
Security Assertion Markup Language	SAML	SAML is an XML-based framework for exchanging authentication and authorisation data between an Identity Provider (IdP) and a Service Provider (SP). It facilitates Single Sign-On (SSO) and enables seamless access to multiple applications with a single set of login credentials.
Service Provider	SP	In SAML terminology, a Service Provider (SP) is a web application or service that delegates authentication and authorisation to an Identity Provider (IdP). It relies on the IdP to verify user identities and grant access to protected resources.
Single Sign-On	SSO	Single Sign-On (SSO) is an authentication process that allows users to access multiple applications or services with a single set of login credentials. Once authenticated, users can navigate between different applications without having to re-enter their credentials.
User Agent	UA	A User Agent (UA) is an HTTP client, typically a web browser or mobile application, that interacts with web servers to retrieve and display web content. It sends requests for resources and handles responses from servers, enabling users to browse the web and access online services.

Understanding SAML

SAML is an XML-based, open-standard data format for exchanging authentication and authorisation data between parties, in particular, between an Identity Provider (IdP) and a Service Provider (SP). An IdP is an authority that can authenticate users and has knowledge of the users' group memberships and other organisational details. The SP is the actual web application that delegates the authentication to the IdP.

The following figure illustrates the authentication process as an interaction between the User Agent (UA), the IdP and the SP.

One important feature of the SAML protocol is the fact that there is no server-to-server communication involved. The complete message flow is done via the UA by means of redirects and (possibly auto-submitted) POST requests.

Whenever a user tries to access the SP's web application without a valid session, the SP generates a SAML authentication request and redirects the UA to the IdP's URL. The authentication request is sent as an argument of the query string. The IdP may validate the origin of the authentication request by verifying that it has been signed with the SP's certificate.

The next step is the authentication of the user which can use various procedures including form-based authentication, Integrated Windows Authentication (including SSO), multi-factor authentication and others. If the authentication succeeds, the IdP assembles the authentication response containing the security assertion with the so-called claims that are used to transport information about the user. Once the UA sends this information to the SP, the response can be validated by verifying the signature. The SP can then use the information received to establish the user's session with the web application.

Prerequisites

Before you can configure ADOIT to use SAML for authentication, you need to do the following:

• Define an authorisation concept

• Obtain and Configure SSL Certificates

• Install ADOIT with SSL

• Create ADOIT User Groups

Defining an Authorisation Concept

Authorisation is the process of determining what actions or resources a user is permitted to access within a system or application. It goes hand in hand with authentication, which verifies the identity of users. While authentication confirms who the user is, authorisation determines what the user can do within the system once authenticated.

Establishing User Groups in ADOIT and IdP

An effective authorisation concept for SAML-based authentication in ADOIT requires establishing groups both within ADOIT and on the IdP side (e.g., Microsoft Entra ID).

Permissions in ADOIT: A Brief Overview

In ADOIT, access to content, such as models and objects, is typically granted through user groups rather than individual users. The group permissions are then inherited by all members of a group.

However, access to functionalities such as release workflows or report creation is controlled via system roles. By assigning system roles to user groups, the permissions tied to these roles are automatically extended to all group members.

This approach allows to manage permissions for a large number of users with little effort.

Connecting the People in your Organisation with ADOIT User Groups

Connecting the people in your organisation with ADOIT user groups can be achieved in a number of ways:

• Manual Assignment: Users can be manually assigned to ADOIT user groups via the ADOIT Administration. However, this approach can become cumbersome and error-prone, especially when dealing with a large number of users.

• IdP Integration: We recommend assigning users to ADOIT user groups via the IdP by mapping IdP groups to ADOIT user groups. When users change roles or departments, their permissions update automatically. New team members also get the right permissions instantly. This approach streamlines onboarding and reduces manual effort.

Defining Group Mapping Strategies

Two common strategies for mapping IdP groups to ADOIT user groups include:

1. Utilising Existing IdP Groups: Existing IdP groups, representing organisational units, can be mapped to corresponding ADOIT user groups. Multiple IdP groups may map to a single ADOIT user group, such as "Modellers".

2. Creating New IdP Groups: New groups can be created within the IdP and users assigned accordingly. These groups are then mapped to corresponding ADOIT groups, maintaining a one-to-one mapping between IdP groups and ADOIT user groups.

Example: Admins, Modellers, and Readers

Consider a scenario with admins, modellers, and readers using Microsoft Entra ID as the IdP:

Based on the provided groups, a mapping between the groups on both sides can be established. Once all configuration steps are completed and SAML-based authentication in ADOIT is operational, people within your organisation can log in to ADOIT with the permissions granted to the ADOIT user groups they belong to.

Ask Your Consultant

It's advisable to collaborate with an ADOIT consultant during the design and implementation of your authorisation concept. They can provide valuable insights and guidance tailored to your organisation's needs.

Obtain and Configure SSL Certificates for the IdP and SP

Depending on the IdP you use and your security needs, you will need to obtain the following certificates:

• An SSL certificate for the SP for HTTPS communication (Cert SP-HTTPS)

• An SSL certificate for the IdP for HTTPS communication (Cert IdP-HTTPS)

• An SSL certificate for the SP for signing SAML tokens (Cert SP-sig)

• An SSL certificate for the IdP for signing SAML tokens (Cert IdP-sig)

• (Optional) An SSL certificate for the SP for decrypting SAML assertions (Cert SP-decr)

SSL Certificates for HTTPS Communication

The SSL certificates for HTTPS (both Cert SP-HTTPS and Cert IdP-HTTPS) are used for browser communication and should be signed by a certificate authority (CA) trusted by the browsers.

• The Cert SP-HTTPS certificate is required when installing ADOIT with SSL, serving as the certificate for Tomcat. You need to obtain this certificate from a certificate authority.

• Whether you need to obtain and configure a Cert IdP-HTTPS certificate depends on the used IdP. For example, you do need to obtain and configure an SSL certificate for HTTPS for AD FS. However, you won't need to separately obtain and configure an SSL certificate for HTTPS for Microsoft Entra ID - it's included right out of the box.

SSL Certificates for Signing SAML Tokens

The SSL certificates for signing tokens (Cert SP-sig and Cert IdP-sig) do not need to be signed by a certificate authority, as they are used on both sides.

• For the Cert SP-sig certificate, you can use a self-signed certificate. Create a Java KeyStore using the Java keytool and export the certificate from it. This certificate will be used when you configure the SAML settings in ADOIT. Depending on the used IdP, it might require uploading this certificate. For example, AD FS requires uploading the Cert SP-sig certificate to establish trust between the IdP and the SP, while Microsoft Entra ID does not require you to manually upload it, using metadata provided by the SP to establish trust instead.

• The Cert IdP-sig certificate is a self-signed certificate generated by the IdP. You can export it from the IdP and upload it to ADOIT or provide ADOIT with the metadata URL from the IdP to retrieve details about the certificate.

SSL Certificate for Decrypting SAML Assertions

The Cert SP-decr certificate can be treated like the certificates for signing tokens, meaning it does not need to be signed by a certificate authority. This certificate can be identical to the Cert SP-sig certificate.

I am Confused - Which Certificates Do I Need to Get Now?

Here's a quick summary to clear up any confusion regarding the SSL certificates you need to obtain:

• For HTTPS Communication:

  • Cert SP-HTTPS: Required for ADOIT installation with SSL. Obtain this certificate from a certificate authority.

  • Cert IdP-HTTPS: Necessary based on your IdP. Obtain this certificate if you're using AD FS. Not needed for Microsoft Entra ID.

• For Signing SAML Tokens:

  • Cert SP-sig: Required for configuring SAML settings in ADOIT. Create a self-signed certificate using Java keytool for this purpose.

  • Cert IdP-sig: A self-signed certificate generated by the IdP. Export it from the IdP.

• For Decrypting SAML Assertions (Optional):

  • Cert SP-decr: This optional certificate can be identical to the Cert SP-sig certificate.

Example: Create Java KeyStore and Export Cert SP.sig Certificate

1. Start a Windows Command Prompt as an administrator, and then navigate to "<Java JDK installation>/bin".

2. Perform the following command to create the keystore in the \bin folder:

keytool -genkey -alias <ALIAS> -keyalg RSA -keystore <KEYSTORE_FILE_NAME>.jks -storepass <PASSWORD> -validity <VALIDITY>

• <ALIAS> is used to identify the certificate in the KeyStore
• <KEYSTORE_FILE_NAME> contains the name of the keystore file that should be created
• <PASSWORD> contains the password for accessing the keystore
• <VALIDITY> is the duration of validity in days

tip

Example: keytool -genkey -alias BOC -keyalg RSA -keystore BOC.jks -storepass <my-password> validity 365

3. Perform the following command to export the self-signed certificate to the \bin folder:

keytool -export -alias <ALIAS> -storepass <PASSWORD> -file <CERTIFICATE_FILE_NAME>.cer -keystore <KEYSTORE_FILE_NAME>.jks

tip

Example: keytool -export -alias BOC -storepass <my-password> -file BOC.cer -keystore BOC.jks

Done! You have successfully created a Java keystore and exported the Cert SP.sig certificate from it.

Install ADOIT with SSL

Install the ADOIT according to the Installation Manual. You must configure SSL/TLS support on Tomcat. As a certificate for Tomcat, the Cert SP-HTTPS certificate has to be used.

Create ADOIT User Groups

Now create the user groups required for your authorization concept in ADOIT, configure their permissions and assign system roles. If you need help with this, read Establishing User Groups in ADOIT.

Configure SAML IdP

This section covers possible SAML IdPs for ADOIT and offers a detailed tutorial specifically for Microsoft Entra ID.

Supported IdPs

ADOIT supports integration with the following IdPs:

• Microsoft Entra ID

• Microsoft Active Directory Federation Services (AD FS)

• Okta

• Shibboleth

• PingFederate

• Any other SAML 2.0-compliant IdP (prior evaluation required)

Detailed instructions for configuring Microsoft Entra ID are provided in the subsequent section. If you require instructions for configuring AD FS, please reach out to your ADOIT consultant. For assistance with configuring another IdP, refer to your IdP's documentation.

Configure Microsoft Entra ID

This section provides a detailed guide on configuring Microsoft Entra ID as the IdP for ADOIT. Follow the steps below to integrate ADOIT, whether it's a SaaS solution or deployed on-premise, with Microsoft Entra ID.

Sign in to the Microsoft Entra Admin Center

To get started, sign in to the Microsoft Entra admin center with your administrator account.

Create Microsoft Entra Groups and Assign Users

If your authorisation concept requires it, and you haven't already done so, create Microsoft Entra groups now and assign users to them. For more information, see the Microsoft Entra documentation.

Create Application

To integrate ADOIT with Microsoft Entra ID, you need to create an application within the Microsoft Entra admin center:

1. Go to Identity > Applications > Enterprise applications, and then select New application.

2. Select Create your own application.

3. In the Input name box, enter the name of your application (for example ADOIT).

4. Select Integrate any other application you don't find in the gallery (Non-gallery).

5. Click Create.

Set Up SAML SSO

After creating the application within the Microsoft Entra admin center, you'll need to configure SAML SSO settings:

1. On the application's Overview page, go to Single sign-on > SAML.

2. Under Basic SAML Configuration, click Edit, and perform the following steps:

   • For Identifier (Entity ID), enter a unique ID to identify ADOIT to Microsoft Entra ID (for example ADOIT_Identifier). Keep this ID for later use on the ADOIT side.

   • For Reply URL (Assertion Consumer Service URL), enter the reply URL where the ADOIT web application expects to receive the authentication token.

     • Enter the HTTPS URL where ADOIT is available and add /auth.view, e.g. https://pp2****.de.boc-cloud.com/auth.view.

3. Under Attributes & Claims, click Edit, and configure the following claims that are issued by default. Change the source attributes if the defined attributes do not match those used in your organisation:

   • surname (user.surname): This claim provides the user's last name to ADOIT.

   • emailaddress (user.mail): This claim provides the user's email address to ADOIT.

   • name (user.userprincipalname): This claim provides the user's unique identifier to ADOIT.

   • givenname (user.givenname): This claim provides the user's first name to ADOIT.

4. Still on the Attributes & Claims page, you need to add a custom claim next:

   • user.groups: Add a group claim that provides the user's group membership information to ADOIT. Select which groups should be returned in the claim, such as Security groups to retrieve all security groups. Use sAMAccountName as the source attribute if your environment is synced with an on-premises Active Directory. If it's not, select Groups assigned to the application to be returned in the claim and Cloud-only group display names as the source attribute.

5. Under SAML Certificates, perform the following steps:

   • Copy the App Federation Metadata URL to the clipboard, which contains necessary details for ADOIT to process tokens issued by Microsoft Entra ID.

   • Download the Certificate (Base64), which is the SSL certificate for the IdP for signing SAML tokens (Cert IdP-sig).

   • Download the Federation Metadata XML which contains all the necessary information needed by ADOIT to consume tokens issued by Microsoft Entra ID. Keep this data for later use on the ADOIT side.

6. Under Set Up <my-app-name>, perform the following steps:

   • Copy the Login URL to the clipboard. Keep this URL for later use on the ADOIT side.

By following these steps, you will have successfully configured Microsoft Entra ID for SAML SSO with ADOIT.

note

The Login URL and Certificate (Base64) could also be extracted from the Federation Metadata XML, but it is more convenient to download them directly now so that you can later use them when you configure the SAML settings on the ADOIT side.

Disable User Assignment Requirement

In Microsoft Entra ID, applications have a property called Assignment required? that controls access to the application. By default, this is set to Yes, meaning users must first be assigned to this application before they can sign in.

We recommend setting this option to No to allow all users to authenticate without needing explicit assignments.

To disable required user assignment in the Microsoft Entra admin center:

1. On the application's Overview page, under Manage, click Properties.

2. Disable Assignment required? so that no user assignment is required.

3. Click Save.

With this setting disabled, any user within your directory will be able to sign in to the application, simplifying the access management process.

Optional: Configure Token Encryption

Optionally, you can encrypt SAML assertions between Microsoft Entra ID and ADOIT for additional security. This process uses a public key obtained from a certificate stored in Microsoft Entra ID to encrypt the SAML assertions, which are then decrypted by ADOIT using the matching private key.

note

Even without token encryption, Microsoft Entra ensures secure transmission of SAML tokens by mandating HTTPS/TLS connections for all token exchanges. Consider the benefits of additional security provided by token encryption against the administrative burden of managing more certificates before deciding on the most suitable approach for your organisation's security needs.

To enable token encryption in the Microsoft Entra admin center:

1. On the application's Overview page, select Token Encryption.

2. Import the certificate for the SP for decrypting SAML assertions (Cert SP-decr). Use a self-signed certificate or reuse the Cert SP-sig certificate.

3. Activate token encryption.

Configure ADOIT

Now that you've configured your chosen Identity Provider (IdP), it's time to specify SAML SSO settings in ADOIT. If you purchased SAML integration support, this part will be handled by BOC’s technical support. On-premise customers, please read on for step-by-step instructions through the entire process.

Open ADOIT Administration

To get started, open the ADOIT Administration with your administrator account:

• Enter the HTTPS URL where ADOIT is available, click Administration, enter your credentials and log in.

• If you’re already logged in to ADOIT and want to switch to the ADOIT Administration, click the user symbol in the upper-right corner, and then click Administration.

Establish Trust Relationship with IdP

The IdP uses a certificate for signing SAML tokens (Cert IdP-sig), leveraging the private key for this purpose. ADOIT also requires this certificate to validate SAML tokens signed with it, utilising the public key. There are two primary methods to make this certificate known to ADOIT:

• Reference Metadata URL (Preferred): Obtain Metadata URL from your IdP and reference it in ADOIT.
• Upload Certificate: Upload the Cert IdP-sig certificate directly into ADOIT.

Reference Metadata URL (Preferred)

The preferred method for making the certificate known to ADOIT is to obtain the metadata URL from your IdP and reference it in ADOIT. This URL points to a metadata document that contains all the necessary configuration details for SAML-based single sign-on, including the certificate used for token signing. The metadata URL must be accessible from ADOIT.

To reference the metadata URL from your IdP in ADOIT:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Hover over the SAML 1 connector, click More, and then select Configure IdP.

3. From the Configuration source list, select URL.

4. For Metadata URL, enter the metadata URL from your IdP, and then click OK. For example, for Microsoft Entra ID, enter the App Federation Metadata URL you copied.

A success message appears. Close the message and save your changes afterwards.

Upload Certificate

Alternatively, you can upload the Cert IdP-sig certificate directly into ADOIT. However, with this method, you will need to manually re-upload the certificate when your IdP switches to a new one.

To upload the Cert IdP-sig certificate:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Hover over the SAML 1 connector, click More, and then select Edit.

3. On the Properties page of the connector configuration, under IDP public key file, click Browse to upload the token-signing certificate from the IdP. When prompted to continue, click Yes.

A success message appears. Close the window and save your changes afterwards.

Configure Global SAML Settings

Next, you will have to modify global settings for SAML authentication:

1. In the ADOIT Administration, go to Authentication > SAML.

2. In the Configuration identifier box, enter a unique identifier that ADOIT will use to identify itself to the IdP.

   • The value must match the ID that you configured on the IdP side to identify ADOIT. For example, for Microsoft Entra ID, it must be equal to the Identifier (Entity ID).

3. In the Assertion consumer URL box, enter the reply URL where ADOIT expects to receive the authentication token.

   • Enter the HTTPS URL where ADOIT is available and add /auth.view, e.g. https://pp2****.de.boc-cloud.com/auth.view.

   • The value must match the reply URL configured on the IdP side. For example, for Microsoft Entra ID, it must be equal to the Reply URL (Assertion Consumer Service URL).

4. Under Token signing, configure the settings for signing SAML tokens in ADOIT:

   • Keystore alias: Enter the alias specified in the KeyStore file for the Cert SP-sig certificate (e.g. BOC).

   • Keystore file: Click Browse to upload the KeyStore file that contains the Cert SP-sig certificate (e.g. BOC.jks).

   • Keystore password: Enter the password for accessing the KeyStore. Will be stored in encrypted form.

5. Optional: If your IdP is configured to encrypt SAML assertions, edit the decryption settings under Assertion decryption:

   • Enabled: Enable this option to allow ADOIT to decrypt incoming encrypted assertions from the IdP.

   • Keystore alias: Enter the alias specified in the KeyStore file for the Cert SP-decr certificate.

   • Keystore file: Click Browse to upload the KeyStore file that contains the Cert SP-decr certificate.

   • Keystore password: Enter the password for accessing the KeyStore. Will be stored in encrypted form.

Example

Sample configuration with token decryption disabled:

SAML settings
- Configuration identifier: ADOIT_Identifier
- Assertion consumer URL: https://pp2****.de.boc-cloud.com/auth.view
- Token signing:
  - Keystore alias: BOC
  - Keystore file: BOC.jks
  - Keystore password: ******** (encrypted)
- Assertion decryption:
  - Enabled: (disabled)
  - Keystore alias: (not configured)
  - Keystore file: (not configured)
  - Keystore password: (not configured)

Adapt Connector-Specific SAML Settings

To enable SAML-based authentication with your chosen IdP, various settings must be configured, including the IDP properties, claims, and a user mapping. These settings are accessed and managed through the properties of the SAML connector within ADOIT.

To access and modify these settings:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Hover over the SAML 1 connector, click More, and then select Edit.

The following sections outline the configuration parameters that require adaptation.

Configure IDP Properties

First, you need to configure how ADOIT interacts with the IdP for authentication:

• On the SAML connector's Properties page, adjust the IDP properties.

note

Depending on how you have established the trust relationship with the IdP, some IDP properties may already be automatically populated:

• Reference Metadata URL (Preferred): Automatically fills in the properties Binding type, IDP address and IDP public key file.
• Upload Certificate: Automatically fills in only the IDP public key file.

To configure the required settings, follow these steps:

1. In the IDP name box, enter a name for the IdP. You can choose any name, e.g. ME-ID. This name will be shown in ADOIT and appear in logs.

2. From the Binding type list, select a binding type for communication with the IdP. The default is post, meaning communication happens through an HTML form submission using the POST method. If set to redirect, the client will contact the IdP via a redirect call, though this might not be allowed to specific policies.

3. In the IDP address box, enter the URL of the IdP for sending authentication requests. For example, for Microsoft Entra ID, enter the Login URL you copied.

4. Enable IDP session end on service provider session end if logging out from ADOIT should also trigger a logout on the IdP. By default, this option is disabled.

5. Verify that IDP public key file contains the Cert IdP-sig certificate.

Example

Sample configuration:

IDP properties
- IDP name: ME-ID
- Binding type: post
- IDP address: https://login.microsoftonline.com/****/saml2
- Assertion decryption: Not set
- Metadata URL: https://login.microsoftonline.com/****/federationmetadata.xml?appid=****
- IDP session end on service provider session end: (disabled)
- IDP public key file: <Cert IdP-sig>.cer

Define Claims

Next, you need to register the claims that ADOIT should expect to receive from the IdP. Claims are used to transport information about the user, such as their email address, first name, and last name. Later, you will create a user mapping, which defines how these claims are processed for assigning user attributes, system roles, user groups, and more in ADOIT.

• On the SAML connector's Properties page, under Claims, add the following claims:

Name	Value [example - use the value provided by your IdP]	Attributes	Description
claim_lastname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname	AttributeStatement	This claim represents the user's last name (surname). As a value, you can typically use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname. This URI corresponds to the surname claim from various IdPs, including Microsoft Entra ID and AD FS. If needed, you can modify the value to map to a different claim type.
claim_email	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress	AttributeStatement	This claim represents the user's email address. As a value, you can typically use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress. This URI corresponds to the emailaddress claim from various IdPs, including Microsoft Entra ID and AD FS. If needed, you can modify the value to map to a different claim type.
claim_login	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name	AttributeStatement	This claim represents the user's unique identifier, which serves as the login name on the ADOIT side. As a value, you can typically use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name. This URI corresponds to the name claim from various IdPs, including Microsoft Entra ID and AD FS. If needed, you can modify the value to map to a different claim type, e.g. http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname, which corresponds to the Windows account name claim.
claim_firstname	http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname	AttributeStatement	This claim represents the user's first name. As a value, you can typically use http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname. This URI corresponds to the givenname claim from various IdPs, including Microsoft Entra ID and AD FS. If needed, you can modify the value to map to a different claim type.
claim_group	http://schemas.microsoft.com/ws/2008/06/identity/claims/groups	AttributeStatement	This claim represents the user's group membership information. If you are using Microsoft Entra ID or AD FS, the value should be http://schemas.microsoft.com/ws/2008/06/identity/claims/groups. Other IdPs typically use http://schemas.xmlsoap.org/claims/Group.

Configure User Mapping

Next, you need to configure how the authentication process handles users who log in. For example, you can specify whether a user should be created if it does not yet exist, or which claims should be processed to assign system roles, user groups, etc.

• On the SAML connector's User Mapping page, perform the following steps:

Properties

In this section, you can map previously registered claims to ADOIT user attributes. One mapping is mandatory:

• The claim_login claim serves as the login name on the ADOIT side and needs to be mapped to the Name attribute.

Other mappings are optional. The following table shows a possible configuration:

Name	Attribute
claim_login	Name
claim_firstname	First name
claim_lastname	Last name
claim_email	Email

This configuration ensures that key user details, such as name and email, are properly mapped during the authentication process.

Roles

In this section, you can configure how system roles are assigned to users during the authentication process.

info

You can leave the Roles settings undefined if you adhere to the authorisation concept proposed in this guide. System roles are then directly assigned to user groups in the ADOIT Administration, instead of to individual users via the settings in this section.

You can specify default roles as well as define conditional group assignments.

• Default Roles: Define default system roles for users if no other role assignments apply.

• Roles: Configure custom role assignments using:

  • Property: Select the claim (e.g., claim_group) that will be used for assigning the system role.

  • Type: Choose a method to match values (see "Possible Methods to Match Values" in the Groups section below for more details).

  • Match: Define the value to match (e.g., a specific group name or ID).

  • Target Name: Select the system role to assign in ADOIT when the conditions are met.

Groups

In this section, you can configure how user groups are assigned to users during the authentication process. Group mappings are often based on the claim_group claim that represents a user's group membership information. There are two methods for assigning user groups: defining default groups and creating group mappings based on specific claim values.

• Default groups: Define default user groups for users if no other group assignments apply.

• Groups: Configure custom group assignments using:

  • Property: Select the claim (e.g., claim_group) that will be used for assigning the user group.

  • Type: Choose a method to match values (see "Possible Methods to Match Values" below for more details).

  • Match: Define the value to match (e.g., a specific group name or ID).

  • Target Name: Select the user group to assign in ADOIT when the conditions are met.

Possible Methods to Match Values

Here are the possible methods to match values (parameter Type) when defining a user mapping for a SAML connector:

• equals: The values must match exactly.

• equalsIgnoreCase: The values must match exactly, but case is ignored.

• contains: The target value must contain the specified match as a substring.

• containsWord: The target value must contain the exact word (as a whole) you're matching.

• containsWordIgnoreCase: Same as containsWord, but case is ignored.

• regExp: The matching is done using a regular expression (a pattern-based matching system, see Creating Regex Mappings).

Example

Sample Configuration:

• Members of the ADO_Modellers IdP group are assigned to the Modellers user group in ADOIT.
• Members of the ADO_Administrators IdP group are assigned to the Administrators user group.
• All other users are automatically assigned to the Readers user group.

Groups
- Default groups
  - Name: Readers
- Groups
  - User group: Modellers
    - Property: claim_group 
    - Type: equals
    - Match: ADO_Modellers
  - User group: Administrators
    - Property: claim_group 
    - Type: equals
    - Match: ADO_Administrators

Repositories

In this section, you can assign specific repositories to users as their working place based on claims. Simultaneously, the users will be made available as objects in modelling.

• Baseline assignments: Define baseline repositories that will be automatically assigned to every user. While you can still configure conditional repository assignments, these repositories will serve as the baseline for all users. Choose "All repositories" or a specific repository. For specific repositories, you can also specify an object group in which the assigned user objects should be located.

• Conditional assignments: Configure custom repository assignments using:

  • Property: Select the claim that will be used for assigning the repository.

  • Type: Choose a method to match values (see "Possible Methods to Match Values" in the Groups section above for more details).

  • Match: Define the value to match (e.g., a specific group name or ID).

  • Target Name: Select the repository to assign in ADOIT when the conditions are met. Choose to target either "All repositories" or a specific repository. For specific repositories, you can also specify an object group in which the assigned user objects should be located.

Example

Sample Configuration:

• All users are assigned the Standard-Repository repository in ADOIT.

• Members of the ADO_Modellers IdP group are additionally assigned the Test-Repository repository. The user objects are created in the Employees object group.

Repositories
- Baseline assignments
  - Repository: Standard-Repository
- Conditional assignments
  - Repository: Test-Repository
    - Property: claim_group 
    - Type: equals
    - Match: ADO_Modellers
    - Object group (optional): Employees

Named Use

In this section, you can assign named access to scenarios to users in ADOIT based on claims.

• Default scenarios: Define default scenarios for users if no other scenario assignments apply.

• Scenarios: Configure custom scenario assignments using:

  • Property: Select the claim that will be used for assigning the scenario.

  • Type: Choose a method to match values (see "Possible Methods to Match Values" in the Groups section above for more details).

  • Match: Define the value to match (e.g., a specific group name or ID).

  • Target Name: Select the scenario to assign in ADOIT when the conditions are met.

Example

Sample Configuration:

• Members of the ADO_Modellers and ADO_Administrators IdP groups are assigned named access to the Design & Document scenario in ADOIT.
• All other users are not assigned named access to the Read & Explore scenario.

Named Use
- Default scenarios
  - Name: Read & Explore
- Scenarios
  - Scenario: Design & Document
    - Property: claim_group 
    - Type: equals
    - Match: ADO_Modellers
  - Scenario: Design & Document
    - Property: claim_group 
    - Type: equals
    - Match: ADO_Administrators

Mapped User Handling

This section can be used to map users to (= treat as) alias users. These alias users will represent the authenticated user when they log in to ADOIT. An example of this might be mapping a specific group of users to a user with access to the Organisation Portal.

info

Leave the Mapped User Handling settings undefined unless your authorisation concept explicitly includes the use of alias users.

• Default mapped user: Define a default alias user for users if no other mapping applies.

• Mapped users: Configure custom alias user assignments using:

  • Property: Select the claim that will be used for assigning the alias user.

  • Type: Choose a method to match values (see "Possible Methods to Match Values" in the Groups section above for more details).

  • Match: Define the value to match (e.g., a specific group name or ID).

  • Map existing users: Optionally, specify how existing users are handled. When enabled, the authenticated user will always be treated as the alias user if the mapping criteria are met. If disabled, this mapping only applies to new users who do not already exist in the ADOIT database and cannot be automatically created.

  • Target Name: Select the alias user to assign in ADOIT when the conditions are met.

Synchronize Users

After configuring how claims will be processed to assign system roles, user groups, and more, the next step is to enable automatic user creation and turn user data synchronisation on.

• Create user automatically: Enable this option to automatically create new users in the ADOIT database the first time they log in. This ensures seamless "on-the-fly" user creation without manual intervention.

• Synchronize automatically: Enable this option to synchronise user data with the IdP each time the user logs in. This ensures that user data is always up-to-date based on IdP information. Note that any manual changes made by the ADOIT administrator will be overwritten during synchroniaation. You can specify what data is synchronized through the following sub-options:

  • Synchronize attributes (= properties): Updates user attributes such as name, email, etc.

  • Synchronize roles: Ensures system roles in ADOIT are aligned with the data from the IdP.

  • Synchronize groups: Synchronises user group membership with the IdP's information.

  • Synchronize repositories: Updates repository access based on IdP data.

  • Synchronize named use: Synchronise usage entitlements for specific scenarios.

Enable Connector

To complete the configuration of the connector-specific SAML settings, you need to enable the SAML connector:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Find the SAML 1 connector and select the Connector enabled check box.

3. Use the drag handle () to move the SAML 1 connector to the top of the list, prioritising it as the primary authentication mechanism.

4. Save your changes in the ADOIT Administration.

SAML-based authentication is now enabled and will serve as the default authentication mechanism. The standard connector ("Standard Login", the standard login page) remains active as a fallback for users who cannot authenticate via the IdP. Do not disable the standard connector.

Edit System Settings

The final configuration step is to define a few technical settings controlling the base functionality of ADOIT:

1. In the ADOIT Administration, go to Settings > System settings > System.

2. In the Base URL box, enter the URL where ADOIT can be reached from other machines.

   • Enter the HTTPS URL where ADOIT is available and add /auth.view, e.g. https://pp2****.de.boc-cloud.com/auth.view.

   • Ensure the entered value matches the Assertion consumer URL configured in the global SAML settings, excluding the /auth.view suffix.

3. Click Save.

Start Authenticating Users

Restart the ADOIT application server now to ensure that all the configurations you've applied take effect. Once the server is up and running, users can start authenticating via the IdP you've configured. New users will be automatically created in the ADOIT database the first time they log in. System roles, user groups, and other attributes will be synchronised with the IdP upon login, ensuring access rights remain current.

(Optional) Tracking Errors

Logging output is written to the files <Tomcat installation>/logs/<WEB_APPLICATION_NAME>.log and ADOIT installation/*_aworker.log.

More

In this section:

• Establishing User Groups in ADOIT
• Configure Users as Administrators in ADOIT
• Creating Regex Mappings
• Certificate Rollover
• Managing Login Name Changes

Establishing User Groups in ADOIT

An effective authorisation concept for SAML-based authentication in ADOIT requires creating user groups in ADOIT that map to IdP groups, thus connecting the people in your organisation with ADOIT user groups. After defining the groups, you'll configure their permissions and assign system roles. Below is an overview of the steps:

Create User Groups

It's easy to create user groups in ADOIT. Here is what you need to do:

1. In the ADOIT Administration, go to the Users page.

2. Select the arrow next to New user, and then select New top level user group.

3. In the Enter name box, enter a name for your user group (e.g. Modellers), and then click OK.

Repeat these steps to create all the necessary user groups for your authentication concept, such as Administrators, Modellers and Readers.

Set Permissions for User Groups

Once the groups are created, assign permissions for content like models and objects at the level of these groups:

1. In the ADOIT Administration, go to the Rights page.

2. Select the user group you want to configure.

3. Next, select a tab to display the appropriate category of permissions, such as Models or Objects.

4. To find out which permissions apply to an element, check the Read/Write column. If you cannot see the element you want, expand the hierarchy of groups and entries to display all elements.

5. To change permissions, choose one of the following actions:

   • To change the permissions for an individual element, in the Read/Write column, click Change Permissions, and then select a permission.

   • To change permissions for multiple elements at once, select the check boxes to the left of the elements, click Bulk actions, and then select the permission you want.

Example:

• If the Readers group does not need to modify content, you can restrict them to Read access for all model and object groups.

• This is most easily achieved by modifying the permissions to the default groups Models and Objects, which will then automatically apply to all subordinated groups long as no explicit permissions are set there.

Assign Default System Roles to User Groups

Next, assign the predefined default system roles to your user groups. These roles govern access to ADOIT scenarios and workflows.

note

For more information on the default system roles, refer to the ADOIT Help.

By assigning these system roles to your user groups, the permissions tied to these roles are automatically extended to all group members:

1. In the ADOIT Administration, go to the Users page.
2. Hover over the user group you want to adjust, click More, and then select Assign system roles.
3. Select the system roles you want to assign, and then click Select.

Example:

Let's assume that members of the user groups Administrators, Modellers and Readers should have access to different scenarios in ADOIT. The configuration could look like this:

• Assign the User system role to the Administrators and Modellers user groups to provide access to ALL scenarios.
• Assign the Reader system role to the Readers user group to provide access to the "Read & Explore" scenario.

Optional: Modules and Metamodel Rights

For advanced scenarios, you can grant system roles access to specific modules (e.g., matrix charts or Excel import features). You can assign these modules to the default system roles or create new roles.

To further refine access permissions, you can configure metamodel rights at the system role level, governing who can work with metamodel elements like model types and attributes in ADOIT. The predefined default system roles don't allow this, so creating custom system roles is necessary for assigning these rights.

note

For more information on assigning modules, creating system roles and configuring metamodel rights, refer to the ADOIT Help:

• Modules

• Create System Role

• Manage Metamodel Rights

Configure Users as Administrators in ADOIT

In ADOIT, you can create administrators in two ways:

• Global Administrators: Grant a user comprehensive administrative rights across the entire system, allowing them to perform nearly all administrative tasks.

• Sub-Administrators: Assign limited administration rights to manage specific repository areas or user groups, either at the group or individual user level.

Details on configuring each type are outlined below.

Assigning Global Administration Rights

To make a user a global administrator:

1. In the ADOIT Administration, go to the Rights page.

2. Select the user to receive global admin rights.

3. Go to the Components tab.

4. In the workspace, find the Administration Toolkit component.

5. In the Access column, click Change Permissions, and then choose Assign global administration rights. When prompted to continue, click Yes.

This grants the user write access to all model groups, models, object groups, objects, user groups, and users.

Configuring Sub-Administrators

To set up sub-administrators, follow these steps:

Grant Access Rights to the ADOIT Administration

For sub-admins to manage user rights, they need access to the ADOIT Administration. Assign this at the user group level to reduce administrative efforts:

1. In the ADOIT Administration, go to the Rights page.

2. Select the user group you want to authorise.

3. Go to the Components tab.

4. In the workspace, find the Administration Toolkit component.

5. In the Access column, click Change Permissions, and then choose Access.

Enable Sub-Administrators to Manage User Rights

To let sub-admins change other users' access rights to models and objects, allow Change Permissions for the user groups they should manage:

1. In the ADOIT Administration, go to the Rights page.

2. Click the Expert Mode button.

3. Select the sub-admin user group.

4. Go to the Users tab.

5. For each user group you want the sub-admins to manage, in the Change Rights column, click Change Permissions and choose Allowed.

Members of the sub-admin group can now log into the ADOIT Administration and manage permissions for the user groups they’re authorised to oversee.

note

To prevent privilege escalation, sub-admins cannot grant permissions beyond their own level. For instance, if a sub-admin group has Read access to the "Models" model group, they cannot assign Write access to this group for any user groups they manage.

Creating Regex Mappings

When you configure a user mapping in ADOIT, you can use regular expressions to create advanced, pattern-based rules for assigning users to system roles, user groups, and more based on IdP claims. This is particularly helpful when group names in your IdP follow a naming convention or contain specific patterns.

To create a regex mapping:

• Set Type to regexp and enter your regular expression in the Match field.

Let’s walk through two examples:

Example 1: Regex Mapping with "Exact Line Match"

In this example, we want to assign users to the Readers user group in ADOIT if the claim_group value is exactly "ReadOnly" as a whole line or appears at the start or end of a line. Here’s the configuration:

Groups
- Default groups: (not configured)
- Groups:
  - User group: Readers
    - Property: claim_group 
    - Type: regexp
    - Match: (?s).*(^|\n)ReadOnly($|\n).*

Explanation:

• Match: The regular expression (?s).*(^|\n)ReadOnly($|\n).* ensures "ReadOnly" is matched only if it’s an entire line or at the beginning or end of a line. Here’s how:
  • (?s): Enables "dotall" mode, allowing . to match any character, including newlines.
  • (^|\n)ReadOnly($|\n): Anchors "ReadOnly" to the start (^) or end ($) of a line, matching it as a distinct line.
  • .* before and after allows for any additional text, making it flexible within multiline strings.

Example 2: Regex Mapping with "Contains" Match

In this example, we assign users to the Readers user group if claim_group contains "ReadOnly" anywhere in the text. Here’s the configuration:

Groups
- Default groups: (not configured)
- Groups:
  - User group: Readers
    - Property: claim_group 
    - Type: regexp
    - Match: .*ReadOnly.*

Explanation:

• Match: The .*ReadOnly.* pattern matches any value in claim_group containing "ReadOnly" as a substring, regardless of its position.

Additional Resources

If you’re unfamiliar with regular expressions or want to learn more about constructing them, this page provides an excellent introduction to regular expressions: Regular Expressions (Regex).

To test your regex patterns and ensure they match the intended values, try regex101, a helpful tool for building and validating regular expressions.

Certificate Rollover

The certificate used by your IdP for signing SAML tokens (Cert IdP-sig) needs to be periodically renewed, a process known as certificate rollover. When this happens, you must ensure that ADOIT is updated with the new certificate to maintain the trust relationship between ADOIT and your IdP.

There are two scenarios for managing certificate rollover, depending on the method you initially used to configure the certificate in ADOIT: referencing a metadata URL or uploading the certificate directly.

Scenario 1: Referencing the Metadata URL

If you initially referenced the IdP's metadata URL during configuration, you’ll need to manually update the connector when the certificate rolls over. While ADOIT can retrieve the latest metadata from the URL, it does not automatically refresh the configuration regularly. Therefore, after a certificate rollover, you must perform the following steps to renew the certificate:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Hover over the SAML 1 connector, click More, and then select Configure IdP.

3. From the Configuration source list, select URL.

4. The Metadata URL field should now already be populated with the metadata URL from your IdP. If not, enter it.

5. Click OK, close the success message, and save your changes.

This process ensures that ADOIT retrieves the new certificate contained within the metadata.

Scenario 2: Uploading the Certificate Directly

If you initially uploaded the certificate directly into ADOIT, you’ll need to upload the new certificate manually each time the IdP rolls over to a new one. Follow these steps to update the certificate:

1. In the ADOIT Administration, go to Authentication > Connectors.

2. Hover over the SAML 1 connector, click More, and then select Edit.

3. On the Properties page of the connector configuration, under IDP public key file, click Browse to upload the new token-signing certificate from the IdP. When prompted to continue, click Yes.

4. A success message will appear. Close the message and save your changes.

By uploading the new certificate, you ensure that ADOIT continues to validate SAML tokens issued by your IdP.

Managing Login Name Changes

In some cases, the login name provided by the IdP in the SAML response may change, such as after a name change (e.g., marriage) or due to a domain migration. When this occurs, ADOIT will treat the new login name as a different user, resulting in the creation of a new user account and a corresponding new user object. This means the same person will have two accounts in ADOIT - one associated with the old login name and another with the new one.

To address this, please contact our support team. Our colleagues can update the login name in the system, consolidating the two user objects into one. Once the change is processed, the user will be able to log in with their new credentials, with all their relations in ADOIT intact.