Single Sign-on with SAML 2.0

Overview

Security Assertion Markup Language 2.0 (SAML 2.0) is a standardized, XML-based framework for the exchange of security and login information between different systems. The most common use case for using this standard is the provision of Single Sign-on (SSO) for web applications. In CURSOR-CRM, SAML 2.0 can be used to integrate the Web Client into an existing environment for Single Sign-on. For this purpose, the Web Browser SSO Profile of SAML 2.0 is used. The systems involved then exchange so-called SAML Assertions to communicate information about participants in the service landscape.

The authentication of users with SAML 2.0 is only possible in the Web Client. Other clients, such as the Windows client or apps, do not support this login procedure.

Systems involved

Three parties are involved when running the SAML 2.0 Web Browser SSO Profile and thus also when using SAML 2.0 SSO in the CURSOR-CRM Web Client:

• Identity Provider (IdP): The Identity Provider performs the authentication of users. For this purpose, he can use any procedure, such as a login mask with user name and password or Kerberos, and can also supplement these with measures such as 2-factor authentication.
  Examples of identity providers include Microsoft Active Directory Federation Services (ADFS) and Red Hat Keycloak.

• Service Provider (SP): The Service Provider receives assertions about users from the identity provider and uses the information from these to determine the identity of users at login. Thus, it relies on the statements of the identity provider for authentication. This is why a service provider is also called a Relying Party.
  The CURSOR-CRM Web Client acts as a service provider in a SAML 2.0 system landscape.

• User or User Agent: In the context of SAML 2.0, a User is defined as a participant in the system who wishes to use the services of a service provider. The User Agent is the browser of this user in the Web environment.

SAML 2.0 metadata

CURSOR-CRM uses Login SAML 2.0 IdP metadata for the configuration of SAML 2.0. Identity providers use this metadata to provide information about themselves for retrieval by service providers. An SP such as CURSOR-CRM can then retrieve this in order to obtain information about SAML 2.0 endpoints or cryptographic certificates used. This simplifies the configuration for the CURSOR-CRM administrator.

Note

In order for CURSOR-CRM to be configured for authentication and Single Sign-on with a SAML 2.0 Identity Provider, that identity provider must provide its SAML 2.0 metadata over a TLS encrypted HTTPS endpoint. This is the only way to ensure the authenticity and integrity of the transmitted cryptographic keys.

Assignment of identity provider users to CURSOR-CRM users

SAML 2.0 Identity Provider and CURSOR-CRM each have separate user administrations. CURSOR-CRM manages users via employee datasets. Without further configuration, these initially have no relation to the users of the identity provider. For the login with SAML 2.0 to CURSOR-CRM, it is therefore necessary that users of the Identity Provider can be assigned to CURSOR-CRM employee datasets.

In SAML 2.0 Assertions a field called NameID is included. There are different formats for NameIDs, but in CURSOR-CRM they are all treated as simple strings. Whether these are meaningless character strings, long columns of numbers or structured data is an implementation detail of the identity provider or can be set there. When sending the authentication request to the Identity Provider, CURSOR-CRM passes a request for the NameID format. By default, the format "Unspecified" is passed as a request, which allows the Identity Provider to decide freely on the format. However, this can be changed to a different NameID format in the CURSOR-CRM system settings.

The assignment of these NameIDs to CURSOR-CRM users is done via the field SAML Login Name in the employee dataset. In this text field, the NameID used by the identity provider for this employee must be entered. If a correct login with SAML 2.0 takes place on the system, CURSOR-CRM searches the SAML login names of all employee datasets for the corresponding value. Only if only one single employee dataset has a SAML Login Name that exactly matches the NameID of the received SAML 2.0 Assertion, this employee will be assigned to the current login attempt and logged in. If several employee datasets contain an identical SAML Login Name, the login with SAML 2.0 is deactivated for both employees for security reasons.

NameIDs and thus SAML Login Names of employees are treated as case-sensitive according to the SAML 2.0 default, i.e. upper and lower case is significant. So the NameIDs abcdef123456 and aBCDEf123456 describe different users!
Since this is a frequent source of errors, however, failed user assignments, which are caused by different upper and lower case letters, are logged in detail in the server log.

System Preferences

Configuration in CURSOR-CRM

In the system preferences, the settings relevant for SAML 2.0 are located in the SAML 2.0 Login area. The following settings are available here:

Configuration per CURSOR-CRM User

For each CURSOR-CRM user for whom the login with SAML 2.0 should be possible, the correct SAML Login Name must be stored in the employee dataset in order to be able to assign users of the identity provider to the CRM users. The correct name depends on the configuration of the identity provider. Details on assignment can be found in the section Assignment of Identity Provider users to CURSOR-CRM users.

Use in the CURSOR-CRM Web Client

General notes on use

If SAML 2.0 is configured correctly, it can be used in the CURSOR-CRM Web Client. For this purpose, a specific login page must be used, since the normal login page is denied to other login procedures. The SAML 2.0 login is available under the path /login/saml/callbac, i.e. in a complete URL for example at https://crm.example.com:18443/login/saml/callbac.

If an error occurs during the login with SAML 2.0, the user is automatically redirected to the normal login page. There, a corresponding error message will be displayed and the user can continue with a manual login.

If SAML 2.0 is deactivated in the system, a redirection to the login page is made without error message.

Interaction with other authentication methods in CURSOR-CRM

Authentication or Single Sign-on with SAML 2.0 is independent of the classic login procedure via the login mask in the Web Client by using a separate login URL. On the classic login mask, the classic login with user name and password or Single Sign-on with Kerberos or SPNEGO can still be used (depending on the configuration).

The SAML 2.0 configuration has no influence on the login to the Windows Client or to the apps.

Configuration of a SAML 2.0 Identity Provider for CURSOR-CRM

General

To enable CURSOR-CRM to use an identity provider for authentication, the identity provider must first be configured to work with CURSOR-CRM. The properties to be set for this purpose are documented in brief below. These options can be set differently for different identity providers. How exactly this works with a special identity provider can be found in the documentation of the identity provider. Only for the Microsoft Active Directory Federation Services (ADFS) an exemplary manual is provided in a later section.

• NameID format: Unspecified (by default; the requested NameID format can be changed in the system settings)
  CURSOR-CRM does not require a special NameID format, because internally NameIDs are compared as simple strings. The only requirement is that the NameID assigned to a user does not change. Therefore, Persistent is recommended as the NameID format, as it meets this requirement. However, it is explicitly not required that the NameIDs are randomly generated pseudonyms (as actually required for persistent NameIDs). Therefore, deviating configurations are also possible.

• EntityID or Relying Party Identifier: /webclient/, for example https://crm.example.com:18443/webclient/

• Assertion Consumer Endpoint URL, POST-Back URL or Callback-URL: /login/saml/callbac, for example: https://crm.example.com:18443/login/saml/callbac

For the cooperation with CURSOR-CRM it is necessary that the identity provider digitally signs the SAML 2.0 Assertion. It is not sufficient to sign the entire SAML 2.0 response; the assertion element in the response itself must be signed.

CURSOR-CRM does not support encrypted SAML 2.0 Assertions and Responses. An optional encryption must be deactivated in the Identity Provider. The digital signature of the assertions is sufficient for the security of the login.

Frequently used Identity Providers

For some commonly used Identity Providers, we additionally provide concrete step-by-step instructions. These can be found in the following sections.