H· Hawiyati Documentation

Integration Guide

Hawiyati supports SAML 2.0 and OpenID Connect (OIDC) for application federation. Choose the protocol that best fits your application type and existing infrastructure.

Hawiyati supports SAML 2.0 and OpenID Connect (OIDC) for application federation. Choose the protocol that best fits your application type and existing infrastructure.

Protocol Comparison

Hawiyati supports SAML 2.0 and OpenID Connect (OIDC) for application federation. Choose the protocol that best fits your application type and existing infrastructure.

Hawiyati IAM Platform — Component Architecture HAWIYATI IAM PLATFORM — COMPONENT ARCHITECTURE Spring Boot 3.5 · Java 25 · gRPC EXTERNAL ACTORS ENTRY LAYER & FEDERATION HTTPS · SAML 2.0 · OIDC · WebAuthn PLATFORM SERVICES HTTPS internal · gRPC DATA & INFRASTRUCTURE JDBC · Redis pub/sub · gRPC User Browser Browser · Mobile App Administrator Admin Console SAML Service Provider SAML 2.0 OIDC Relying Party OIDC · OAuth 2.0 SCIM Client HR System · Directory hawiyati-gateway Spring Cloud Gateway · :8080 Routing · TLS termination hawiyati-http-server IdP Login · MFA · FIDO2 · :8085 SAML ACS · OIDC callback · Account BFF hawiyati-federation SAML 2.0 · OIDC · :8087 Assertion & token issuance · Policy hawiyati-admin Admin Console · :8095 · WebFlux hawiyati-account Account Portal · :8096 · BFF/OIDC hawiyati-scim SCIM 2.0 API · :8098 hawiyati-session · :9004 hawiyati-cache · :9003 hawiyati-infra · :9002 PostgreSQL hawiyati · hawiyati_identity Redis / Valkey Sessions · Cache · Rate limits Audit & Logs CEF Syslog · OTel · SIEM PKI & Keystore SAML · OIDC · mkcert TLS External Actor External System Entry / Federation Platform Service gRPC Service Data Store

The sections below cover integration patterns. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

Dimension SAML 2.0 OIDC
Best for Enterprise web apps, legacy portals, SharePoint, SAP, Salesforce Modern web apps, SPAs, mobile apps, APIs
Config exchange XML metadata files (/saml/metadata) JSON discovery document (/.well-known/openid-configuration)
Response format Signed XML assertion (browser POST) JWT ID Token (back-channel token exchange)
Token transport Browser form POST to ACS URL Back-channel (server-to-server token request)
Session termination SAML SLO (fan-out to all SPs) RP-initiated logout (/oidc/logout)
Signature algorithm RSA-SHA256 (XML-DSig) RS256 (JWT)
PKCE support Not applicable Required (S256); prevents auth code interception
Library ecosystem Extensive for enterprise platforms; more complex Broad and modern; simpler to implement
Mobile/SPA suitability Poor (browser-only) Excellent (Authorization Code + PKCE)
Clock sensitivity ±30 seconds tolerance on assertion timestamps ±60 seconds tolerance on exp
Hawiyati status Production (custom stack — not OpenSAML) Production (custom stack — not Nimbus)
Recommendation Use SAML 2.0 for legacy enterprise applications that already have SAML SP support configured. Use OIDC for all new applications — it is lighter, uses standard JSON tokens, and has broader library support for modern frameworks and mobile apps.

SAML 2.0 — Use when

  • Target app already has SAML SP config (Salesforce, SAP, SharePoint)
  • Browser-based SSO required and OIDC is unavailable
  • Legacy vendor integration without OIDC support
  • Organisation policy mandates SAML for all SSO

OIDC — Use when

  • Building a new web app, SPA, or mobile app
  • Service-to-service authentication needed
  • Standard JWT library support preferred
  • Token refresh and offline access required

SAML 2.0 — Overview & Metadata

Hawiyati implements a custom SAML 2.0 Identity Provider stack. The first step in any SAML integration is exchanging metadata between the IdP and your Service Provider.

IdP Metadata Endpoint

Hawiyati publishes its IdP metadata at a well-known URL. Configure this URL in your SP, or download and upload the XML manually.

GET https://<idp-host>/saml/metadata
Content-Type: application/xml

# Development example:
GET https://dev.hawiyati.org:8085/saml/metadata
Metadata FieldValue
Entity IDConfigured via HAWIYATI_IDP_ENTITY_ID (dev default: http://localhost:8085)
SSO endpoint (HTTP-POST)https://<idp-host>/saml/sso
SSO endpoint (HTTP-Redirect)https://<idp-host>/saml/sso
SLO endpoint (HTTP-Redirect)https://<idp-host>/saml/slo
SLO endpoint (HTTP-POST)https://<idp-host>/saml/slo
WantAuthnRequestsSignedfalse (signed requests accepted but not required by default)
Certificate Note The metadata does not currently embed the IdP signing certificate. Obtain it separately from your Hawiyati administrator and upload it to the SP manually, or configure the SP to fetch and verify at runtime using the metadata URL.

SAML 2.0 — SP Registration

Register your Service Provider in Hawiyati using the admin console UI or by editing sp-registry.yml directly. Both methods write to the same underlying store.

Method A — Admin Console

1
Sign in to the admin console

Navigate to https://<admin-host>/ and sign in with an admin operator account.

2
Open Applications

Navigate to Applications in the left sidebar and click New Application.

3
Select SAML 2.0

Choose the SAML 2.0 protocol type and fill in the SP registration fields.

4
Save — no restart required

The SP is registered immediately. Changes propagate via Redis pub/sub within ~10 seconds.

Method B — sp-registry.yml (Infrastructure as Code)

Add the SP entry directly to dist/config/hawiyati-infra/sp-registry.yml. The infra service reloads on startup.

Minimal SAML entry

service-providers:
  - type: SAML
    entityId: https://app.example.com/saml/metadata
    displayName: Example Application
    active: true
    saml:
      acsUrl: https://app.example.com/saml/acs
      nameIdFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      wantAssertionsSigned: true

Full SAML entry with all options

service-providers:
  - type: SAML
    entityId: https://app.example.com/saml/metadata   # Must match SP's entityID exactly
    displayName: Example Application
    description: Finance department intranet portal
    logoUri: https://app.example.com/assets/logo.png
    contacts: [email protected]
    active: true
    acceptedAuthMethods: [pwd, totp, fido2]           # Empty = all methods
    saml:
      acsUrl: https://app.example.com/saml/acs
      metadataUrl: https://app.example.com/saml/metadata
      nameIdFormat: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
      assertionConsumerServiceBinding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
      singleLogoutServiceUrl: https://app.example.com/saml/logout
      singleLogoutServiceBinding: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect
      allowedAttributes: [email, displayName, groups]
      signatureRequired: false        # Require signed AuthnRequests
      wantAssertionsSigned: true      # Hawiyati signs the Assertion
      encryptAssertions: false        # Encrypt assertion for this SP
      signingCertPath:                # SP signing cert path (PEM)
      encryptionCertPath:             # SP encryption cert path (PEM)

SP Registration Reference

FieldRequiredDescription
entityIdYesThe SP's Entity ID. Must match exactly what the SP sends in its AuthnRequest Issuer.
displayNameYesHuman-readable name shown in the admin console
activeYesSet to false to disable the SP without removing it
acceptedAuthMethodsNoRestricts auth methods: pwd, totp, email_otp, sms_otp, fido2. Empty = all.
saml.acsUrlYesAssertion Consumer Service URL. Hawiyati POSTs the SAMLResponse here.
saml.nameIdFormatNoNameID format URI. Default: unspecified. See NameID formats below.
saml.singleLogoutServiceUrlNoSP SLO endpoint. Required for SLO to work.
saml.wantAssertionsSignedNoDefault true. Signs the Assertion element with IdP private key.
saml.signatureRequiredNoDefault false. Reject unsigned AuthnRequests when true.
saml.encryptAssertionsNoDefault false. Encrypts assertion with SP's public cert (AES-256-GCM + RSA-OAEP).
SAML service-provider initiated single sign-on sequence
The service provider validates request binding, signature, issuer, destination, audience, and time constraints.

SAML 2.0 — SP-Initiated SSO Flow

The standard SP-initiated SSO flow in 7 steps. Understanding each step is essential for debugging integration issues.

User Browser
Service Provider
Hawiyati IdP
DB / Redis
1
Browser→Service Provider
GET /app/resource — User requests a protected page; SP detects no active session
2
Service Provider→Browser
302 Redirect — SP constructs AuthnRequest (Base64+Deflate), redirects to IdP: GET /saml/sso?SAMLRequest=…&RelayState=…
3
Browser→Hawiyati IdP
IdP validates AuthnRequest: checks Issuer (SP EntityID), Destination, IssueInstant, optional signature. Checks for existing session cookie (fast path: skip login if valid session exists).
4
Hawiyati IdP↔Browser
IdP presents login page → User submits credentials → MFA challenge evaluated per SP auth policy (TOTP, FIDO2, OTP, etc.)
5
Hawiyati IdP↔DB / Redis
Verify password hash (Argon2id), load SP policy, evaluate risk score, write session to Redis (opaque token → HttpOnly cookie)
6
Hawiyati IdP→Browser
Auto-submit HTML form: POST /saml/acs — SAMLResponse contains Base64-encoded XML with RSA-SHA256 signed Assertion (NameID, attributes, AuthnContext, audience restriction, time bounds) and original RelayState
7
Browser→Service Provider
SP validates: XML-DSig signature, Audience restriction (must match EntityID), Recipient URL (must match ACS URL), NotOnOrAfter, InResponseTo matches request ID, replay detection → creates local session → redirects to original resource via RelayState
1
User accesses the SP

User navigates to a protected resource on the Service Provider (e.g., https://app.example.com/dashboard). The SP detects no active session.

2
SP builds AuthnRequest

The SP constructs a SAML AuthnRequest (Base64 + deflate encoded) and redirects the browser to the IdP SSO endpoint with the SAMLRequest and optional RelayState parameters.

GET https://<idp>/saml/sso
  ?SAMLRequest=<base64-deflate-encoded-authnrequest>
  &RelayState=<opaque-sp-state>
3
Hawiyati validates the AuthnRequest

Hawiyati decodes and validates: issuer (SP entityId), destination, format. Checks if an IdP session already exists for the browser cookie.

  • SSO fast path: existing valid session → issue assertion immediately
  • No session: store AuthnRequest, redirect to /idp/login
4
User authenticates at Hawiyati

User enters credentials on the Hawiyati login page. The authentication policy for this SP is evaluated. The user completes any required MFA steps (TOTP, FIDO2, OTP, etc.).

5
Hawiyati builds the signed SAMLResponse

Hawiyati constructs the assertion with: random Assertion ID, current timestamps, configured NameID, AuthnContext class, attribute statements, and XML-DSig signature (RSA-SHA256).

Assertion fields:
  NotBefore:    now − 30 seconds (clock-skew tolerance)
  NotOnOrAfter: now + 3600 seconds (1 hour)
  Recipient:    the SP's ACS URL
  Audience:     the SP's entityId
  Signature:    XML-DSig on the Assertion element (RSA-SHA256)
6
Browser auto-POSTs to ACS URL

Hawiyati sends an auto-submitting HTML form to the browser:

POST https://app.example.com/saml/acs
  SAMLResponse=<base64-encoded-xml>
  RelayState=<original-opaque-value>
7
SP validates and creates session

The SP validates: assertion signature, audience restriction (must match entityId), recipient (must match ACS URL), time conditions (NotOnOrAfter), InResponseTo matches original request ID, replay detection (store and reject seen assertion IDs). On success, creates a local session.

IdP-Initiated SSO Also supported. The request arrives at /saml/sso without an InResponseTo value. The SP must be configured to accept unsolicited responses for IdP-initiated flows to work.

SAML 2.0 — Attributes & NameID Formats

NameID Formats

FormatURIValueWhen to use
Unspecified (default)...nameid-format:unspecifiedUsernameSP accepts any string identifier
Email address...nameid-format:emailAddressUser's emailSP uses email as primary identifier and it is stable
Persistent...nameid-format:persistentInternal user UUIDDurable opaque identifier; does not expose PII
Transient...nameid-format:transientRandom per-sessionPrivacy-preserving; SP must be stateless

Attribute Mapping

Only attributes listed in allowedAttributes are released. If the list is empty, no attributes are released — only the NameID subject is asserted.

Attribute NameContent
emailUser's email address
displayNameFirst + last name, or username if not set
firstNameGiven name
lastNameFamily name
usernameAccount username
groupsComma-separated list of group names

Attribute format in assertion

<saml:AttributeStatement>
  <saml:Attribute Name="email"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name="displayName"
      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xsi:type="xs:string">Alice Martin</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>
Attribute Name Mapping Hawiyati uses simple short names (email, displayName). If your SP expects claim URIs (e.g., http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress), configure the mapping on the SP side.

SAML 2.0 — Single Logout (SLO)

Hawiyati supports both SP-initiated and IdP-initiated Single Logout. SLO terminates the IdP session and sends logout requests to all registered SPs that participated in the session.

User / SP
Hawiyati IdP
Other SPs
Redis Session
1
SP (or User)→Hawiyati IdP
SP sends LogoutRequest to GET /saml/slo?SAMLRequest=… (HTTP-Redirect binding) or user clicks logout on IdP portal
2
Hawiyati IdP↔Redis Session
IdP looks up session, finds all SPs with active session index entries for this user session
3
Hawiyati IdP→Other SPs
IdP fan-out: sends signed LogoutRequest to each participating SP's SLO endpoint. SPs destroy their local session and respond with LogoutResponse.
4
Hawiyati IdP→Redis Session
IdP invalidates the master session in Redis (session token revoked), clears session cookie
5
Hawiyati IdP→Initiating SP
IdP sends signed LogoutResponse (Status: Success) back to initiating SP. User is now fully logged out across all applications.

SP-Initiated SLO

1
SP sends LogoutRequest

The SP sends a SAML LogoutRequest to /saml/slo (HTTP-Redirect or HTTP-POST binding) including the SessionIndex from the original assertion.

2
Hawiyati terminates IdP session

The IdP session is invalidated in Redis. All session tokens are revoked.

3
Fan-out to other SPs

Hawiyati sends logout requests to all other SPs associated with the same IdP session that have singleLogoutServiceUrl configured. SP non-response is tolerated — IdP logout is not conditional on SP acknowledgment.

4
LogoutResponse returned

Hawiyati returns a LogoutResponse to the initiating SP, completing the SLO flow.

SLO Compatibility Warning SLO implementations vary significantly across vendors. Always test the full SLO flow end-to-end with each SP. Some SPs omit the SessionIndex or use a different binding than configured — check the audit log for the actual request content if logout does not work.

SLO Requirements

  • SP registration must include singleLogoutServiceUrl
  • SP must implement the SLO receiver endpoint and terminate its local session
  • SP must store the SessionIndex from the SSO assertion and include it in LogoutRequests

SAML 2.0 — Security Checklist

Before going to production, verify all of these on the SP side:

  • Validate assertion signature on every SSO response — never skip in production
  • Validate the Audience restriction matches your entityId exactly
  • Validate the Recipient in SubjectConfirmationData matches your ACS URL
  • Enforce time conditions: reject assertions where NotOnOrAfter has passed (±30s tolerance)
  • Implement replay detection: store and reject previously seen assertion IDs
  • Use HTTPS for your ACS URL in production — HTTP allows assertion interception
  • Never log raw assertion XML in production (contains PII)
  • Test SLO end-to-end — broken SLO allows sessions to persist after IdP logout
  • Plan for IdP certificate rotation — configure SP to accept two certs during overlap

SAML Troubleshooting

SymptomLikely CauseResolution
missing_saml_requestAuthnRequest not sent by SPVerify SP constructs and sends the SAMLRequest parameter
AudienceRestrictionViolationSP entityId mismatchCompare Audience in assertion to entityId in Hawiyati registration
RecipientMismatchACS URL mismatchUpdate acsUrl in SP registration to exactly match SP's ACS URL
SignatureValidationFailureWrong signing certificate in SPDownload IdP cert from /saml/metadata and re-upload to SP
InResponseToMismatchSession or cache mismatchEnsure SP stores AuthnRequest ID per browser session
SLO doesn't log out other appsMissing singleLogoutServiceUrlAdd SLO URL to all SP registrations that should participate
Clock failures (NotYetValid)Server clock skewSynchronize server clocks with NTP; Hawiyati applies ±30s tolerance

OIDC — Overview & Discovery

Hawiyati acts as an OpenID Connect Provider implementing OIDC Core 1.0 with the Authorization Code flow. Applications delegate authentication and receive a signed RS256 ID Token.

OIDC Discovery Document

Hawiyati publishes a discovery document — always use automatic discovery over hardcoded URLs.

GET https://federation.dev.hawiyati.org:8087/.well-known/openid-configuration
FieldValue
issuerConfigured per deployment (hawiyati.oidc.issuer)
authorization_endpoint{base-url}/oidc/authorize
token_endpoint{base-url}/oidc/token
userinfo_endpoint{base-url}/oidc/userinfo
jwks_uri{base-url}/oidc/jwks
end_session_endpoint{base-url}/oidc/logout

Supported Features

FeatureValue
Response typescode
Grant typesauthorization_code, refresh_token
Scopesopenid, profile, email, phone, address, offline_access
Signing algorithmRS256
PKCE methodsS256 (required), plain (not recommended)
Client auth methodsnone, client_secret_basic, client_secret_post
Subject typepublic (stable UUID per user)
Dynamic registrationNot supported — register via sp-registry.yml or admin console

OIDC — Client Registration

Every relying party must be registered in the SP registry before initiating authentication. Hawiyati does not support dynamic client registration.

Registration via sp-registry.yml

- type: OIDC
  entityId: my-app                          # unique identifier
  displayName: My Application
  description: Internal HR portal
  active: true

  oidc:
    clientId: my-app                        # sent in authorization requests
    clientName: My Application
    redirectUris:
      - https://app.example.com/callback    # exact match enforced — no wildcards
    postLogoutRedirectUris:
      - https://app.example.com/
    scopes: [openid, profile, email]
    responseTypes: [code]
    tokenEndpointAuthMethod: client_secret_basic
    clientSecret: ${MY_APP_CLIENT_SECRET}   # leave blank for public clients
    requirePkce: true
    frontchannelLogoutUri: https://app.example.com/logout/fc

Public Client (SPA/Mobile)

tokenEndpointAuthMethod: none
clientSecret:         # blank
requirePkce: true     # always required

Confidential Client (Server-side)

tokenEndpointAuthMethod: client_secret_basic
clientSecret: ${SECRET}
requirePkce: true     # still recommended
Redirect URI Matching Hawiyati enforces exact URI matching — no wildcards or prefix matches. Register every URI variant you will use, including http://localhost:8080/callback for development.
OIDC Authorization Code flow with PKCE
State, nonce, PKCE, issuer, signature, audience, and time validation bind the browser and token exchanges.

OIDC — Authorization Code Flow with PKCE

The only flow Hawiyati supports. PKCE (S256) is required for all public clients and strongly recommended for confidential clients.

User Browser
Client App
Hawiyati IdP
Token Store
1
Client App⚙Client App
Generate code_verifier (32 random bytes, base64url-encoded, 43 chars). Compute code_challenge = BASE64URL(SHA-256(verifier)). Generate state (CSRF) and nonce (replay). Store all in server-side session — never in browser.
2
Browser→Hawiyati IdP
GET /oidc/authorize?response_type=code&client_id=…&redirect_uri=…&scope=openid profile&state=…&nonce=…&code_challenge=…&code_challenge_method=S256
3
Hawiyati IdP↔Browser
IdP presents login page → User authenticates → MFA evaluated per SP policy → on success, authorization code generated (60 s TTL)
4
Hawiyati IdP→Browser
302 Redirect → redirect_uri?code=AUTH_CODE&state=… — App must verify state matches stored value (CSRF check) before proceeding
5
Client App→Hawiyati IdP
Server-to-server: POST /oidc/token — body: grant_type=authorization_code&code=…&redirect_uri=…&client_id=…&code_verifier=… — confidential clients add Basic Auth header
6
Hawiyati IdP↔Token Store
IdP verifies: SHA-256(code_verifier) == stored code_challenge; checks code not expired, not reused; loads session claims; signs ID Token (RS256)
7
Hawiyati IdP→Client App
JSON response: {"access_token":"…", "id_token":"…", "token_type":"Bearer", "expires_in":3600, "refresh_token":"…"}
8
Client App⚙Client App
Validate ID Token: fetch RS256 public key from /oidc/jwks → verify signature → check iss (matches discovery document), aud (matches client_id), exp (not expired), nonce (matches stored value, prevents replay)
1
Generate PKCE values and state

Before redirecting, generate PKCE pair, state (CSRF), and nonce (replay) on the server. Store them in the server-side session — never in the browser.

// code_verifier: 32 random bytes, base64url-encoded without padding (43 chars)
byte[] bytes = new byte[32];
new SecureRandom().nextBytes(bytes);
String codeVerifier = Base64.getUrlEncoder().withoutPadding()
    .encodeToString(bytes);

// code_challenge: SHA-256 of ASCII bytes of verifier, base64url-encoded
byte[] digest = MessageDigest.getInstance("SHA-256")
    .digest(codeVerifier.getBytes(StandardCharsets.US_ASCII));
String codeChallenge = Base64.getUrlEncoder().withoutPadding()
    .encodeToString(digest);

String state = UUID.randomUUID().toString();
String nonce = UUID.randomUUID().toString();
2
Redirect user to authorization endpoint
GET /oidc/authorize
  ?response_type=code
  &client_id=my-app
  &redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
  &scope=openid%20profile%20email
  &state=<random-state>
  &nonce=<random-nonce>
  &code_challenge=<base64url-sha256-of-verifier>
  &code_challenge_method=S256
3
User authenticates at Hawiyati

Hawiyati displays the login page, evaluates the authentication policy for this client, and prompts for any required MFA. On success, redirects back with an authorization code.

4
Handle the callback
GET /callback?code=<authorization-code>&state=<your-state>

// Verify state matches session — this is the CSRF check
// Authorization codes expire in 60 seconds — exchange immediately
5
Exchange code for tokens (server-to-server)
POST /oidc/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>  # confidential clients

grant_type=authorization_code
&code=<received-code>
&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback
&client_id=my-app
&code_verifier=<original-code-verifier>
6
Receive ID Token + Access Token
{
  "access_token":  "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "id_token":      "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_...",          // only with offline_access scope
  "token_type":    "Bearer",
  "expires_in":    3600,
  "scope":         "openid profile email"
}
TokenLifetime
Authorization code60 seconds
Access token3600 seconds (1 hour)
ID token3600 seconds (1 hour)
Refresh token2,592,000 seconds (30 days)
7
Validate the ID Token

Never skip validation. Perform all checks before establishing a user session.

  1. Decode JWT header; verify alg is RS256
  2. Fetch public key from JWKS using kid from header
  3. Verify RS256 signature against the public key
  4. Verify iss matches the discovery document issuer
  5. Verify aud equals your client_id
  6. Verify exp > now (±60s clock skew tolerance)
  7. Verify nonce matches value stored in session
  8. Use sub (not email) as the stable user identifier
8
(Optional) Fetch UserInfo

For additional claims or fresher data, call the UserInfo endpoint with the access token.

GET /oidc/userinfo
Authorization: Bearer <access_token>

OIDC — Token Claims & Key Management

Standard ID Token Claims

ClaimDescription
issIssuer — Hawiyati's configured OIDC issuer
subSubject — stable internal user UUID (use this as the user identifier)
audAudience — your client_id
expExpiry (Unix epoch)
iatIssued-at (Unix epoch)
auth_timeWhen the user actually authenticated
azpAuthorized party — your client_id
nonceEcho of the nonce from the authorization request
at_hashLeft-most 128 bits of SHA-256(access_token), base64url-encoded

Scope-Driven Claims

ScopeClaims Included
profilename, given_name, family_name, preferred_username, picture, locale, birthdate
emailemail, email_verified
phonephone_number, phone_number_verified
addressaddress (structured: formatted, street_address, locality, region, postal_code, country)
Missing Claims Claims are only present when the underlying attribute exists in the user record. Missing attributes are silently omitted — Hawiyati does not fail the authentication. Design your SP to handle optional claims gracefully.

JWKS Key Management

GET /oidc/jwks

{
  "keys": [
    {
      "kty": "RSA",
      "alg": "RS256",
      "use": "sig",
      "kid": "hawiyati-signing-key-1",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

Use the kid from the JWT header to select the matching key. Cache the JWKS response and refresh only on encountering an unknown kid.

Attribute Mapping (LDAP / AD Compatibility)

OIDC ClaimAttribute Keys Checked (first non-blank wins)
namename, displayName, cn
given_namegiven_name, firstName, givenName
family_namefamily_name, lastName, familyName, sn
preferred_usernamepreferred_username, username, uid, samAccountName
emailemail, mail
phone_numberphone_number, phoneNumber, mobile, telephoneNumber

OIDC — Logout

RP-Initiated Logout

To terminate the Hawiyati session, redirect the user's browser to the end-session endpoint:

GET /oidc/logout
  ?id_token_hint=<id_token>
  &post_logout_redirect_uri=https%3A%2F%2Fapp.example.com%2F
  &state=<optional-state>
Dual Session Invalidation Required Terminating the Hawiyati session does not automatically destroy your application's session. Invalidate your own session before or immediately after initiating the redirect. The post_logout_redirect_uri must be registered in your client's postLogoutRedirectUris — unregistered URIs are silently ignored. Hawiyati identifies your client from id_token_hint (or a client_id parameter); without either, the user ends on the Hawiyati sign-in page instead of your URI.

Back-Channel Logout

Implemented (2026-06-20). When a user logs out of Hawiyati, the IdP POSTs a signed logout_token JWT to the backchannelLogoutUri registered for your application. Register the URI on the SP configuration form in the admin console. Your endpoint must return 200 OK; errors are logged but do not abort the logout flow.

Token Refresh

POST /oidc/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=refresh_token
&refresh_token=<stored-refresh-token>
&client_id=my-app

Refresh tokens expire after 30 days. If expired, the user must re-authenticate. The refresh token may be rotated — always store the latest one returned.

OIDC — Integration Examples

Spring Boot (Confidential Client)

# application.yml
spring:
  security:
    oauth2:
      client:
        registration:
          hawiyati:
            client-id: my-app
            client-secret: ${MY_APP_CLIENT_SECRET}
            authorization-grant-type: authorization_code
            redirect-uri: "{baseUrl}/login/oauth2/code/hawiyati"
            scope: openid, profile, email
            client-authentication-method: client_secret_basic
        provider:
          hawiyati:
            issuer-uri: https://federation.dev.hawiyati.org:8087

Node.js (Public Client with PKCE)

import { generators, Issuer } from 'openid-client';

const issuer = await Issuer.discover(
  'https://federation.dev.hawiyati.org:8087'
);

const client = new issuer.Client({
  client_id: 'my-spa',
  redirect_uris: ['https://app.example.com/callback'],
  response_types: ['code'],
  token_endpoint_auth_method: 'none',
});

// Step 1 — generate authorization URL
const codeVerifier  = generators.codeVerifier();
const codeChallenge = generators.codeChallenge(codeVerifier);
const state         = generators.state();
const nonce         = generators.nonce();

req.session.pkce = { codeVerifier, state, nonce };

const authUrl = client.authorizationUrl({
  scope: 'openid profile email',
  state, nonce,
  code_challenge: codeChallenge,
  code_challenge_method: 'S256',
});
res.redirect(authUrl);

// Step 2 — on callback
const { codeVerifier, state, nonce } = req.session.pkce;
const params   = client.callbackParams(req);
const tokenSet = await client.callback(
  'https://app.example.com/callback',
  params,
  { code_verifier: codeVerifier, state, nonce }
);
const claims = tokenSet.claims();
// Use claims.sub as the stable user identifier

OIDC — Security Checklist

  • state parameter validated on every callback — CSRF protection
  • nonce validated in the ID Token — replay protection
  • aud validated against your own client_id
  • Token signature verified using JWKS public key — never skipped in any code path
  • code_verifier generated with ≥32 bytes entropy, stored server-side only
  • Token exchange (POST /oidc/token) made server-to-server — never from browser
  • client_secret in environment variables or secrets manager — not in source code
  • All redirect URIs are HTTPS in production
  • ID Token exp checked before accepting the token
  • sub (not email) used as the stable user identifier
  • Logout terminates both Hawiyati session and your own application session
SCIM provisioning and reconciliation lifecycle
Stable external identifiers and reconciliation keep the customer source and Hawiyati account state aligned.

SCIM 2.0 — Inbound Provisioning & Outbound Push

Hawiyati acts as a SCIM 2.0 server for inbound user and group provisioning, and as a SCIM 2.0 client for outbound push to downstream applications. Your Identity Governance tool (e.g., AD, Okta, or a custom provisioner) acts as the upstream SCIM client; Hawiyati then fans out lifecycle events to configured downstream SCIM targets.

Inbound + Outbound Hawiyati supports both directions: it accepts SCIM provisioning from upstream IdM systems (inbound) and pushes user lifecycle events (create, update, delete) to downstream SCIM-capable applications (outbound). Configure outbound targets in the admin console under SCIM › Outbound Push Targets.

Supported Endpoints

EndpointMethodsDescription
/scim/v2/UsersGET, POST, PATCH, DELETEUser resource management
/scim/v2/Users/{id}GET, PUT, PATCH, DELETEIndividual user operations
/scim/v2/GroupsGET, POST, PATCH, DELETEGroup resource management
/scim/v2/Groups/{id}GET, PUT, PATCH, DELETEIndividual group operations
/scim/v2/ServiceProviderConfigGETSCIM server capabilities
/scim/v2/SchemasGETSchema definitions

SCIM Extension Schema

Hawiyati exposes a custom SCIM extension schema. Only the following extension attributes are supported:

Extension FieldTypeDescription
externalIdstringSP's own user identifier; stored in users.external_id
sourceInstanceIdstringIdentifies which SP instance provisioned this user
pendingApprovalbooleanSets the pendingApproval flag on the user account
Explicitly Excluded Fields The SCIM extension does NOT support credential, assurance level, or KYC fields. Sending these fields in a SCIM request will result in an error or be silently ignored depending on the field. Assurance levels are set exclusively through the KYC workflow — never via SCIM.

Provisioning Flow

1
SP provisions user via POST /scim/v2/Users

The user account is created in Hawiyati with active=false, pendingApproval=true — the MIGRATED_UNCLAIMED state.

2
Claim token generated

A 256-bit random claim token is generated (HMAC-SHA256 stored, 15-minute TTL, single-use). A claim link is returned or emailed to the user.

3
User follows the claim link

User arrives at Hawiyati, completes identity verification, enrolls credentials, and claims the account.

4
Account transitions to ACTIVE

active=true, pendingApproval=false. User can now authenticate to registered SPs.

Authentication

Authorization: Bearer <scim-bearer-token>

Configure the bearer token in the Hawiyati admin console under SCIM settings. Rotate tokens regularly and store them in a secrets manager.

Example: Create User

POST /scim/v2/Users
Authorization: Bearer <token>
Content-Type: application/json

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:hawiyati:scim:extension"
  ],
  "userName": "[email protected]",
  "name": { "givenName": "Alice", "familyName": "Martin" },
  "emails": [{ "value": "[email protected]", "primary": true }],
  "phoneNumbers": [{ "value": "+213555001234", "primary": true }],
  "active": true,
  "urn:hawiyati:scim:extension": {
    "externalId": "ext-user-9876",
    "sourceInstanceId": "sp-finance-prod",
    "pendingApproval": true
  }
}

Deactivating a User

PATCH /scim/v2/Users/{id}
Authorization: Bearer <token>
Content-Type: application/json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{ "op": "replace", "path": "active", "value": false }]
}

FIDO2 / WebAuthn / Passkeys

Hawiyati supports FIDO2/WebAuthn for phishing-resistant authentication. Only the public key is stored — the private key never leaves the authenticator device.

Registration Flow

1
Server issues registration challenge

Hawiyati generates a random challenge and a PublicKeyCredentialCreationOptions object including the RP ID, user handle, and supported algorithms.

2
Browser calls navigator.credentials.create()

The browser (or platform) invokes the authenticator (hardware key or platform authenticator — Face ID, Touch ID, Windows Hello) to generate a new key pair.

3
Attestation returned to server

The authenticator returns the public key credential including: credential ID, public key, attestation statement, client data JSON. The private key never leaves the device.

4
Server stores public key

Hawiyati verifies the attestation, stores the public key and credential ID in user_credentials. Registration complete.

Authentication Flow

1
Server issues authentication challenge

Hawiyati generates a random challenge and a PublicKeyCredentialRequestOptions object with the list of allowed credential IDs for this user.

2
Browser calls navigator.credentials.get()

The browser invokes the authenticator to sign the challenge with the private key. User gesture required (biometric or PIN).

3
Assertion returned and verified

Hawiyati verifies the signature against the stored public key, checks the challenge, origin, and RP ID binding, and increments the signature counter (replay detection). Authentication succeeds.

Authenticator Types

TypeExamplesNotes
Hardware security keyYubiKey 5, FIDO2-compliant tokensCross-device; requires physical possession; phishing-resistant
Platform authenticatorFace ID, Touch ID, Windows Hello, Android biometricsPasskey; bound to device; may sync to cloud (iCloud/Google)

Browser Support

Browser/PlatformHardware KeyPlatform Auth / Passkey
Chrome 89+ (Windows/macOS/Linux)YesYes (Windows Hello / Touch ID)
Firefox 60+YesPartial (platform auth varies by OS)
Safari 14+ (macOS/iOS)YesYes (Touch ID / Face ID)
Edge 18+YesYes (Windows Hello)
Android ChromeYes (via USB OTG / NFC)Yes (Android biometrics)
iOS Safari 16+Yes (NFC/Lightning)Yes (Face ID / Touch ID passkey)

Admin Management

Administrators can view and manage registered FIDO2 credentials for a user in the admin console under Users → [user] → Credentials. Available actions: view credential list (name, registration date, last used), deregister a credential, force re-enrollment, send enrollment invitation.

Go-Live Checklist

Use this checklist before cutting over to production. All items must pass before go-live.

Pre-Production

  • IdP metadata exchanged with all SPs and verified in staging
  • SP-initiated SSO tested end-to-end for each SP
  • Attribute mapping verified (NameID, email, groups reach SP correctly)
  • SAML SLO tested — logout propagates to all SPs
  • OIDC discovery document fetched and all endpoints verified
  • OIDC token exchange tested — ID token validated server-side
  • PKCE flow tested for public clients
  • MFA enrolled on all test accounts; MFA challenge flow verified
  • Risk engine mode confirmed (MONITOR for initial rollout recommended)
  • Authentication policy rules reviewed and tested
  • Audit log streaming to SIEM configured and verified
  • TLS certificates valid (not self-signed in production); HSTS configured
  • SCIM provisioning tested — create, update, deactivate flows verified
  • FIDO2 registration and authentication tested on target browsers/devices

Production Cutover

  • DNS records updated to production hostname
  • SP metadata updated with production IdP URLs
  • Monitoring alerts configured (login failure rate, error rate, latency)
  • Rollback plan documented and tested
  • On-call runbook available and team briefed
  • First-user test login performed post-cutover

First-Week Post Go-Live

  • Review audit logs daily for unexpected auth failures or patterns
  • Confirm risk engine is not producing false positives (CRITICAL risk on legitimate users)
  • Verify SLO is working correctly across all SPs
  • Check that SCIM provisioning events are processing without queue backlog
  • Confirm IdP signing certificate rotation plan is documented
  • Review support tickets for integration issues and resolve within SLA
Risk Engine Recommendation Start with the risk engine in MONITOR mode for the first two weeks of production. This lets you observe risk signals and scoring without blocking users, giving you time to tune thresholds before switching to ENFORCE mode.
HawiyatiDocumentation · v2026 · Spring Boot 3.5