H· Hawiyati Documentation

Guide d’intégration Java/Spring Boot

Intégrez le SDK SAML2 SP Hawiyati avec vos applications Java/Spring Boot. Couvre la dépendance Maven, la configuration minimale, la protection des routes, le traitement du callback ACS, la déconnexion et l’enregistrement SP.

1. Prérequis

PrérequisVersion minimale
Java17
Spring Boot3.2.x
Hawiyati IdP2.0
Accès réseauSP → IdP sur le port 443

Les horloges du SP et de l’IdP doivent être synchronisées à moins de 5 minutes près. Utilisez NTP dans tous les environnements. La tolérance par défaut est de 60 secondes.

2. Ajout de la dépendance

Ajoutez le starter Spring Boot dans votre pom.xml :

<dependency>
    <groupId>org.hawiyati</groupId>
    <artifactId>saml-sp-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

Pour les déploiements multi-instances, ajoutez également l’adaptateur Redis :

<dependency>
    <groupId>org.hawiyati</groupId>
    <artifactId>saml-sp-redis</artifactId>
    <version>1.0.0</version>
</dependency>

3. Configuration minimale

Ajoutez les éléments suivants à votre application.yml :

hawiyati:
  saml:
    sp:
      entity-id: https://app.example.com/saml/metadata
      acs-url: https://app.example.com/saml/acs
      idp:
        entity-id: https://idp.hawiyati.org
        sso-url: https://idp.hawiyati.org/saml2/sso/redirect
        signing-cert-paths:
          - /etc/saml/idp-signing.crt
      clock-skew-seconds: 60
      protected-paths:
        - /app/
        - /api/

Note de sécurité : Le chemin du certificat de signature de l’IdP doit pointer vers un fichier sur un système de fichiers sécurisé. Ne codez jamais le contenu d’un certificat dans les fichiers sources.

4. Protéger une route

@Configuration
@EnableWebSecurity
public class SecurityConfig {
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**", "/saml/acs", "/saml/metadata").permitAll()
                .anyRequest().authenticated()
            )
            .formLogin(AbstractHttpConfigurer::disable);
        return http.build();
    }
}

5. Traitement du callback ACS

Le SamlFilter traite automatiquement le callback ACS. La rotation de session a lieu à l’intérieur du SDK avant le stockage du principal. Votre code applicatif n’a pas besoin d’implémenter l’endpoint ACS.

6. Afficher l’utilisateur courant

@GetMapping("/me")
public String me(Model model, HttpSession session) {
    SamlPrincipal p = (SamlPrincipal) session.getAttribute("saml_principal");
    model.addAttribute("principal", p);
    return "me";
}

7. Déconnexion locale

La déconnexion locale détruit la session HTTP et supprime le cookie de session. SAML Single Logout (SLO) n’est pas implémenté en v1.0.0.

http.logout(logout -> logout
    .logoutUrl("/logout")
    .logoutSuccessUrl("/")
    .invalidateHttpSession(true)
    .deleteCookies("JSESSIONID")
);

10. Extensions différées (hors périmètre v1.0.0)

FonctionnalitéStatutComportement de repli
SAML Single Logout (SLO)DifféréDéconnexion locale uniquement ; session IdP conservée
Connexion initiée par l’IdPDifféréUniquement SP-initié
Assertions chiffréesDifféréSeules les assertions signées (non chiffrées) sont acceptées
Négociation du contexte d’authentificationDifféréAucun élément RequestedAuthnContext dans la requête
Fédération multi-IdP par SPDifféréUn seul TrustedIdp par instance