Authentication and MFA

ArkanPM implements layered authentication with short-lived access tokens, rotating refresh tokens, TOTP-based multi-factor authentication, and intelligent account lockout. This article walks through each layer and the everyday flows.

JWT tokens

ArkanPM uses stateless JSON Web Tokens (JWT) for authentication:

• Access token — carries the user's identity and permissions. TTL is 15 minutes.
• Refresh token — issued alongside the access token. TTL is 7 days. Stored server-side as a SHA-256 hash, never in plain text.

When an access token expires, the client silently exchanges the refresh token for a new access token. ArkanPM rotates the refresh token on every refresh — the old one is invalidated. This makes replay attacks essentially impossible.

What to do when tokens expire

Users almost never notice. The client library transparently refreshes. If the refresh token itself has expired (after 7 days of inactivity), the user is redirected to the sign-in page.

Multi-factor authentication (MFA)

MFA is TOTP-based (time-based one-time passwords) compatible with any authenticator app — Google Authenticator, Microsoft Authenticator, 1Password, Authy.

Enabling MFA

1. Open Profile → Security → Enable MFA.
2. Scan the QR code with your authenticator app.
3. Confirm by entering a TOTP code from the app.
4. Save the 8 backup codes somewhere safe. Each is single-use.
5. MFA is now required at every sign-in.

MFA enforcement

MFA is enforced for all administrator roles — Super Admin, Platform Admin, and Tenant Admin — with no exceptions. Other roles can enable MFA voluntarily.

Using backup codes

If you lose your authenticator device, sign in with email and password, then enter a backup code in place of the TOTP prompt. Each backup code works exactly once. When you have used several, regenerate a new set from Profile → Security → Regenerate backup codes.

Account lockout

ArkanPM implements intelligent account lockout: after 5 failed login attempts, the account is locked for 15 minutes. No brute-force attack survives this.

During lockout:

• The user sees a generic "account temporarily locked" message.
• A tenant admin can unlock the account immediately from Admin → Users.
• The lockout event is recorded in the audit trail with the attempting IP address and user agent.

Password policy

Passwords must:

• Be at least 10 characters.
• Contain at least one uppercase, one lowercase, one digit, and one special character.
• Not match any of the last 5 passwords used by the same user.

The policy is enforced at creation, at reset, and at every password change. Users are guided by an inline strength meter.

Session limits

To prevent credential sharing:

• Standard users: 5 concurrent sessions.
• Admin users: 10 concurrent sessions.

When a user exceeds the limit, the oldest session is invalidated automatically.

Tenant status guards

ArkanPM's tenant state machine directly gates authentication:

• Active tenants — normal operation.
• Suspended tenants — users can sign in but are restricted to read-only access automatically.
• Archived or terminated tenants — users are fully locked out.

No manual intervention needed. Tenant status flips at the admin level and takes effect at the next request.

Secure password reset

The password reset flow:

1. User clicks Forgot password on the sign-in page.
2. Enters their email address.
3. ArkanPM sends a reset email with a time-limited token.
4. User clicks the link, sets a new password (subject to the policy and history check).
5. User signs in with the new password.

The reset endpoint is hardened against email enumeration — it always returns the same response whether the email exists or not.

Best practices

1. Enforce MFA tenant-wide. Even non-admin accounts benefit from the extra factor.
2. Rotate backup codes periodically. Especially after a device change.
3. Watch the audit trail for failed logins. Spikes correlate with brute-force attempts against specific accounts.
4. Keep session limits conservative. Loose limits make credential theft easier to hide.

What next

Read Audit trail and data retention to see how every authentication event is logged and retained.