Client `saml`¶

Description¶

Ce client permet l'authentification par SAML. Il n'intègre que le mode indirect et est donc réservé à l'authentification des individus (personnes physiques). Pour l'authentification des services, se reporter vers un autre type de client.

Le module s'appuie sur le client SAML de pac4j.

Exemple de configuration¶

<client name="saml" type="saml">
    <keystorePath>file:${env:CATALINA_HOME}/conf/saml/samlKeystore.jks</keystorePath>
    <keystorePassword>changeit</keystorePassword>
    <privateKeyPassword>changeit</privateKeyPassword>
    <idpMetadataPath>file:${env:CATALINA_HOME}/conf/saml/idp-metadata.xml</idpMetadataPath>

    <entityId>ewt-saml-client</entityId>
    <spMetadataPath></spMetadataPath>
    <keyStoreType>jks</keyStoreType>
    <keyStoreAlias></keyStoreAlias>
    <maxAuthLifetime>3600</maxAuthLifetime>
</client>

Paramètres¶

keystorePath obligatoire

Chemin du keystore contenant la paire de clés utilisées pour le chiffrement et la signature. Le client attend un keystore JKS.

Pour désigner un fichier local, utiliser le préfixe file:.

Pour désigner un fichier en ligne, utiliser le préfixe http: ou https:.

Si nécessaire, vous pouvez générer une paire de clés au moyen de la commande suivante:

$ keytool -genkeypair
          -alias ewt-saml
          -keypass changeit
          -keystore samlKeystore.jks
          -storepass changeit
          -keyalg RSA
          -keysize 2048
          -validity 3650

Pour convertir un keystore PKCS12 en JKS, utiliser la commande suivante:

$ keytool -importkeystore
          -srckeystore <path_to>/source.pfx
          -srcstoretype PKCS12
          -srcstorepass SecretPass
          -destkeystore <path_to>/samlKeystore.jks
          -deststoretype JKS
          -deststorepass changeit
          -destalias ewt-saml
          -destkeypass changeit
Importing keystore source.pfx to samlKeystore.jks...
Entry for alias le-webservertls-d3be9bec-bcb5-4456-94ac-cfbfa0c7f030 successfully imported.
Import command completed:  1 entries successfully imported, 0 entries failed or cancelled

Si l'alias de clé ne convient pas, il est possible de changer le nom d'alias de notre keystore. L'alias actuel est inscrit dans le message ci-dessus. Il peut également être retrouvé avec la commande

keytool -list -keystore <path_to>/samlKeystore.jks -storepass changeit

Utiliser la commande suivante pour renommer cet alias.

keytool -changealias -keystore <path_to>/samlKeystore.jks -storepass changeit
        -alias le-webservertls-d3be9bec-bcb5-4456-94ac-cfbfa0c7f030
        -destalias ewt-saml

Penser également à adapter les autorisations, par exemple:

chown root:tomcat <path_to>/samlKeystore.jks

keystorePassword obligatoire

Mot de passe du keystore (correspond au paramètre -storepass de la commande keytool)

privateKeyPassword obligatoire

Mot de passe de la clé privée (correspond au paramètre -keypass de la commande keytool)

idpMetadataPath obligatoire

Chemin du fichier de métadonnées du fournisseur d'identité (identity provider ou IDP).

Pour désigner un fichier local, utiliser le préfixe file:.

Pour désigner un fichier en ligne, utiliser le préfixe http: ou https:.

entityId

Par défaut, c'est l'URL de callback du moteur (service provider) qui est utilisé comme entity ID. Il est possible de spécifier une autre valeur de service provider entity ID.

keyStoreType

Type du keystore

keyStoreAlias

Alias de clé à reprendre dans le keystore

maxAuthLifetime

Durée de vie de la session en secondes

spMetadataPath

Chemin du fichier de métadonnées à produire pour le service provider (c.-à-d. l'application ewt). La JVM doit posséder un droit d'écriture sur le dossier contenant le fichier indiqué. Le fichier est généré à la première connexion via le client saml.

Pour désigner un fichier local, utiliser le préfixe file:.

Pour désigner un fichier en ligne, utiliser le préfixe http: ou https:.

⚠️ Attention, ce paramètre ne sert pas à référencer un fichier de metadonnées existant mais à indiquer à quel emplacement générer les métadonnées du service provider. Dans le cas où le chemin désigne un fichier, ce dernier ne doit pas exister afin que le moteur puisse le générer. Si un fichier est déjà présent à l'emplacement indiqué, ce dernier sera renommé et un nouveau fichier sera créé par le moteur. Le dossier contenant le fichier indiqué doit être accessible en écriture par la JVM.

forceAuth

Flag true/false permettant de contrôler le mode forced de l'authentification. Par défaut: false

passive

Flag true/false permettant de contrôler le mode passive de l'authentification. Par défaut: false

authRequestBindingType

Type de binding de la requête d'authentification.

La valeur par défaut est urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Pour rappel, les bindings possibles sont:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST-SimpleSign

authResponseBindingType

Type de binding de la réponse d'authentification.

La valeur par défaut est urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

Pour rappel, les bindings possibles sont:

urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact

logoutRequestBindingType

Type de binding de la requête de logout.

La valeur par défaut est urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

logoutResponseBindingType

Type de binding de la requête de logout.

La valeur par défaut est urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST.

useNameQualifier

Flag true/false permettant de forcer un NameQualifier dans la requête d'authentification. Selon la spécification SAML, la requête ne doit pas contenir de NameQualified lorsque le format du SP entity est nameid-format:entity. Il arrive cependant que certains IdP nécessite que cette information soit présente. Par défaut: false

responseDestinationAttributeMandatory

Flag true/false permettant de désactiver le contrôle de l'attribut Destination dans la réponse SAML. La spécification SAML suggère que cet attribut doit être présent et par défaut le module d'authentification vérifie que c'est le cas. Le flag permet de désactiver ce contrôle. Par défaut: true

attributeConsumingServiceIndex

Index de l'attribut de consuming service à transmettre à l'IdP. Par défaut: -1

assertionConsumerServiceIndex

Index de l'assertion de consuming service à transmettre à l'IdP. Par défaut: -1

wantsAssertionsSigned

Flag true/false permettant d'indiquer le statut de signature des assertions. Par défaut: false

wantsResponsesSigned

Flag true/false permettant d'indiquer le statut de signature des réponses. Par défaut: false

authnRequestSigned

Flag true/false

acceptedSkew

Délai maximum d'écart d'horloge autorisé entre l'IdP et le SP, en secondes. Par défaut: 300

uidAttribute

Nom de l'attribut contenant la valeur à reprendre comme uid. Si défini, le module va reprendre la valeur de l'attribut indiqué comme nom d'utilisateur.

rolesAttribute

Nom de l'attribut contenant les rôles. Si défini, le module va reprendre le ou les attributs indiqués en tant que rôle dans le profile.

repository

Référentiel(s) sur le(s)quel(s) s'appuyer pour mettre à jour les profils utilisateurs. Si défini, le module va demander au(x) référentiel(s) indiqué(s) de vérifier l'existence du profil et de compléter les rôles et attributs.

Il est possible de spécifier plusieurs référentiels en les séparant par une virgule.

Mise en oeuvre¶

En pratique, on commencera par générer le keystore à l'aide de keytool (voir paramètre keystorePath ci-dessus) et à référencer ce dernier dans le fichier de configuration.

Ensuite on définit les autres paramètres de la config.

En démarrant le moteur, celui-ci va construire un fichier de metadata pour l'application (le service provider). Ce fichier sera enregistré à l'emplacement désigné par la propriété spMetadataPath (à condition que le chemin indiqué soit accessible et ne contienne pas déjà un fichier existant).

Selon l'IAM utilisé, ce fichier peut ensuite être réutilisé pour créer le client. Par exemple sur Keycloak, le client peut être créé ainsi:

Cliquer sur l'entrée "Client" du menu principal
Dans la liste "Clients list", cliquer sur "Import client"
Sélectionner le fichier sp-metadata.xml généré par le moteur
Cliquer sur "Save"

Cela crée automatiquement le client dans Keycloak.

Client saml¶

Description¶

Exemple de configuration¶

Paramètres¶

Mise en oeuvre¶

Client `saml`¶