SSO & LDAP Configuration

This guide is for tenant administrators and account owners who integrate Waqti with corporate identity systems. It reflects how the tenant application wires SSO login, SAML 2.0, and LDAP directory synchronization.

Single sign-on (SSO) overview

Waqti stores SSO provider definitions per tenant on the central database. Each provider has a type (for example Google Workspace, Microsoft Entra ID, or SAML 2.0), display name, active flag, and type-specific secrets and endpoints.

End users see SSO on the tenant login experience: the app can list available providers for the current tenant. Choosing a provider starts the login flow; successful authentication creates or matches a user session and redirects to the dashboard.

OAuth-style providers (Google, Entra)

For OAuth-based providers, Waqti builds an authorization URL and sends the user to the identity provider. After consent, the provider redirects back to Waqti’s callback route with an authorization code (and state for CSRF protection).

The callback exchanges the code, maps profile attributes to Waqti users (email, name, and related fields per provider defaults), and provisions or links accounts according to your provider configuration (auto provision and default role are stored on the provider record).

Supported OAuth provider constants in the product include:

• Microsoft Entra ID (entra) — attribute mapping for email, display name, given name, surname.
• Google Workspace (google) — mapping for email, name, given name, family name, picture.

When registering your OAuth app with the vendor, configure the redirect URI to match Waqti’s tenant callback URL pattern (the application route named for SSO callback, scoped to your tenant host). The login entry point resolves the provider by numeric ID or by provider key (for example google) when a single active provider matches.

SAML 2.0

For SAML, the service provider exposes:

• Assertion Consumer Service (ACS) — HTTP POST endpoint that receives SAMLResponse from the IdP.
• Metadata — XML document describing the SP that you import into your IdP (entity ID, bindings, certificates as generated by the application).

The SAML handler validates the response, applies attribute mapping (defaults cover common email and name attributes; custom mapping can be stored on the provider), and signs the user in on success.

Single logout (SLO) is routed through a dedicated SAML logout path: the controller ends the local session and invalidates the session cookie, then returns the user to the login page. Coordinate full IdP-initiated SLO with your identity architect if you require global logout at the organization.

Activating providers

Only providers marked active participate in login. Inactive providers return an error if someone attempts to use them. Each provider row is scoped to one tenant; cross-tenant use is rejected with 403 at runtime.

Provider records include optional client ID and client secret (OAuth), external tenant identifiers where Entra requires them, and for SAML: IdP entity ID, IdP SSO URL, optional SLO URL, IdP signing certificate, SP entity ID, NameID format, and attribute mapping JSON.

If your organization receives provider setup from Waqti support or a central console, verify names and activation flags before go-live.

LDAP directory integration

LDAP connects Waqti to Active Directory, OpenLDAP, or Oracle Fusion directory layouts supported by the built-in service. Configuration lives on the tenant record (encrypted bind password, JSON ldap_config).

Access control

Only tenant administrators and the account owner may open LDAP settings, save configuration, test the connection, or run sync jobs.

Connection parameters

When saving LDAP settings, the application validates:

Field	Purpose
Enabled	Turns LDAP on or off for the tenant
Directory type	active_directory, openldap, or oracle_fusion
Host	LDAP server hostname
Port	LDAP port (defaults to 389 if omitted)
Use SSL / TLS	Transport security flags
Base DN	Search root for users and groups
Bind DN	Service account performing searches
Bind password	Encrypted at rest; leave masked (********) to keep the previous secret
User filter	LDAP filter for users (default includes users with mail)
Group filter	Filter for organizational units / groups (default objectClass-based)
Sync interval	hourly, daily, weekly, or manual
Auto-create users	Create Waqti users for new directory entries
Auto-create departments	Create departments from directory structure
Default role	Optional role applied to newly provisioned users
Field mappings	Attribute mapping per directory type

The settings screen exposes supported directory types and field mapping templates per type so administrators align attributes (for example mail, cn) with Waqti user fields.

Test connection

Use Test connection with live host, bind DN, and password. If you submit the masked placeholder password, the server attempts to decrypt the stored secret for the test. A decryption failure returns a clear error asking you to re-enter the password.

Sync users

Sync users connects with the saved configuration, runs the user import pipeline, updates ldap_last_sync, and reports created, updated, skipped, and optional error counts. LDAP must be enabled and configuration must be non-empty; otherwise the action errors with a localized “not configured” message.

Sync departments

Sync departments imports or updates organizational units as departments using the group filter and directory structure. Results summarize created and updated rows.

Run a test after any firewall, credential, or base DN change before scheduling broad syncs.

Unlinking SSO identities (end users)

While SSO providers are tenant-level, linked identities belong to individual users. On Settings → Security, users see active SSO providers for the tenant and their own linked accounts (provider name, email on file, last login).

A user may unlink a linked identity if they still have a viable sign-in method: the application blocks unlinking when there is no password and no other linked identity, to prevent account lockout.

After unlinking, the user signs in with password or another provider as usual.

Operational checklist

1. DNS and TLS — Tenant hostname resolves correctly; certificates trusted by IdP and browsers.
2. Redirect / ACS URLs — Match exactly what is registered in Entra, Google, or SAML IdP.
3. Clock skew — SAML validity windows require reasonable NTP on app servers and IdP.
4. Secrets rotation — Update client secrets and LDAP bind passwords in Waqti when IT rotates them; run test immediately after.
5. Pilot — Enable one provider for a pilot group before org-wide enforcement.

Related topics

• Security — broader security practices
• Users — roles and invitations