Skip to main content
Skip table of contents

User management via SAML2

LUY can be set up to authenticate users via SAML2 and an identity provider (IDP).

LUY matches its own roles with the user groups sent by the identity provider (IDP).

For example:
User Alice is part of the groups "admin" and "employee". In LUY the roles "admin" and "architect" are already present. When Alice logs into LUY, the group "admin" is matched to the LUY role "admin" because they share the same name. The group "employee" as well as the LUY role "architect" are ignored since there is no match for them. Alice is then assigned the permissions of the LUY role "admin".

Prerequisites

In order to use LUY with the identity provider (IDP) the following must be available:

  • An identity provider (IDP) which allows authentication via SAML2

  • The link to the metadata of the identity provider (IDP) 

  • The metadata from the identity provider (IDP)

  • The identity provider (IDP) must send the following attributes to LUY

    • Last name

    • First name

    • Login

    • Email

    • Usergroups or IDs for matching the "role" in LUY

  • The possibility to create a "keystore" on a system console (CMD/Linux terminal) 

Metadata from the identity provider 

Set up the LUY login on the identity provider (IDP). When this is finished, download the "metadata" to the local system. This is a necessary step in order to set up the keystore for the LUY SAML2 connection. If additional certificates for authentication to the identity provider (IDP) are used, take note of these as well. 

Create the certificate file

Create the file "Cert1.cer" and add these two lines:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

Save the file in a new folder. Open the downloaded "metadata" and search for the first relevant entry of "<X509Certificate>". If the IDP has more than one <x509Certificate> entries, search for entry "Keydescription" -"signing". The "Keydescription" can be different for different IDPs

<X509Certificate> MIIC8DCCAdigAwIBAgIQFn1DqrUImqtOk9t3euSiVzANBgkqhkiG9... </X509Certificate>

Copy the value between "<X509Certficate>" and "</X509Certificate>" and paste it into the lines

-----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- 

in created file "Cert1.cer". The file "Cert1.cer" should now look like this: 

-----BEGIN CERTIFICATE----- MIIC8DCCAdigAwIBAgIQFn1DqrUImqtOk9t3euSiVzANBgkqhkiG9... -----END CERTIFICATE-----

Save the file and close it. If additional certificates are needed, create additional "*.cer" files and save them into the same folder as the keystore.

Open a terminal console "CMD" or the "Linux terminal". Open the folder where the certificates are saved. Enter the following command to create the keystore for LUY:

CMD: "%JAVA_HOME%\bin\keytool" -genkey -alias luy -keyalg RSA -keystore keystore.jks -validity 360 when the "JRE" is used "%JRE_HOME%\bin\keytool" -genkey -alias luy -keyalg RSA -keystore keystore.jks -validity 360
Linux Terminal:
keytool -genkey -alias luy -keyalg RSA -keystore keystore.jks -validity 360

After the keystore is created, enter the following command to import the certificates into the keystore. 

CMD: "%JAVA_HOME%\bin\keytool" -import -alias idpSigningKey -file Cert1.cer -keystore keystore.jks when the "JRE" is used "%JRE_HOME%\bin\keytool" -import -alias idpSigningKey -file Cert1.cer -keystore keystore.jks
Linux Terminal:
keytool -import -alias idpSigningKey -file Cert1.cer -keystore keystore.jks

The certificate created from the metadata must have the alias - idpSigningKey. 
Import the remaining certificates, the alias should be different for every certificate.

Install LUY 

Start the installer and select SAML2 as authentication option. Enter the necessary information. A description of the values for SAML2 is listed in the SAML2 properties below. Additionally, if the REST API of LUY is needed, select this option in the installer.

After the setup is finished and LUY is deployed, stop your Tomcat. Copy the finished keystore in the folder "security" on the path "$TOMCAT/webapps/<luy>/WEB-INF/classes/security".

SAML2 properties

These properties can be set in the installation process or in the file luy-auth.properties. 
This file can be found in the path "$TOMCAT/webapps/<luy>/WEB-INF/classes".

baseURL:

The entity baseURL must be set like "https://<servername>:<port>/luy".

E.g., "saml.entityBaseURL=https://test.luy.eu:443/LUY703 

The entity baseURL is added to the metadata.xml of the service provider (LUY). When LUY is started, you can download the metadata of the service provider (LUY) from the URL:

"https://test.luy.eu:443/saml/metadata".

In the metadata.xml, the baseURL is used for:

REPLY URL: https://test.luy.eu:443/saml/SSO
SIGN ON URL: https://test.luy.eu   
LOGOUT URL: https://test.luy.eu:443/saml/SingleLogout

entityId:

The entityId must be set to a URL or ID which is provided by the identity provider (IDP).
If you use MS Azure, the addition "spn:" must be added to your ID. For some identity providers (IDP) it may happen that the addition "spn:" is not needed for the ID.  

E.g., "saml.entityId=spn:00330-39993-48884"

metadataUrl:

The URL must be set to access the metadata of the identity provider (IDP). E.g., for MS Azure the metadatUrl looks like this:
"https://login.microsoftonline.com/<IDP-ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<ALPHA-NUMERIC ID OF THE APPLICATION CREATED IN THE IDP>"

Attributes:

LUY needs the following items from the identity provider (IDP) to login and assign the LUY roles to the user correctly:

  • firstname 

  • lastname 

  • email 

  • login

  • groups

The following first example is a generic configuration and the second one shows MS Azure:

#1
saml.attribute.firstname=Given_Name
saml.attribute.lastname=Sur_Name
saml.attribute.email=E-Mailadress
saml.attribute.login=userprincipalname
saml.attribute.groups=LUY_Munich

#2

saml.attribute.firstname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
saml.attribute.lastname=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
saml.attribute.email=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
saml.attribute.login=http://schemas.microsoft.com/identity/claims/objectidentifier
saml.attribute.groups=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

It is possible to add more than one value in the attribute "groups":

"saml.attribute.groups=LUY_Munich; E-Mailadress"

Creditials for keystore and certificate:

The credentials for saml.keystore and saml.cert are usually the same.

saml.keystore.user=luykeystore
saml.keystore.password.encrypted=password
saml.keystore.encrypted=false

saml.cert.user=luykestore
saml.cert.password.encrypted=password
saml.cert.encrypted=false

If an additional encrypted certificate is used, specify the credentials in the part saml.cert.user and saml.cert.password.

DefaultRole:

Specify a LUY role to be assigned to every successfully identified user over IDP by default. This role is added additionally to the roles sent by the identity provider (IDP).

For an initial setup of LUY use the role "luy_Supervisor" to create and manage any other roles.
Afterwards, this role can be removed. A restart of LUY is required to apply the changes.

Additional settings: 

With "saml.maxAuthenticationAge" the maximal value for the allowed age of an authentication cookie can be defined. The value is set in seconds.

The entry "security.daysBeforePasswordExpires=9999" should not be changed.
The entry "saml.enabled=true" should be not changed. 

Log level

If the login does not work, a higher log level is especially useful for diagnosis. Uncomment the following lines in the file "luy-auth.properties“ in the path "$TOMCAT/webapps/<luy>/WEB-INF/classes":

saml.logAllMessages=true
saml.logErrors=true
saml.logMessagesOnException=true

iTURM and REST requests

The REST interface requires basic authentication in LUY. For this, an iTurm instance is necessary.
SAML2 cannot be used for basic authentication. Log into iTURM and create a technical user to use for basic authentication. You need a LUY role for the permissions of this user. Create or use an existing LUY role and create a role with the same name in iTURM. Then add users to this role.

Sign in with SAML2

Upon successful setup of SAML2 for LUY, the login screen will present the option to “Sign in with SSO”. Click here to access LUY.

Username and password entry are disabled in this setting.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close