H· Hawiyati Documentation

Administration Guide

This guide covers everything available in the Hawiyati admin console — user and group management, application (SP) registration, authentication policy configuration, the adaptive risk engine, audit log search and export, SCIM provisioning, and system settings. Access the admin console at https://localhost:8095 or your configured hostname.

This guide covers everything available in the Hawiyati admin console — user and group management, application (SP) registration, authentication policy configuration, the adaptive risk engine, audit log search and export, SCIM provisioning, and system settings. Access the admin console at https://localhost:8095 or your configured hostname.

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 administration capabilities. For a full module map with ports, gRPC boundaries, and deployment topology, see the Implementation Guide.

Admin Console

The Hawiyati admin console is a WebFlux + Thymeleaf web application running on port 8095. It is the primary interface for all platform administration tasks.

Accessing the console

Navigate to https://localhost:8095 (development) or your configured admin hostname. On first login, use the bootstrap administrator credentials set during installation. All subsequent logins use Hawiyati's own authentication — the admin console is itself a protected application.

⚠
TLS Required

The admin console enforces HTTPS. Do not expose port 8095 on a public interface. In production, place it behind a private load balancer or VPN gateway accessible only to operations personnel.

Admin operator roles

Every admin account has one of three roles. Roles are set at account creation and cannot be self-elevated.

RoleBadgePermissions
SUPER_ADMIN Super Admin Full access — create/delete admin accounts, change system settings, view all audit logs, manage all entities
ADMIN Admin Manage users, groups, applications, policies, and risk configuration; cannot create/delete admin accounts or change system-wide settings
VIEWER Viewer Read-only access to all pages; cannot modify any configuration or user data. Suitable for auditors and on-call engineers who need visibility without write access.

Dashboard

The admin console home page shows a live snapshot of platform health:

—
Total users
—
Active sessions
—
Registered SPs
—
Failed logins (24h)

Navigation structure

Menu itemPurpose
UsersView, create, edit, suspend, and delete end-user accounts
GroupsCreate and manage groups used in policy conditions
KYC QueueReview and approve/reject identity document submissions
ApplicationsRegister SAML SPs and OIDC clients, assign policies
PoliciesCreate and manage authentication policy rule sets
Network ZonesDefine named IP CIDR ranges used in policy conditions
RiskConfigure the adaptive risk engine, signals, blocklists
Audit LogSearch and export structured security events
Live SessionsView active user sessions; revoke individual sessions
SettingsSystem-wide settings: session TTL, password policy, SMTP, LDAP, branding

Users & Groups

Hawiyati maintains a single identity schema for all users regardless of their origin — local accounts, LDAP/AD, SCIM-provisioned, or external SQL. The Users page shows accounts from the currently active user store.

User sources

SourceHow users arriveAuthentication
LOCAL Created by an admin or through self-service registration Argon2id-hashed password stored in Hawiyati's own DB
LDAP / Active Directory Synced from a directory server, or just-in-time on first successful login Pass-through LDAP bind — password never stored in Hawiyati
SCIM Pushed by an external HR/IGA/AD-sync system via the SCIM 2.0 API on port 8098 Local credential set by the provisioning system, or reset by the user
External SQL Users exist in a customer-managed relational database; Hawiyati reads them Password verified against the external database's hash
ℹ
Active Store

The active user store is set at Admin → Settings → User Stores. Switching stores takes effect immediately for new login attempts. Users from inactive stores remain in the database but cannot authenticate until their source is activated again.

User status model

The authoritative state is two boolean flags on the user record: active and pendingApproval. The admin console renders these as a computed status label.

Display statusactivependingApprovalCan authenticate?
ACTIVE true false Yes — full access
ACTIVE_LIMITED true true Limited — basic login only, no SP access until approved
INACTIVE false false No — account suspended
PENDING APPROVAL false true No — awaiting admin approval
MIGRATED UNCLAIMED false true + migrated flag No — bulk-imported, awaiting account claim by the real user
⚠
ACTIVE_LIMITED is computed

ACTIVE_LIMITED is a presentation label — it is not a database column. Do not look for it in the schema. The source of truth is always the two boolean flags. A user with active=true, pendingApproval=true has a valid credential but is restricted pending post-registration review.

Creating a user

Navigate to Admin → Users → Add User and complete the form.

FieldRequirementNotes
UsernameRequired3–30 chars; letters, digits, underscores, hyphens. Unique, immutable after creation.
EmailRequiredValid email address. Admin-created accounts are marked email_verified=true automatically.
PasswordRequiredMin 8 chars. Hashed with Argon2id on save — never stored in plaintext.
Phone numberOptionalE.164 format — e.g. +213555123456. Required for SMS OTP MFA.
First name, Last nameOptionalUsed in claims and email notification templates.
LocaleOptionalfr / en / ar. Affects notification email language. Defaults to fr.
✓
Immediate activation

Admin-created users can sign in immediately. No invitation email is sent unless you trigger one manually from the user's detail page (Send TOTP Invitation or Send Passkey Invitation).

Editing a user

Navigate to Admin → Users → [username] → Edit. Editable fields: email, phone number, first name, last name, locale, and active status.

⚠
Username is immutable

Username cannot be changed after creation — it is the stable lookup key used across audit logs, group memberships, and application session records. If the wrong username was used, create a new account and delete the old one (after verifying there is no open audit compliance requirement to retain the history).

Suspending an account

In Edit mode, set Active to off. Existing sessions are not terminated immediately — the user is blocked on the next request that requires session validation, or when their current session expires. To force immediate session termination, revoke active sessions from Admin → Live Sessions.

Deleting a user

Navigate to Admin → Users → [username] → Delete. This permanently removes the user record and all associated data: credentials, group memberships, consent records, device registrations, KYC submissions. Active sessions in Redis remain until TTL expiry.

⚠
Irreversible

Deletion is permanent. If you need to preserve the account for compliance review, suspend instead of deleting. Deletion removes all audit linkages for that username from the user record; the audit events themselves remain in audit_events.

Groups

Groups are named collections of users used as conditions in authentication policies. Navigate to Admin → Groups.

Group typeDescriptionMembership management
LocalCreated and managed in the Hawiyati consoleAdd/remove members via Admin → Groups → [group] → Members
LDAP / ADImported during directory syncRead-only in Hawiyati; managed in the directory server

Every membership change publishes an invalidation to the Redis sp-config:invalidate channel. Downstream policy caches clear within seconds — no service restart is needed.

✓
Best practice

Use groups, not per-user policy exceptions. Authentication policies operate on groups. Assigning users to named groups ("Privileged Users", "Contractors", "Remote Workers") makes policies predictable and auditable.


Credential Management

Administrators can manage all authentication factors for any user account. These are high-privilege operations — every action is logged.

Reset password

Navigate to Admin → Users → [username] → Reset Password. Sets a new password immediately. The previous password is invalidated. The new password must be at least 8 characters and is hashed with Argon2id before storage. Communicate the new password through a secure out-of-band channel — the admin console does not display the password after submission.

Logged as: end_user.reset_password

TOTP authenticator

Two options for admin-assisted TOTP enrollment:

A
Admin-assisted (in-person or screen-share)
Open Admin → Users → [username] → Enroll TOTP. The console generates a TOTP secret and QR code. The user scans with their authenticator app (RFC 6238-compatible), reads back the 6-digit code, and the admin enters it to activate. The secret is encrypted AES-256-GCM at rest.
B
Send enrollment invitation by email
For remote users: Admin → Users → [username] → Send TOTP Invitation Email. The system sends an email linking to the self-service TOTP enrollment page (/idp/enroll/totp). The user signs in with their password to verify identity, scans the QR code, and completes enrollment independently. Requires SMTP to be configured.

Reset TOTP: Removes the stored TOTP secret. The user's MFA preference reverts to PWD_ONLY until re-enrolled. Logged as: end_user.reset_totp

FIDO2 / Passkeys

FIDO2 credential registration must happen in the user's own browser — WebAuthn binds the credential to the user's device and the relying party ID. Administrators cannot register a passkey on behalf of a user.

Admin actionNav pathDescription
Send passkey invitation Admin → Users → [username] → Send Passkey Invitation Sends a branded email linking to /idp/fido2/enroll. User signs in, registers their passkey.
Clear all FIDO2 keys Admin → Users → [username] → Remove All Passkeys Deletes every registered FIDO2 credential. Use when a user loses all their devices. Logged as: end_user.delete_fido2.

KYC Review Queue

KYC manual review evidence and decision flow
Reviewers evaluate evidence consistently and record a reason for approval, retry, rejection, or escalation.

KYC (Know Your Customer) document verification is an optional registration step that requires users to submit a government-issued identity document. When enabled per registration policy, submitted documents appear in the KYC queue for admin review.

Navigate to Admin → KYC Queue. The queue shows all pending submissions in chronological order (oldest first).

ActionEffectAudit event
Approve Sets submission status to APPROVED and user's kyc_status to APPROVED. A confirmation email is sent if SMTP is configured. The user can now access applications that require KYC. kyc.approve
Reject Sets submission status to REJECTED. A rejection email is sent with the required rejection reason. The user may resubmit unless the policy prevents it. kyc.reject
✓
Rejection reason

Rejection reason is required and is sent to the user. Write clear, actionable reasons — for example: "Document image is blurry — please resubmit a clear photo of your national ID." Vague rejection messages increase re-submission errors and support tickets.

KYC status values

StatusMeaning
(none)User has not submitted any KYC documents
PENDINGDocuments submitted, awaiting admin review
APPROVEDDocuments verified and approved
REJECTEDReview completed; submission rejected — user may resubmit

Applications (Service Providers)

Service providers (SPs) are the applications that use Hawiyati as their identity provider. Navigate to Admin → Applications to manage SP registrations.

Adding a SAML SP

1
Obtain SP metadata
Download the SP's SAML metadata XML from the SP's metadata endpoint. If the SP doesn't have a metadata endpoint, collect: Entity ID (URN or URL), ACS URL (assertion consumer service endpoint), and optionally the SP's public certificate for signed AuthnRequests.
2
Create the SP registration
Navigate to Admin → Applications → Register SAML SP. Upload the metadata XML, or enter the Entity ID and ACS URL manually. The SP registration form also accepts a name, description, and logo URL for display purposes.
3
Provide IdP metadata to the SP
Download Hawiyati's IdP metadata from https://[hawiyati-host]/idp/saml2/metadata and import it into the SP. The metadata includes the IdP's Entity ID, SSO endpoint, and signing certificate.
4
Configure attribute mapping
In the SP's Attributes tab, define which user attributes to release in the SAML assertion. Common attributes: uid (username), email, givenName, sn, groups.
5
Assign an authentication policy
Under the SP's Authentication Policy tab, assign a policy. SPs with no policy assigned allow all logins without MFA.
✓
Test the integration
Use the SAML SP demo at port 8090 or initiate a login from your SP. Verify the assertion is accepted and attribute values are correct.

Adding an OIDC client

FieldRequirementNotes
Client IDAuto-generated or customUnique identifier for the OIDC client. Used in the client_id parameter.
Client secretAuto-generatedShown once at creation. Used only for confidential clients (server-side apps). Public clients use PKCE instead.
Redirect URIsRequired; one or moreExact match only. Wildcard URIs are not supported. Include all environments (dev, staging, prod) separately.
Grant typesRequiredauthorization_code (with PKCE) is the only supported grant for new integrations. refresh_token is available when enabled.
ScopesOptionalDefault: openid profile email. Additional scopes can be added per application.
Token lifetimeOptionalAccess token TTL (default: 300s), ID token TTL (default: 3600s), refresh token TTL (if enabled).

After creating the OIDC client, configure the SP to use the OIDC discovery document at: https://[hawiyati-host]/.well-known/openid-configuration


Authentication Policies

Policies control what happens when a user signs in to a service provider. Each policy contains an ordered list of rules. The IdP evaluates rules top-to-bottom and applies the first rule whose all conditions match (first-match semantics, like a firewall ruleset). If no rule matches, the default outcome is Allow.

Rule anatomy

Each rule answers four questions:

DimensionOptionsNotes
Who (group) Everyone or Members of a specific group ALL conditions in a rule are ANDed. For OR logic (Group A or Group B), create two separate rules at the same priority level.
Where (network zone) Anywhere or From a named network zone (CIDR list) Create network zones at Admin → Network Zones or inline from the rule editor.
When (time window) Any time or During a configured time window (days + HH:mm range) Time is evaluated against the server's local timezone. Document this in policy descriptions if the server timezone differs from users' locale.
Action Allow / Require MFA / Deny When Require MFA is selected, optionally restrict to specific methods: TOTP, FIDO2, EMAIL_OTP, SMS_OTP. Leave unchecked to accept any enrolled method.

Policy evaluation flow

1
Login request arrives
A user initiates login to a SAML SP or OIDC client. The SP is looked up and its assigned policy is loaded from cache (Redis-backed, ~10s TTL).
2
Rules evaluated in priority order
Rules are iterated from lowest priority number to highest. For each rule: check group condition → check network zone condition → check time condition. All three must match for the rule to fire.
3
First match wins
The first rule whose conditions all match applies its action: Allow, Require MFA, or Deny. No further rules are evaluated. This is identical to first-match firewall semantics.
4
Risk engine override (if enabled)
The adaptive risk engine runs in parallel. If the risk action is stricter than the policy action, the risk action wins. Strictness order: ALLOW < MFA_ANY < MFA_STRONG < DENY.
✓
Final action enforced
The stricter of the policy action and risk action is applied. The user sees a single, consistent authentication flow.

Common policy patterns

Require MFA for all users

Rule 1 (catch-all): Everyone / Anywhere / Any time → Require MFA

Office network bypass — MFA only from outside

Rule 1 (priority 1): Everyone / From zone "Office Network" / Any time → Allow Rule 2 (priority 2): Everyone / Anywhere / Any time → Require MFA

Strong MFA for privileged group, any MFA for others

Rule 1 (priority 1): Members of "Privileged Users" / Anywhere / Any time → Require MFA (TOTP, FIDO2) Rule 2 (priority 2): Everyone / Anywhere / Any time → Require MFA

Business-hours-only access

Rule 1 (priority 1): Everyone / Anywhere / During Mon–Fri 08:00–18:00 → Allow Rule 2 (priority 2): Everyone / Anywhere / Any time → Deny

After-hours step-up

Rule 1 (priority 1): Everyone / Anywhere / During Mon–Fri 08:00–18:00 → Allow Rule 2 (priority 2): Everyone / Anywhere / Any time → Require MFA
⚠
Rule ordering matters

A catch-all Allow rule at the top of the list will short-circuit every rule below it. Always put more specific rules (group-scoped, zone-scoped, time-scoped) before catch-all rules.

⚠
Orphaned group conditions

Deleting a group that is referenced by a policy condition does not automatically update the policy. The condition silently never matches. After deleting a group, review all policies that referenced it and remove or update the affected rules.

Assigning a policy to an SP

Navigate to Admin → Applications → [application] → Authentication Policy → Assign. Select the policy and save. Each SP can have at most one policy. To remove a policy without assigning a replacement, select "No policy (allow all)". Changes take effect immediately via Redis cache invalidation.


Network Zones

Network zones are named collections of IPv4 CIDR ranges used in authentication policy conditions. Navigate to Admin → Network Zones to manage zones independently, or create zones inline from the policy rule editor.

FieldDescription
NameUnique across all zones. Used in policy rule conditions.
DescriptionOptional. Document the purpose — e.g., "Corporate HQ office network 192.168.1.0/24".
CIDR rangesOne or more IPv4 CIDR blocks. A client IP must match any one CIDR in the zone. An empty CIDR list means the zone never matches.

Zone edits (add/remove CIDRs, rename) take effect immediately via Redis invalidation — no service restart required. Adding or removing CIDRs from a zone propagates instantly to all policies that reference that zone.


Risk Engine

The adaptive risk engine evaluates each authentication attempt against behavioral and contextual signals. Based on the resulting risk score, it can leave the policy decision unchanged, require stronger MFA, or block access entirely — automatically, at each login, alongside policy evaluation.

Operating modes

Set the mode at Admin → Risk → Settings → Mode.

ModeBehaviorWhen to use
OFF Risk assessment is skipped entirely. No signals evaluated. No overhead. Initial setup, troubleshooting, or when risk engine is not needed.
MONITOR Signals are evaluated and assessments recorded, but the risk action never overrides the policy action. Use to measure what enforcement would look like without affecting users. Pre-production tuning. Run for several days of real traffic and review the dashboard.
ENFORCE The risk action overrides the policy action when it is stricter. Production operating mode. After tuning in MONITOR mode and confirming acceptable false-positive rates.
✓
Recommended rollout

Start in MONITOR, review the dashboard for several days of real traffic, tune thresholds and weights, then switch to ENFORCE. False positives in MONITOR mode are visible without causing user impact.

Risk assessment pipeline

1
Login request arrives
Policy evaluation and risk assessment run in parallel for each login attempt.
2
Evaluate enabled signals
Each enabled signal evaluates the request and contributes 0–30 points. Points from all signals are summed and capped at 100.
3
Map score to risk level
The total score is mapped to LOW / MEDIUM / HIGH / CRITICAL using configurable thresholds. Signals can additionally set a minimum-level override that forces the level regardless of the numeric score.
4
Determine risk action
Each risk level maps to a risk action: LOW→ALLOW, MEDIUM→MFA_ANY, HIGH→MFA_STRONG, CRITICAL→DENY (defaults, configurable).
5
Stricter of policy vs risk wins
Strictness order: ALLOW < MFA_ANY < MFA_STRONG < DENY. The stricter of the policy action and risk action is applied. The user sees a single authentication flow.

Risk signals

NEW_DEVICE

Detects logins from an unrecognized browser/device. Hawiyati issues a hwd_id cookie (UUID, 400-day lifetime) to each browser. On each login, the cookie is checked against the user's known devices list.

FactorRisk contribution
KNOWN_DEVICE0 points — no additional risk
NEW_DEVICEMEDIUM — unrecognized device for a user with at least one known device on record
DEVICE_TRUST_EXPIREDMEDIUM — device was trusted but the trust window has lapsed
REVOKED_DEVICE_SEENHIGH — an admin-revoked device has reappeared

First login baseline: a user's very first login does not raise a NEW_DEVICE signal. Subsequent logins from a different browser do.

GEO_VELOCITY

Detects logins from physically implausible locations. Requires a MaxMind-format GeoIP2 database file (licensed separately; path configured at Admin → Risk → Settings → GeoIP Database).

FactorRisk contribution
GEO_OK0 points
NEW_COUNTRYMEDIUM — login from a country the user has not previously authenticated from
IMPOSSIBLE_TRAVELHIGH + HIGH minimum-level override — implied travel speed exceeds configured max (default: 900 km/h ≈ jet speed)

LOGIN_VELOCITY

Detects brute-force and credential-stuffing attacks by counting recent failed logins in a sliding time window (default: 15 minutes).

FactorThreshold (default)Risk
USER_FAILED_HIGH≥ 5 failed logins per username in windowMEDIUM-HIGH
IP_FAILED_HIGH≥ 10 failed logins per IP in windowMEDIUM-HIGH
IP_MANY_USERS≥ 5 distinct usernames attempted per IP in windowHIGH — credential-stuffing indicator

IP_REPUTATION

Checks the client IP against an administrator-maintained blocklist. Navigate to Admin → Risk → IP Reputation to import CIDR blocklists. Hawiyati does not ship with pre-loaded data.

FactorDescription
KNOWN_MALICIOUS_IPIP on a threat intelligence blocklist
CREDENTIAL_STUFFING_IPIP associated with credential-stuffing campaigns
TOR_EXITTor exit node
ANON_PROXYAnonymous proxy or VPN commonly used to hide origin
DATACENTERDatacenter or cloud provider IP range

Signal fail modes

Fail modeOn errorWhen to use
OPEN (default) Signal skipped — contributes no points. Assessment continues with other signals. Signals where availability matters more than conservative security (e.g., GEO_VELOCITY when GeoIP database may be unavailable)
CLOSED Signal contributes a HIGH minimum-level override — access requires FIDO2 MFA or better until the error is resolved. Security-critical signals where a database error should be treated as suspicious (e.g., IP_REPUTATION)

Risk level actions (defaults)

Risk levelDefault actionUser experience
LOWALLOWNo change to normal login flow
MEDIUMMFA_ANYPrompted for any enrolled second factor
HIGHMFA_STRONGPrompted specifically for FIDO2 hardware key or passkey
CRITICALDENYLogin blocked — "Access denied: risk level too high"

Override defaults at Admin → Risk → Level Actions.


Audit Logs

Hawiyati records a structured audit event for every security-relevant action — authentication attempts, configuration changes, user and group mutations, token issuance, and administrator activity. Navigate to Admin → Audit Log to search and export events.

Search filters

FilterBehavior
CategoryExact match. One of: authentication, configuration, iam, process, token, federation, access.
ActionExact match against the action code (e.g., authentication.login.success).
ActorPartial match (case-insensitive) against the actor's username.
OutcomeExact match: success, failure, or unknown.
From / ToInclusive time range. ISO 8601 format or date picker.
SearchFree-text search across the event message and resourceId fields.
ℹ
Audit queries are themselves audited

Every search an administrator performs is logged as an audit.query event in category access. Every export is logged as audit.export. The audit trail cannot be quietly reviewed — reviewing it always leaves a trace.

Event structure — always-present fields

FieldTypeDescription
@timestampISO 8601When the event occurred (UTC)
servicestringModule that emitted the event (e.g., hawiyati-http-server)
categorystringHigh-level category code
actionstringSpecific action code (e.g., authentication.login.success)
outcomestringsuccess, failure, or unknown
severitystringINFO for success/unknown; WARN for failure. Set automatically — cannot be overridden.
actorstringUsername of the person or system that performed the action
messagestringHuman-readable summary of the event

Export

Navigate to Admin → Audit Log → Export. Two formats:

FormatUse caseColumns / structure
CSV Spreadsheet analysis in Excel or Google Sheets 11 columns: event_time, source_service, category, action, outcome, severity, actor_username, source_ip, resource_type, resource_id, message. Formula injection protected (values beginning with =, +, -, @ are tab-prefixed).
JSON Log pipeline, SIEM ingestion, programmatic analysis Each row is a full event object (NDJSON). Sensitive detail keys auto-redacted to "***".

Maximum export size: 50,000 rows (configurable via hawiyati.audit.export.max-rows). For larger histories, narrow the time window and batch-export.

Event sinks (where events go)

SinkDefaultDescription
Structured JSON logAlways onWritten to the application log as NDJSON on the audit logger. Cannot be disabled. Route via Logback to a dedicated file for log-shipper ingestion.
Database (JPA async)OnPersisted to PostgreSQL audit_events table. Powers the in-console search interface. Async micro-batch writer: 100 events/flush, 1s flush interval, 10,000-event queue capacity.
CEF syslogOffCommon Event Format for SIEM ingestion (Splunk, QRadar, ArcSight). Enable with hawiyati.audit.cef.enabled: true.

Retention

Events cannot be deleted until they are at least 30 days old (configurable via hawiyati.audit.retention.min-days). A background job removes events older than the retention floor on a schedule. Set retention.enabled: false to accumulate indefinitely.


SCIM 2.0 Provisioning

SCIM user provisioning and reconciliation lifecycle
Provisioning operations and audit events are reconciled against the authoritative customer source.

SCIM (System for Cross-domain Identity Management) allows external systems — HR platforms, identity governance tools, AD sync agents — to create, update, and deactivate users in Hawiyati automatically via the SCIM 2.0 API on port 8098.

Enabling SCIM

1
Generate a SCIM token
Navigate to Admin → User Stores → SCIM Tokens → Generate Token. The plaintext token is shown once — copy it immediately. Only the SHA-256 hash is stored.
2
Configure your provisioning source
Set your provisioning system to send requests to https://[hawiyati-host]:8098/scim/v2/ with the header Authorization: Bearer <token>.
✓
Verify provisioning
Test by provisioning a single user and verifying they appear in the Admin → Users list with source_type = SCIM. Check Admin → Audit Log for end_user.create events with actor system.

SCIM API endpoints

MethodPathOperation
GET/scim/v2/UsersList users (paginated, filterable)
POST/scim/v2/UsersCreate a user
GET/scim/v2/Users/{id}Get a user by ID
PUT/scim/v2/Users/{id}Replace a user (full update)
PATCH/scim/v2/Users/{id}Update a user (partial)
DELETE/scim/v2/Users/{id}Delete a user
GET/scim/v2/ServiceProviderConfigDiscovery
GET/scim/v2/SchemasSchema discovery
⚠
Groups not supported

GET /scim/v2/Groups returns HTTP 501 Not Implemented. Group provisioning is on the roadmap. For now, manage group memberships through the admin console or direct API calls after SCIM user provisioning.

SCIM attribute mapping

SCIM attributeHawiyati fieldNotes
userNameusernameRequired, unique
emails[0].valueemailRequired
name.givenNamefirst_name
name.familyNamelast_name
phoneNumbers[0].valuephone_numberE.164 format required
preferredLanguagelocale
activeactiveSet to false to deactivate the account
urn:...externalIdexternal_idHawiyati SCIM extension field only
⚠
SCIM extension scope

The Hawiyati SCIM extension includes only: externalId, sourceInstanceId, pendingApproval. Credential, assurance level, and MFA fields are explicitly excluded from the SCIM schema — these are managed through Hawiyati's own admin interface or user self-service flows, never via SCIM.

Token security

SCIM tokens are validated by SHA-256 hash comparison — the plaintext token is never stored. An invalid or revoked token returns HTTP 401. Rotate tokens periodically: generate a new token, update the provisioning source, verify provisioning works, then revoke the old token. SCIM tokens do not expire automatically.


Settings & Branding

Navigate to Admin → Settings for system-wide configuration. Only SUPER_ADMIN accounts can modify settings.

Session settings

SettingDefaultDescription
Session TTL8 hoursHow long a Hawiyati session stays valid without user activity.
Session absolute timeout24 hoursMaximum session duration regardless of activity.
MFA grace period0How long a completed MFA step is remembered (skips repeat MFA prompt within the same session). 0 = MFA re-prompted on every SP access.
Concurrent session limitunlimitedMaximum simultaneous active sessions per user. Oldest sessions are terminated when the limit is exceeded.

Password policy

SettingDefaultDescription
Minimum length8Minimum password character count.
Require uppercasefalseAt least one uppercase letter required.
Require digitfalseAt least one digit required.
Require special characterfalseAt least one non-alphanumeric character required.
Password history0Number of previous passwords that cannot be reused. 0 = no history enforcement.
Lockout threshold10Failed consecutive login attempts before account is locked.
Lockout duration30 minutesHow long the account remains locked after threshold is hit. 0 = locked until admin unlocks.

Notification gateway (SMTP & SMS)

Setting groupFields
SMTP Host, port, TLS mode (STARTTLS / SSL), username, password, from address, from display name
SMS gateway HTTP endpoint URL, HTTP method (POST/GET), auth header, request body template, response success pattern

Test both gateways before relying on them for MFA OTP delivery — use the built-in send test functionality after configuration.

LDAP / Active Directory connector

FieldDescription
LDAP URLldap:// or ldaps:// server URL
Bind DNService account DN for Hawiyati to use when querying the directory
Bind passwordService account password — stored encrypted
User search baseDN under which to search for user objects
User search filterLDAP filter for user objects (e.g., (objectClass=person))
Username attributeLDAP attribute that maps to the Hawiyati username (e.g., sAMAccountName or uid)
Group search baseDN under which to search for group objects
Group membership attributeLDAP attribute on groups that lists member DNs (e.g., member)
Sync intervalHow often Hawiyati syncs the LDAP directory (default: 15 minutes)

External SQL Identity Store

Hawiyati can authenticate users directly against a customer-owned relational database (PostgreSQL, MySQL, or Microsoft SQL Server) without migrating the user table. On the first successful login, Hawiyati automatically creates a lightweight shadow record that carries the user's profile and group memberships — the password always stays in the external database.

Connection and table mapping

FieldDescription
NameHuman-readable label for this store (shown in the Admin console)
Database typePOSTGRES, MYSQL, or MSSQL
JDBC URLFull JDBC connection string, e.g. jdbc:postgresql://db.example.org:5432/myapp
DB usernameDatabase login that Hawiyati uses to run read-only queries
DB passwordStored AES-256 encrypted in Hawiyati's configuration database
User tableTable or view containing user records (default: users)
Username columnColumn holding the login name (default: username)
Password columnColumn holding the stored password hash (default: password_hash)
Email columnColumn mapped to the user's email address (default: email)
First name columnOptional — mapped to the user's given name
Last name columnOptional — mapped to the user's family name
Active columnOptional boolean column; when present, a false value blocks login
WHERE clauseOptional extra filter appended to every query, e.g. deleted_at IS NULL

Password hash algorithm

AlgorithmWhen to use
BCRYPTDefault. Works with hashes produced by bcrypt (any cost factor $2a, $2b, $2y).
ARGON2Argon2id hashes (Spring Security v5.8 defaults).
PBKDF2PBKDF2WithHmacSHA256 hashes.
SHA256Legacy plain SHA-256 hex digest. Migrate to bcrypt as soon as practical.

Activation

Configure and test the store first (Test connection button), then click Activate. Hawiyati immediately routes all new login attempts through the external database. To revert, click Deactivate — the active store reverts to Local and existing shadow users retain their profiles.

The activation API endpoints are: POST /api/v1/sql-stores/{id}/activate and POST /api/v1/sql-stores/{id}/deactivate.

User sync

Optional scheduled sync (Sync users button or cron) imports all rows from the external table and pre-creates shadow records. This is not required for login to work, but it lets admins search, group-assign, and pre-provision users before they first sign in.

Branding

SettingDescription
Organization nameShown in login page header, email templates, and consent pages
LogoUpload an SVG or PNG (max 200 KB). Displayed on the login page and account portal.
Primary colorHex color code applied to buttons and link accents on user-facing pages
Login page headingCustom text shown above the login form (supports plain text; HTML is escaped)
Support contactEmail or URL shown on error pages and the account portal help section
Privacy policy URLLinked on the self-service registration page and consent screens

Audit Event Reference

Every operation generates an audit event visible in Admin → Audit Log. Key events by category:

Authentication events

Action codeOutcomeTrigger
authentication.login.successsuccessUser authenticated successfully
authentication.login.failurefailureAuthentication failed (wrong credential, bad OTP, policy deny, etc.)
authentication.logoutsuccessUser signed out (IdP-initiated or SP-initiated SLO)
authentication.mfa.totp.successsuccessTOTP second factor passed
authentication.mfa.totp.failurefailureTOTP code invalid or expired
authentication.mfa.fido2.successsuccessFIDO2/WebAuthn assertion passed
authentication.mfa.fido2.failurefailureFIDO2 assertion failed
authentication.session.expiredunknownSession TTL elapsed without explicit logout

IAM (users & groups) events

Action codeTrigger
end_user.createAdmin creates a user
end_user.saveAdmin edits a user profile or status
end_user.reset_passwordAdmin resets a password
end_user.reset_totpAdmin removes TOTP enrollment
end_user.enroll_totpAdmin completes TOTP enrollment on behalf of user
end_user.delete_fido2Admin removes all FIDO2 credentials
end_user.approveAdmin approves a pending self-registration
end_user.rejectAdmin rejects a pending self-registration
end_user.deleteAdmin deletes a user account
user_group.createAdmin creates a group
user_group.add_memberAdmin adds a user to a group
user_group.remove_memberAdmin removes a user from a group
user_group.deleteAdmin deletes a group
kyc.approveAdmin approves a KYC document submission
kyc.rejectAdmin rejects a KYC document submission

Policy & configuration events

Action codeTrigger
auth_policy.createAdmin creates a new policy
auth_policy.save_rulesAdmin saves the rule list (full replace)
auth_policy.deleteAdmin deletes a policy
auth_policy.assign_spAdmin assigns a policy to a service provider
auth_policy.unassign_spAdmin removes a policy from a service provider
network_zone.createAdmin creates a network zone
network_zone.updateAdmin edits a zone
network_zone.deleteAdmin deletes a network zone
risk.settings.mode.updateRisk engine mode changed
risk.reputation.importIP reputation blocklist imported
risk.device.revokeAdmin revoked a known device

Best Practices

✓
Use groups, not per-user exceptions

Authentication policies operate on groups. Assign users to named groups ("Privileged Users", "Contractors", "Remote Workers") and write policies against those groups. Avoid policies that reference specific usernames — they are fragile, hard to audit, and don't scale.

✓
Audit MFA resets

Password and TOTP resets are high-privilege operations. A malicious or mistaken reset can downgrade a user's security posture. Review the audit log periodically for end_user.reset_password and end_user.reset_totp events and verify they were intentional.

✓
Suspend rather than delete when in doubt

Deletion removes all audit linkages for that username from the user record. If there is any chance you need the account history for compliance review, suspend the account first and delete only when retention requirements are confirmed.

✓
Rotate SCIM tokens periodically

Generate a new token, update the provisioning source, verify provisioning is working, then revoke the old token. SCIM tokens do not expire automatically — set a calendar reminder to rotate them quarterly.

✓
Test policy changes with a demo SP first

Assign the policy to the SAML SP demo (port 8090) or OIDC SP demo (port 8092) and walk through a test login before applying the policy to production applications. A misconfigured catch-all Deny rule will lock all users out of the SP immediately.

✓
Use MONITOR mode before enforcing risk controls

Run the risk engine in MONITOR mode for at least one week of real production traffic before switching to ENFORCE. The dashboard shows exactly how many additional challenges would have been issued — tune until the false-positive rate is acceptable.

✓
Refresh IP blocklists regularly

IP reputation data ages quickly. Use the expiry feature and a regular import cadence (weekly with Replace) to keep data current. Stale blocklist data is less harmful than no data — expired entries stop matching automatically.

HawiyatiDocumentation · v2026 · Spring Boot 3.5