Java/Spring Boot Integration Guide
Integrate Hawiyati SAML2 SP SDK with Java/Spring Boot applications. Covers Maven dependency, minimum configuration, route protection, ACS callback handling, logout, and SP registration.
1. Prerequisites
| Requirement | Minimum version |
|---|---|
| Java | 17 |
| Spring Boot | 3.2.x |
| Hawiyati IdP | 2.0 |
| Network access | SP → IdP on port 443 |
The SP and IdP clocks must be synchronized to within 5 minutes. Use NTP in all environments. The default clock-skew tolerance is 60 seconds.
2. Add the dependency
Add the Spring Boot starter to your pom.xml:
<dependency>
<groupId>org.hawiyati</groupId>
<artifactId>saml-sp-spring-boot-starter</artifactId>
<version>1.0.0</version>
</dependency>
For multi-instance deployments, also add the Redis adapter:
<dependency>
<groupId>org.hawiyati</groupId>
<artifactId>saml-sp-redis</artifactId>
<version>1.0.0</version>
</dependency>
3. Minimum configuration
Add the following to 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/
Security note: The IdP signing certificate path must point to a file on a secured filesystem or a classpath resource that is not part of your SCM-tracked source tree. Never hardcode certificate content in source files.
4. Protect a route
The auto-configuration registers SamlFilter at servlet-filter order -100. For Spring MVC applications with Spring Security:
@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. Handle the ACS callback
The SamlFilter handles the ACS callback automatically. Session rotation occurs inside the SDK before the principal is stored. Your application code does not need to implement the ACS endpoint.
To react immediately after a successful ACS callback, implement SamlPrincipalHook:
@Component
public class AuditingPrincipalHook implements SamlPrincipalHook {
@Override
public void onAuthenticated(SamlPrincipal principal,
HttpServletRequest request, HttpServletResponse response) {
auditLog.record("SAML_LOGIN", principal.trustedIdpEntityId());
}
}
6. Display the current user
@GetMapping("/me")
public String me(Model model, HttpSession session) {
SamlPrincipal p = (SamlPrincipal) session.getAttribute("saml_principal");
model.addAttribute("principal", p);
return "me";
}
| Field | Type | Description |
|---|---|---|
nameId() | String | Subject NameID value |
nameIdFormat() | String | NameID format URI |
attributes() | Map<String, List<String>> | SAML assertion attributes |
sessionIndex() | String | IdP session index |
authnContextClassRef() | String | Authentication context class |
notOnOrAfter() | Instant | Session expiry from the assertion |
trustedIdpEntityId() | String | Entity ID of the authenticating IdP |
7. Local logout
Local logout destroys the HTTP session and clears the session cookie. SAML Single Logout (SLO) is not implemented in v1.0.0 — see Section 10.
http.logout(logout -> logout
.logoutUrl("/logout")
.logoutSuccessUrl("/")
.invalidateHttpSession(true)
.deleteCookies("JSESSIONID")
);
Include a CSRF token in every logout form:
<form th:action="@{/logout}" method="post">
<input type="hidden" name="_csrf" th:value="${_csrf.token}"/>
<button type="submit">Sign out</button>
</form>
8. Local user mapping
Implement LocalAccountResolver to map a SAML principal to a local user account after assertion validation. The default PassThroughLocalAccountResolver accepts every authenticated principal. Override it by declaring your own bean.
@Component
public class AppLocalAccountResolver implements LocalAccountResolver {
@Override
public AuthenticatedPrincipal resolve(SamlPrincipal principal)
throws LocalAccountResolutionException {
String nameId = principal.nameId();
return users.findByNameId(nameId)
.map(u -> mapToAuthenticated(u, principal))
.orElseGet(() -> provisionNewUser(nameId, principal));
}
}
Throw UnknownLocalAccountException or AccountDisabledException to reject users — both produce HTTP 403.
9. SP registration in Hawiyati
The SDK exposes SP metadata at: GET https://app.example.com/saml/metadata
| Field | Value |
|---|---|
| SP Entity ID | Same as hawiyati.saml.sp.entity-id |
| ACS URL | Same as hawiyati.saml.sp.acs-url |
| Metadata URL (optional) | https://app.example.com/saml/metadata |
After registration, download the IdP signing certificate from Admin → IdP → Certificates → Download PEM and place it at the path referenced in idp.signing-cert-paths.
10. Deferred extensions (not in v1.0.0)
| Feature | Status | Fallback behavior |
|---|---|---|
| SAML Single Logout (SLO) | Deferred | Local logout only: session destroyed, IdP session remains active |
| IdP-initiated login | Deferred | SP-initiated only; IdP-initiated POST requests are rejected |
| Encrypted assertions | Deferred | Only signed (unencrypted) assertions are accepted |
| AuthnContext class negotiation | Deferred | No RequestedAuthnContext in AuthnRequest |
| Multi-IdP federation per SP | Deferred | Exactly one TrustedIdp per SamlSpConfig |