How sign-in works

octoja supports three sign-in methods: local password login, OIDC / SSO, and TOTP as a second step on top of either.

Authentication methods

Important behavior

• A user without a password cannot use local password login.
• SSO signs in an octoja account that already has that provider linked. The link comes from accepting an octoja invitation with the provider, from linking the provider yourself under Linked Logins in your profile, or from an administrator connecting it to an account that already exists. Without that link, the sign-in page answers "This SSO login is not linked to any account. An administrator must connect it first."
• octoja recognises a person by the account they sign in with at the provider, not by the email address the provider reports. Everyone therefore links the provider account they will keep signing in with.
• Removing a sign-in method from your own account must leave a usable way in: a password can be removed once an SSO login for an enabled provider is linked. The last such SSO login can be unlinked only when a password is set and password sign-in is allowed. When SSO is required, first link another enabled provider; links to disabled providers do not count. An administrator can set a password for an account that has none.
• For Microsoft SSO, the first sign-in asks each person to approve octoja's access to their name, email address, and profile. Where an organisation requires administrator approval for apps, a Microsoft Entra administrator approves octoja once and everyone else signs in without being asked.
• Administrators can disable password sign-in for every user under Settings → Authentication. This policy requires at least one configured and enabled SSO provider, and accounts must be linked to that provider.
• Administrators can also require TOTP for every user there. Users without an authenticator enroll one before completing their next password or SSO sign-in and cannot remove it while the policy is active.

Turn SSO providers on or off

octoja support sets up which SSO providers are available for your octoja instance. Members of an administrator group can turn each of these providers off individually, for example if your organisation only uses Microsoft:

1. Open Settings → Authentication. The SSO providers section only appears when at least one provider is set up.
2. Click a provider's card to turn it off or back on. Enabled providers show a check mark.
3. Click Save.

A provider that is turned off disappears from the sign-in page, from invitations, and from linking in the profile; sign-ins through it are rejected. Users' linked logins are kept and work again once you turn the provider back on. While Require SSO sign-in is active, at least one provider must stay on.

Recommended setup

TOTP is switched on per user and adds meaningful protection to any sign-in: if a user has 2FA enabled, signing in through an identity provider also prompts for the authenticator code, so SSO logins are covered as well as local password logins. Organisations that want central identity management and passwordless sign-in are best served by Microsoft or another OIDC provider. Authentication only verifies identity. What a user can then see and do is governed separately by the groups they belong to — a group grants module permissions, Customer Access (which customers members can work with), and Device Access with its Allowed actions (which devices members can reach and what they may do on them). See How Users, Groups & Permissions Work.

Session management

• Browser-based sign-ins use a session cookie managed by octoja. The session runs for eight hours and renews itself while you keep working, so it is an idle browser that gets signed out.
• API clients use bearer tokens returned by the login or refresh endpoints. An access token is good for one hour, and the refresh token issued alongside it exchanges for a fresh pair without sending the password again.
• Logging out ends the current browser session. A bearer token already handed to an API client stays valid until it expires.

See also: API Authentication, Reset Your Password