> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Policy

> Require single sign-on, limit sign-in methods and cap session length for your workspace, and what your members see when a sign-in is refused.

A workspace's authentication policy decides how people may sign in to it and how long their sessions last. Find it under **Settings → Authentication policy**.

Viewing or changing it needs the **owner or admin** role, and saving a change needs a re-authentication in the last 5 minutes. A policy can only be stricter than KnoxCall's platform defaults, never looser.

## What each setting does

| Setting | What it does | Applied today |
| - | - | - |
| **Require single sign-on** | Members must sign in through your workspace's SSO connection. | Yes |
| **Sign-in methods** | Which of magic link, passkey, Google, Microsoft, GitHub and SAML members may use. | Yes |
| **Maximum session length** | A session ends this long after sign-in, however active it has been. The platform allows at most 30 days. | Yes |
| **Idle timeout** | A session ends if no browser or client has renewed it for this long. | Yes |
| **Require a phishing-resistant method** | Stored, but not applied yet. The page marks it **Not enforced**. | No |
| **Second-factor grace period** | Stored, but not applied yet. The page marks it **Not enforced**. | No |

In the browser, an idle session also signs out after 15 minutes, or after your idle timeout if that is shorter.

> [!WARNING]
>
> Set up and test your [SSO connection](https://docs.knoxcall.com/sso/overview.md) before you turn on **Require single sign-on**. Once it is on, the members it applies to can't sign in any other way.

## When a change takes effect

* **New sign-ins** are judged by the new policy straight away.
* **Sessions already open** are judged at their next renewal, so a member can keep working for up to 15 minutes after you tighten the policy.
* **OAuth grants made by a person**, such as a CLI login, are judged when consent is given and at every token refresh. If the way that person signed in no longer satisfies the policy, the grant ends and they need to sign in again. Maximum session length and idle timeout don't apply to these grants; their lifetime comes from the OAuth client's token settings.
* **API keys and machine credentials** aren't people and don't sign in, so this policy doesn't apply to them.

## What your members see

A refused sign-in or session names the workspace and says why:

| Reason | Message |
| - | - |
| SSO is required | *"Acme requires single sign-on. Sign in through its SSO."* |
| That method isn't allowed | *"Acme does not allow this sign-in method. Use a method it allows."* |
| Session reached its maximum length | *"Your session reached the maximum length Acme allows. Sign in again."* |
| Session was idle too long | *"Your session was inactive for longer than Acme allows. Sign in again."* |

**Magic links:** asking for a link always gets the same response, so nobody can use that request to learn your workspace's policy. If magic links aren't allowed, the refusal appears when the link is opened.

### Members of more than one workspace

A session that isn't tied to one workspace is held to the strictest rules of every workspace the person belongs to, so the weakest workspace can't be a way into the strictest.

* SSO sessions are always tied to one workspace. So someone who belongs to a workspace that requires SSO signs in to it through its SSO, and to their other workspaces at each one's own address.
* If their workspaces allow different methods with none in common, they see: *"Your workspaces allow different sign-in methods, with none in common. Sign in to one workspace at a time, at its own address."*

## If you are locked out

Requiring SSO means an identity provider outage or a deleted connection could keep your whole workspace out. There are two ways back in. Neither changes your stored policy.

**The last owner, when there is no usable SSO connection.** If your workspace has no SSO connection that sign-in could use, its last active owner can still sign in, despite **Require single sign-on** and **Sign-in methods**. They can then fix the connection or change the policy.

**KnoxCall support, for everything else.** A connection that exists but no longer works, such as a rotated signing key or an identity provider outage, doesn't count as having no connection, so the last-owner route won't open. Contact support. KnoxCall staff can suspend your policy's sign-in rules for your active members for up to 72 hours, and your owners and admins are emailed when they do. Staff can't suspend the policy of a workspace they are a member of.

Maximum session length and idle timeout still apply during either route, because they end a session rather than locking anyone out.

### Both are recorded

Every sign-in or session renewal that goes through either route writes a row to your workspace's audit log, so you can see that your policy didn't apply, to whom and why. An active session renews about every 10 minutes, so expect one row per session at that rate for as long as the route is in use.

| Audit action | Meaning |
| - | - |
| `auth.policy_bypass.last_owner` | The last owner was let in because the workspace has no usable SSO connection. |
| `auth.policy_bypass.operator_break_glass` | A member was let in under a suspension granted by KnoxCall staff. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.