Overview

Sign in with Enjab Auth is the central login for every Enjab tool. It is an OAuth 2.0 authorization code flow (with an extra feature: the token response includes the user's profile and roles, so you usually need no extra call).

• Issuer: https://auth.enjab.ae
• Discovery: https://auth.enjab.ae/.well-known/openid-configuration

What Enjab Auth does (and does not)

Enjab Auth handles all authentication: passwords, two-factor authentication (TOTP), sessions, lockout. Your tool never sees a password or a 2FA code and never builds a login screen. It enforces a strong password policy (12 to 24 characters, mixed character classes, never the person's name), a forced password change on first login (and after an admin reset) before anything else, and mandatory two-factor. Users manage their own password from Settings on the hub. There is exactly one super admin per organization.

Enjab Auth handles authorization at the door: a user can only complete "Sign in with Enjab Auth" for your tool if an admin gave them access (via a role or a direct grant). If they cannot, Enjab Auth shows the "no access" screen and never returns to your tool.

Enjab Auth shows the user a greeting plus consent screen on the way in ("Welcome, Sara. You have access to <tool>. <tool> will receive your name, email, role..."), then a Continue button sends them back to you. Your tool does not build this; Enjab Auth owns it.

Sign-out is confirmed on Enjab Auth and per-tool. Your "Sign out" button just navigates to your /api/auth/logout route; Enjab Auth shows a confirm page first (so an accidental click never logs anyone out), and confirming drops only your tool, never the central Enjab Auth session. Signing out of Enjab Auth itself (from the Enjab Auth hub) ends everything: it revokes every access token issued to you, so each tool loses access on its next /userinfo check. Never call signOut or clear the session yourself.

It tells your tool who the user is. By default it does NOT send roles and you must NOT gate by role: if Enjab Auth let the user in, that is the whole decision. Roles are sent only if an admin marks your tool "role-aware" (see Roles).

It stores only identity plus access. It does NOT store your app's data. Key all your own records by the user's sub (the stable Enjab Auth user id).

Your tool builds no login button and no login page. The instant a signed-out user touches any page, redirect straight to Enjab Auth (see the Flow guide).

The user object your tool receives

{
  "sub": "0f3c...",            // stable Enjab Auth user id - your foreign key for this user
  "email": "sara@enjab.ae",
  "name": "Sara Ahmed",        // the person's name, set in Enjab Auth admin - greet them with it
  "roles": ["reception"],      // ONLY present if your tool is role-aware; otherwise omitted
  "is_super_admin": false      // ONLY present if your tool is role-aware; otherwise omitted
}

There is no is_active flag: Enjab Auth blocks a disabled account at the door, so any user your tool receives is active. Most tools never see roles or is_super_admin at all (the keys are absent) and should not branch on them. Only role-aware tools receive the org's authorization details; a super admin has is_super_admin: true and access to every tool.

Most tools never need roles

Access is binary. An admin gives a user access to your tool (via a role or a direct grant); Enjab Auth enforces that at the door. If the user reaches your tool, they are allowed to use it. That is enough for almost every tool. Do not gate features by role.

Turn on roles ONLY when your tool has functions that not every authorized user should reach (for example, an admin-only settings page inside the tool). Then an Enjab Auth admin flips your tool to "role-aware" (Admin -> Tools -> your tool -> Role-aware), and from then on the user object includes roles (global keys like reception, doctor). You gate with user.roles?.includes("reception"). If the flag is off, roles is omitted.