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érequis | Version minimale |
|---|---|
| Java | 17 |
| Spring Boot | 3.2.x |
| Hawiyati IdP | 2.0 |
| Accès réseau | SP → 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é | Statut | Comportement de repli |
|---|---|---|
| SAML Single Logout (SLO) | Différé | Déconnexion locale uniquement ; session IdP conservée |
| Connexion initiée par l’IdP | Différé | Uniquement SP-initié |
| Assertions chiffrées | Différé | Seules les assertions signées (non chiffrées) sont acceptées |
| Négociation du contexte d’authentification | Différé | Aucun élément RequestedAuthnContext dans la requête |
| Fédération multi-IdP par SP | Différé | Un seul TrustedIdp par instance |