H· Hawiyati Documentation

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

RequirementMinimum version
Java17
Spring Boot3.2.x
Hawiyati IdP2.0
Network accessSP → 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";
}
FieldTypeDescription
nameId()StringSubject NameID value
nameIdFormat()StringNameID format URI
attributes()Map<String, List<String>>SAML assertion attributes
sessionIndex()StringIdP session index
authnContextClassRef()StringAuthentication context class
notOnOrAfter()InstantSession expiry from the assertion
trustedIdpEntityId()StringEntity 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

FieldValue
SP Entity IDSame as hawiyati.saml.sp.entity-id
ACS URLSame 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)

FeatureStatusFallback behavior
SAML Single Logout (SLO)DeferredLocal logout only: session destroyed, IdP session remains active
IdP-initiated loginDeferredSP-initiated only; IdP-initiated POST requests are rejected
Encrypted assertionsDeferredOnly signed (unencrypted) assertions are accepted
AuthnContext class negotiationDeferredNo RequestedAuthnContext in AuthnRequest
Multi-IdP federation per SPDeferredExactly one TrustedIdp per SamlSpConfig