SAML2

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

Prerequisites

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

An identity provider (IDP) which allows authentication via SAML2
A link to the metadata of the identity provider (IDP)
The identity provider (IDP) must send the following claims to LUY
- Last name
- First name
- Login
- E-Mail
- Usergroups or IDs for matching the "role" in LUY

Setup SAML2

To authenticate users in LUY over SAML2 with the used IDP, it is necessary to mount the

luy_saml_properties.yml.

The property file should look like this:

CODE

luy:
  auth:
    saml2:
      relying-party:      
        # Properties for determining the properties of the service provider
        # The entity base URL of the application that will be added to the metadata of the service provider
        entity-base-url: https://test.luy.app/
        
        # The entity id that is generated in the identity provider for LUY
        # for Entra ID this has the following format "spn:<ALPHA-NUMERIC ID OF THE APPLICATION CREATED IN THE IDP>"
        entity-id: spn:00330-39993-48884          

        #If you have imported the signing key in the keystore, please provide the alias and password for the certificate here
        #signing-key:
         #alias: idpSigningKey
         #password: Password      
        
        #If you have imported the decryption key in the keystore, please provide the alias and password for the certificate here
          #alias: alias
          #password: password

      # If a keystore is used the password needs to be set
      # Please don't change the keystore path 
      #keystore: 
        #path: /var/luy/conf/saml.jks
        #password: Password
     
      asserting-party:
        # The URL where the metadata of the identity provider can be found
        # for Entra ID it looks like 
        # https://login.microsoftonline.com/<IDP-ID>/federationmetadata/2007-06/federationmetadata.xml?appid=<ALPHA-NUMERIC ID OF THE APPLICATION CREATED IN THE IDP>
        metadata-url: https://login.microsoftonline.com/<IDP-ID>/federationmetadata/2007-06/federationmetadata.xml?appid=003303999348884
        
      attributes:
        # Properties for the different claims that will be used when reading the saml response

        # The claim that is used to get the value for the first name
        first-name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
        
        # The claim that is used to get the value for the last name
        last-name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
        
        # The attribute that is used to get the value for the email address
        email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
        
        # The claim that is used to get the value for the login name
        login: http://schemas.microsoft.com/identity/claims/objectidentifier
        
        # The claim that is used to get the value for the assignment of the groups.
        # The format the value that is send from the IDP is also the format that has to be used as role names
        groups: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups
        
      # The name of a default role that each User that logs in via saml2 gets
      # If no role should be set, set the empty value '~'
      default-role: luy_Supervisor

entity-base-url:

The entity-base-url must be set like "https://<servername>/".

E.g., entity-base-url: https://test.luy.app/

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

https://test.luy.app/saml/metadata.

In the metadata.xml, the entity-base-url is used for:

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

entity-id:

The entity-id must be set to a URL or ID which is provided by the identity provider (IDP).
If you use Entra ID, the addition "spn:" must be added to your entity-id:

E.g., entity-id: spn:00330-39993-48884

metadata-url:

The metadata-url must be set to access the metadata of the identity provider (IDP).
E.g., for Entra ID the metadata-url looks like this:

metadata-url: https://login.microsoftonline.com/<IDP-ID>/federationmetadata/2007-06/federationmetadata.xml?appid=003303999348884

attributes:

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

firstname-name
last-name
email
login
groups

The following first example is a generic configuration and the second one shows Entra ID:

#1
first-name: Given_Name
last-name: Last Name
email: E-Mailadress
login: userprincipalname
groups: Groups

#2

first-name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
last-name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
email: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
login: http://schemas.microsoft.com/identity/claims/objectidentifier
groups: http://schemas.microsoft.com/ws/2008/06/identity/claims/groups

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

groups: LUY_Munich; E-Mailaddress

default-role:

Specify a LUY role to be assigned to every authenticated user over SAML2 by default. This role is additionally added to the sent group claims.

Use the role "luy_Supervisor" to initially create and manage other roles.

E.g. default-role: luy_Supervisor

Afterwards, this role needs to be removed, and the default value '~' can be set.
A restart of LUY is required to apply the changes.

Keystore (optional)

In some setups, certificates for signing key and decryption key are required. For such setups, we need to create a keystore to import the certificates.

Create 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 luysigninkey -keyalg RSA -keystore keystore.jks -validity 360
Linux Terminal:
keytool -genkey -alias luy -keyalg RSA -keystore keystore.jks -validity 360

Configuration of keystore and certificates:

To use a keystore containing a signing key or decryption key in LUY, you need to uncomment and configure the following parts in the luy-saml-properties.yml and compose.yml file.

To mount the created keystore, it needs to be included in the container via the compose.yml file. Uncomment the following line:

CODE

      # Uncomment the following line if you require a keystore for the saml2 authentication method
      - ./keystore.jks:/var/luy/conf/saml.jks

Now that the keystore is available in the container, uncomment the keystore, path, and password fields, and set the password for the keystore:

CODE

      # If a keystore is used the password needs to be set
      # Please don't change the keystore path 
      keystore: 
        path: /var/luy/conf/saml.jks
        password: Password

To specify the alias and password for the signing and decryption key, uncomment the following lines:

CODE

        #If you have imported the signing key in the keystore, please provide the alias and password for the certificate here
        signing-key:
         alias: luysigninkey
         password: password      
        
        #If you have imported the decryption key in the keystore, please provide the alias and password for the certificate here
        decryption-key:
          alias: decryptionkeyalias
          password: password

Roles

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

For example:
When Alice logs into LUY, her user profile indicates she belongs to both the "admin" and "employee" groups which are sent by the IDP. Within LUY, predefined roles such as "admin" and "architect" exist. Upon login, Alice's "admin" group aligns with the "admin" role in LUY, thanks to the identical naming convention. The group "employee" as well as the LUY role "architect" are ignored since there is no match for them. Alice is then assigned only the permissions of the LUY role "admin".

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.