Password, MFA & SSO

The Settings → Password, MFA & SSO page combines your own sign-in settings with the organization's policies:

• Left column: Your password, Multi-factor authentication and API keys. Every signed-in user can use these.
• Right column: Password policy and Single sign-on. The policy card appears for people with at least Read only on Organization settings.

#Ways to sign in

A failed sign-in always returns the same message, "Wrong sign-in details", so nobody can find out whether an account exists. Sign-in requests are limited to 10 per minute for each client IP and account name (or access key), and MFA code checks to 10 per minute for each client IP. Too many attempts return "Too many attempts. Wait a minute and try again."

#Password policy

The policy is stored per organization and applies to users who sign in with a password. Viewing it needs Read only on Organization settings. Changing it needs Full access.

A small built-in list of very common passwords, such as password123, is always rejected.

To change the policy:

1. Open Settings → Password, MFA & SSO.
2. Edit the numbers and switches in Password policy.
3. Select Save policy.

The new rules apply to the next password change. Existing passwords are not checked again. The change is recorded in the audit log as settings.password_policy.update, with the old and new value of each setting.

#Expired passwords

When a password is older than the expiry period, the user can still sign in, but Your password shows "Your password has expired. Choose a new one." Users who sign in with SSO are never subject to expiry.

#Lockout

Each wrong password adds one to the user's failed-attempt count. When the count reaches Lock after failed attempts, the account is locked for Lock duration (minutes). A successful sign-in resets the count.

To unlock someone early, open Settings → Access control → Users and select Unlock on their row. You need Read & modify on Users, roles & teams. Locked users are counted in the Locked out tile.

#Change your password

1. In Your password, enter the Current password and the New password.
2. Select Change password.

If the new password breaks the policy, the error lists every problem. Users who sign in with Google or Microsoft see a note that their password is managed by their identity provider instead.

#Multi-factor authentication

OpsNexus supports time-based one-time codes (TOTP) from any authenticator app, such as Google Authenticator, Microsoft Authenticator or 1Password. The MFA secret is encrypted at rest.

#Turn on MFA

1. Open Settings → Password, MFA & SSO.
2. In Multi-factor authentication, select Set up MFA.
3. In your authenticator app, add an account and scan the QR code. If you can't scan it, select Copy key and enter the key by hand. On a phone, use On this phone? Open in authenticator app.
4. Type the 6-digit code from the app into Code from the app.
5. Select Turn on MFA.

The QR code is drawn by the OpsNexus server, not by an online service. If the code is rejected, check that the time on your phone is correct.

From the next sign-in, OpsNexus asks for a One-time code after the password or SSO step. The MFA step must be finished within 5 minutes (MFA_TOKEN_MINUTES).

#Turn off MFA

Enter a current code in Current code to turn MFA off and select Turn off MFA. This isn't possible while the organization requires MFA.

#Lost authenticator

OpsNexus has no recovery codes, and the UI has no button for an admin to reset another user's MFA. Turning MFA off needs a valid code from the app. Before you enforce MFA, make sure people back up their authenticator app or add the key to a second device during setup.

#Enforce MFA for everyone

1. In Password policy, turn on Require MFA for every user.
2. Select Save policy.

Users without MFA can still sign in, but they are sent to the MFA setup screen with the message "Your organization requires MFA. Set it up now." While the policy is on, nobody can turn MFA off. Use the MFA enabled tile on Access control to see how many users still need to set it up.

#Single sign-on

OpsNexus supports OpenID Connect sign-in with two providers:

• Google Workspace
• Microsoft Entra ID

There is no generic OIDC, SAML or LDAP sign-in. The Single sign-on card shows each provider as Enabled or Not configured.

#How SSO works

• Users must exist in OpsNexus before they can use SSO. Add them on Access control with Signs in with set to Google SSO or Microsoft SSO.
• OpsNexus matches the verified email address from the provider to an active user. If no active user has that email, sign-in fails with "No active OpsNexus account uses this email. Ask an admin to invite you."
• For Google, the email must be verified.
• If the user has MFA turned on, OpsNexus still asks for the one-time code after SSO.
• Users created with SSO can't sign in with a password.

#Configure Google or Microsoft

SSO is configured on the server with environment variables, not in the UI.

1. Register an OAuth / OpenID Connect web application with your provider.

2. Set the redirect URI to:

   <PUBLIC_URL>/api/auth/sso/google/callback
   <PUBLIC_URL>/api/auth/sso/microsoft/callback

   PUBLIC_URL must be the address users open in the browser, for example https://opsnexus.example.com.

3. Add the client ID and secret to .env:

   ini

   GOOGLE_CLIENT_ID=
   GOOGLE_CLIENT_SECRET=
   MICROSOFT_CLIENT_ID=
   MICROSOFT_CLIENT_SECRET=
   MICROSOFT_TENANT_ID=common

   For Microsoft, set MICROSOFT_TENANT_ID to your directory (tenant) ID to accept only your own tenant. The default common accepts any Microsoft account, but only users that already exist in OpsNexus can sign in.

4. Restart the API so it reads the new values:

   bash

   docker compose up -d api

A provider counts as configured when both its client ID and secret are set. The sign-in page then shows its button. OpsNexus requests the openid email profile scopes.

See Environment variables for the full list.

#Sessions

A browser keeps one session, shared by all its tabs, in an HttpOnly cookie that is only sent to the sign-in endpoints. The refresh token rotates on each use, so an old one stops working at once. After the session lifetime, the user signs in again.

Sessions end early when:

• The user signs out.
• The user signs out a session on My profile → Where you're signed in.
• An admin deactivates or deletes the user.

#API keys

API keys let scripts and the VS Code extension sign in. A key acts with your own role.

1. In API keys, enter a Key name, for example terraform-automation.
2. Select Create key.
3. Copy the Secret key at once. It isn't shown again, and OpsNexus only stores a hash of it.

Send the key in a header:

curl -H "X-API-Key: <access-key>.<secret-key>" https://opsnexus.example.com/api/auth/me

To stop a key, select Revoke. It stops working right away. Creating and revoking keys is recorded in the audit log.

#Related pages

• Access control
• Audit logs
• Production checklist