Skip to content

User Authentication

Applies to: All subscriptions

Purpose

Describe how users authenticate, what an administrator can configure, and what to do when someone cannot sign in — a category that accounts for a large share of first-line tickets and is usually not an authentication fault at all.

Audience

Identity administrators, system administrators, security reviewers, first-line support.

Prerequisites

Reference

Sign-in methods

Method How it works Notes
Email and password Local account, credential verified against the stored hash Always available
External identity provider The browser authenticates with the customer's identity provider Configured at front-end build time and on the API
Social sign-in Where enabled and permitted by customer policy Frequently disallowed by corporate policy — confirm before offering it
Email one-time code A code sent to the account's address Depends entirely on mail delivery

Sessions

A successful sign-in issues a signed session token, held by the browser and presented on every request. The API is stateless — nothing about the session is stored server-side.

Property Consequence
Signed with a server secret Changing that secret invalidates every session immediately. A deliberate act, not a routine restart
Carries identity and scope Which is why scope is never taken from client input
Time-limited Users re-authenticate when it expires
Stateless Scaling out requires no session affinity

Verify: Session lifetime, password complexity, lockout thresholds and reuse rules are not stated in this portal. Obtain them from Complifly before answering a security questionnaire or aligning to customer policy. Recorded as assumption E3 in the Assumptions Register.

Everything depends on mail

Password reset, one-time codes and account activation all require a delivered email. If mail is misconfigured, users are locked out and nothing indicates why:

  • No error appears in the interface.
  • Nothing fails at application startup — mail credentials are validated at send time.
  • The ticket that reaches support says "I cannot log in", which sends the responder to authentication rather than to mail.

When several users cannot sign in at once, check mail delivery first. It is the most common cause and the least obvious.

GSTIN access is separate from sign-in

Authentication establishes who a user is. Two further gates decide what they see:

Gate Controls
Role Which actions they may perform. See Roles and Permissions
GSTIN access Which registrations they may work with

A user who signs in successfully and sees nothing usually has no GSTIN access, not an authentication problem. This distinction resolves a large share of "it is broken" reports.

Account lifecycle

Stage Action Note
Create Administrator creates the account with a role and GSTIN access The email must be one the user actually reads
Activate The user completes activation from an emailed message Blocked entirely if mail is not working
Operate Normal use —
Change role Administrator updates it Takes effect on the user's next sign-in
Suspend Disable the account Use for temporary removal of access
Revoke Disable on departure Do not delete. Deletion breaks the attribution of past actions in the audit trail

The final row matters for audit: a compliance system must be able to say who performed an action years later. Disable, never delete.

Development-only sign-in conveniences

Development builds may include conveniences that bypass normal sign-in. These must be absent or disabled in every production build. Verify explicitly before publishing a production front-end bundle — see Front-end Deployment.

Validation

Check Method Pass condition
Sign-in works Sign in as a test user Reaches the landing screen
External identity provider works Sign in through it Succeeds and the redirect returns correctly
Password reset works Trigger a reset to a real mailbox Message arrives in the inbox and the reset completes
One-time codes arrive in time Trigger a code Delivered well inside its validity period
Lockout works Attempt sign-in with a wrong password repeatedly Locks out per policy
Role gating works Sign in as a limited role and attempt a restricted action Refused or greyed out
GSTIN gating works Sign in as a user with access to one registration Only that registration's data is visible
Session expiry works Leave a session idle past its lifetime Re-authentication required
Revocation works Disable an account and attempt to sign in Refused
No development bypass in production Search the published front-end bundle for the flag names Absent
Attribution works Perform an action and inspect the audit trail The action is attributed to the correct user

Troubleshooting

Symptom Cause Action
Several users cannot sign in at once Mail delivery failure, not authentication Check mail first. See Email and Notifications
One user cannot sign in Wrong password, locked out, or account disabled Check the account state before anything else
Password reset email never arrives Mail misconfigured, wrong address, or filtered as spam Confirm the address, then test delivery to a known-good mailbox
One-time code expires before it is read Relay latency exceeds the code's validity Reduce latency, or extend the lifetime deliberately
Everyone signed out at once The token signing secret changed Expected if intended. If not, investigate what changed the configuration
Signs in successfully but sees nothing No GSTIN access Grant access. Not an authentication fault
Signs in but every button is greyed out Role lacks the permissions Fix the role. See Roles and Permissions
External sign-in redirect fails Redirect URL not registered, or a protocol mismatch Register the exact URL, including scheme and path
Social sign-in blocked by the customer Corporate policy Confirm the policy before enabling it
A departed employee's past actions lost from the audit trail The account was deleted rather than disabled Disable, never delete. Restore attribution if possible
Sessions expire too quickly for users Lifetime shorter than the working pattern Confirm the configurable range with Complifly before changing it