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.