Users and access — Documentation

Accounts, roles and departments are managed in the admin console, under "Users" (the "Users and roles" page), which is reserved to the "Administrator" role. It has three tabs: "Accounts", "Roles and permissions" and "Departments".

The four roles

Roles are fixed: their permissions cannot be changed. An account can hold several. The "Roles and permissions" tab shows the full matrix.

Role	What it reaches
"Employee"	Chats with authorized destinations. No console access.
"Auditor"	Read-only access to the audit journal, statistics and exports.
"Administrator"	Full console access, except reading conversations.
"Knowledge manager"	Uploads and removes documents of the knowledge base. No other console access.

Every role can chat and query the knowledge base. Under "Never granted — by design", the matrix lists reading the content of others' conversations and disabling redaction.

A role change ends the account's open sessions: the new roles apply at the next sign-in. You cannot edit your own account here, and Cortex refuses to remove the "Administrator" role from the last active administrator, or to deactivate them.

Create an account

At the top of the page, click "New user".
Fill in the "Email" and the "Display name", then tick the "Roles" ("Employee" is ticked by default).
Optional: choose a "Department". Pick an existing one, "No department", or type a new name and add it on the fly.
Click "Create". The "User created" dialog shows the initial password.
Copy it with "Copy" and deliver it to the employee securely. It will never be shown again; close the dialog with "Close".

Cortex screenshot: the Users and roles page, Accounts tab, with seven fictitious accounts, their department, roles and status — The “Accounts” tab: department, roles, destinations and status of each account.

An account created here is a local account, protected by a password that Cortex generates. If the email already exists, the console answers "This email is already in use."

Departments

The "Departments" tab lists departments with their users and collections. A department is used to open collections of the knowledge base to part of your employees. An account belongs to at most one department.

"New department" asks for a "Name" (1 to 100 characters, unique regardless of case), then "Create".
"Rename" changes the name; attachments stay.
"Delete" opens a dialog that states the effect before you confirm: the department's users lose their department, and the collections that listed it lose that access.

MFA

MFA (two-factor authentication) applies to local accounts only. For an SSO account, the console states "MFA is managed by the identity provider for SSO accounts."

To require MFA for an account, open it with the actions menu (⋯) on its row, then "Edit", and tick "MFA required" (the checkbox applies immediately, without "Save"). At the next sign-in the employee sees "Set up two-factor authentication": they scan the QR code (or type the "Manual entry key") into an authenticator app, enter the 6-digit code and click "Verify". From then on, every sign-in asks for that code ("Two-step verification"). An account that has already enrolled an app keeps this step even if "MFA required" is unticked.

If an employee loses their app, open the account: next to "MFA enrolled", the "Reset MFA" button clears the enrollment. The "Without 2FA" card counts active local accounts with no enrolled app.

Single sign-on

Cortex supports OIDC and SAML 2.0. The variables are set in the .env at the repository root, which Compose reads on the host; after a change, recreate the gateway container (docker compose up -d gateway).

# With the SSO sign-in button, this is the web origin plus /api/gateway
GATEWAY_PUBLIC_URL=http://localhost:3000/api/gateway

# OIDC: the three variables are required together
OIDC_ISSUER_URL=
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=

# SAML: the SSO URL and the certificate are required together
SAML_IDP_SSO_URL=
SAML_IDP_CERT=
SAML_SP_ENTITY_ID=cortex-gateway

AUTH_LOCAL_ENABLED=true

OIDC is enabled when OIDC_ISSUER_URL is set; Cortex requests the openid email profile scopes with PKCE. The redirect URI to register at the provider is GATEWAY_PUBLIC_URL followed by /api/v1/auth/oidc/callback.
SAML is enabled when SAML_IDP_SSO_URL is set. The callback URL (ACS) is GATEWAY_PUBLIC_URL followed by /api/v1/auth/saml/callback, the service provider metadata is served at GATEWAY_PUBLIC_URL followed by /api/v1/auth/saml/metadata, and both the response and the assertion must be signed. SAML_SP_ENTITY_ID must match the identifier registered at the provider.
With the "Sign in with SSO" button, GATEWAY_PUBLIC_URL must be the web origin followed by /api/gateway (for example http://localhost:3000/api/gateway): the button goes through the web proxy and the OIDC return lands on the origin this variable names.
AUTH_LOCAL_ENABLED: only the value true keeps local accounts. The gateway refuses to start if local accounts are disabled with neither OIDC nor SAML configured, or if a required variable is missing.

The "Sign in with SSO" button on the sign-in page starts the OIDC flow. SAML has no button: the flow starts at GATEWAY_PUBLIC_URL followed by /api/v1/auth/saml/start. According to the Cortex repository (installation document), SAML behind the web proxy has not been exercised yet; only OIDC has. The page always shows the SSO button and the form, even if one of the two is disabled.

On first SSO sign-in, an employee is created automatically with the "Employee" role only; Cortex reads their name and email from the provider's response and takes no role from it. An administrator then adds roles and a department in "Edit". The console does not create SSO accounts.

Deactivate an account

Open the account with the actions menu (⋯) on its row, then "Edit", and choose "Inactive" under "Status". The dialog warns: "Their active sessions will be revoked immediately." Click "Save" to apply. To reactivate, choose "Active", then "Save". The account can no longer sign in, even through SSO; it is kept.

Deactivating erases nothing. To erase an account's data, see Retention and erasure.