Duo sign-in check
The Duo check is one more step after sign-in. Someone signs in the way they always do (single sign-on or a password), and then CompassDocs sends them to Duo to approve the sign-in, usually with a push on their phone. When Duo says yes, they carry on to the page they wanted.
It works the same for every way of signing in. OIDC, SAML and passwords are all covered, and you change nothing in your identity provider.
You find it in Settings → Single sign-on, under Duo sign-in check.
What you need from Duo
Section titled “What you need from Duo”- In the Duo Admin Panel, go to Applications → Protect an Application and choose Web SDK.
- Copy its Client ID, Client secret and API hostname.
- Make sure your people exist in Duo. CompassDocs sends each person’s email address to Duo as their username. If your Duo usernames are something else, either add the email as a username alias in Duo, or set Name sent to Duo to CompassDocs username.
Which methods people may use (Duo Push only, passcodes, security keys) is Duo policy. Set it on the Web SDK application in the Duo Admin Panel. CompassDocs only learns whether Duo allowed the sign-in. To allow Duo Push and nothing else, restrict the application’s authentication methods in Duo.
Set it up
Section titled “Set it up”- Open Settings → Single sign-on and scroll to Duo sign-in check.
- Paste the Client ID, Client secret and API hostname
(it looks like
api-xxxxxxxx.duosecurity.com, withouthttps://). Select Save. - Select Test with my account. You go to Duo, approve the request, and come back to the settings page.
- Now turn on the rules you want, add your break-glass accounts, and Save.
The client secret is write-only. CompassDocs stores it encrypted and never shows it again. It is not written to the audit log or the server log.
One address for everyone
Section titled “One address for everyone”Run the test on the address your people use to open CompassDocs. When Duo has approved someone, it sends their browser back to CompassDocs, and CompassDocs decides that address itself. It never takes it from the request:
- If you set a custom domain in Settings → Domain & HTTPS, Duo always
sends people back to
https://your-domain. - If you did not, Duo sends people back to the address the test was run on. The settings page shows it next to Tested in this session.
Someone who opens CompassDocs on another address (an IP address, an old
hostname, http instead of https) is not sent to Duo. They see a message
naming the right address. So make sure everyone uses the one address, and
that your reverse proxy passes the real host and protocol on.
To move CompassDocs to a new address without a custom domain: turn both rules off, open CompassDocs on the new address, run the test there, and turn the rules back on. While a rule is on, a test from another address is refused.
Why the test comes first
Section titled “Why the test comes first”A rule can only be turned on by an administrator who has just passed Test with my account: a real Duo approval, in the same session, with the details that are saved. That way nobody switches Duo on with a mistyped secret and locks the workspace out.
If you later change the Client ID, the secret, the API hostname or Name sent to Duo, CompassDocs turns both rules off and asks you to test again before you turn them back on.
Changing the settings while Duo is enforced
Section titled “Changing the settings while Duo is enforced”While a rule is on, the Duo settings can only be changed from a session that has passed Duo, or by a bypass account. This matters with only the desk rule on: an administrator can open Settings without Duo, but cannot turn the rule off, edit the bypass list or change the details until they have approved a Duo request (open the desk, approve, come back and save).
If Duo itself is what is broken, sign in with a bypass account, or use the emergency switch.
Where Duo is asked for
Section titled “Where Duo is asked for”There are two rules. You can use one or both.
| Rule | What it does |
|---|---|
| At sign-in | Every session passes Duo once, right after signing in. |
| When opening the desk | The desk and its API want a Duo approval on this session no older than a number of hours (12 by default, from 1 to 168). |
With only When opening the desk on, the rest of CompassDocs is not
affected: people read and edit documents as before, and are asked for Duo
when they open /desk. Get help, the page where people raise requests, is
not the desk and is not asked.
With both on, people approve once at sign-in. That approval also opens the desk until it is older than the desk hours, then the desk asks again.
What the desk rule also covers
Section titled “What the desk rule also covers”The desk rule follows desk work, not only the /desk address. While
someone with desk access owes the desk its Duo approval:
- Get help does not show them tickets they reach as an agent (a ticket in their queue, its files, its contact cards, the agents’ approvals list). They are sent to the Duo step first. Their own requests, and requests they approve or are copied on, open as always.
- They cannot create an API token or approve the Claude connector (or another app). Both would reach the desk later without Duo. The page says “Confirm with Duo first”.
- A desk role that may edit the helpdesk’s email templates cannot do so from Settings.
People with no desk access never notice the desk rule.
If the desk asks while an agent is working
Section titled “If the desk asks while an agent is working”When an agent’s approval runs out in the middle of a reply, nothing is thrown away. The desk shows Confirm with Duo to keep working. The agent selects it, approves in a new tab, and carries on in the tab they were in. The text in the reply box stays where it is (it is also saved per ticket in the browser). The one action that was refused, such as Send, needs pressing again.
What is never asked
Section titled “What is never asked”Duo is for people signing in with a browser. These are not asked:
- API tokens (
/api/v1, the helpdesk API), once created. Creating one happens in the browser, so the sign-in rule applies, and so does the desk rule for people with desk access. - The Claude connector (MCP), once someone has approved it. Approving it happens in the browser, under the same two rules.
- Webhooks, inbound email, SCIM and chat app events.
- The customer portal for people outside your company.
Accounts that skip Duo (break-glass)
Section titled “Accounts that skip Duo (break-glass)”Pick the accounts that may sign in without Duo. Choose them by name; there is no “all administrators” switch. Use one or two dedicated accounts with long passwords, kept somewhere safe.
- A bypass account is let in whatever state Duo is in.
- Each session of a bypass account writes one line to the audit log: Skipped Duo (bypass list).
- The settings page warns you while a rule is on and the list is empty.
While SSO only is on, only the break-glass accounts named under
Single sign-on can sign in with a password, at /login?local=1. Put
at least one of them on this list too. See
Break-glass accounts.
A session Duo approved counts as the second step for Require two-step sign-in (1.20.27): nobody is asked for an authenticator code after Duo as well. A session let through while Duo couldn’t be reached is asked.
If Duo can’t be reached
Section titled “If Duo can’t be reached”By default people are blocked. They see Duo can’t be reached and a Try again button, and the attempt is written to the audit log.
If you would rather let people in while Duo is down, turn on Let people in when Duo can’t be reached. Each time someone is let through, the audit log says so.
It is deliberately narrow:
- It only covers Duo not answering: no connection, a timeout, or a server error (5xx). If anything answers and it is not a yes (Duo refusing because the client secret was revoked, a redirect, a captive portal’s page), people are blocked.
- If Duo fails after the person has already answered the prompt, they are let through only if Duo’s health check cannot be reached either.
- Being let through lasts one hour, for both rules. After that the session owes Duo again. If Duo is still down the person is let through again, and that is audited again.
- A session that was let through has not proved anything. It cannot change its own email or the Duo settings.
Bypass accounts get in either way.
The emergency switch
Section titled “The emergency switch”If nobody can get in to fix the settings (the Duo application was deleted, the bypass account’s password is lost), set this in the server’s environment and restart:
COMPASSDOCS_DUO_DISABLED=1While it is set, nobody is asked for Duo. Your saved settings stay as they are, and every Settings page shows a banner saying Duo is switched off on the server. Fix the settings, remove the variable and restart to enforce the rules again.
What your license does
Section titled “What your license does”The Duo check follows the sso entitlement, like SSO only:
- While the license is active, and for the 14 days of grace after it expires, the rules are enforced and can be changed.
- From 1.20.27, after that the rules keep being enforced, as long as
the license was one our signature verified, and the settings can’t be
changed until you renew.
COMPASSDOCS_DUO_DISABLED=1still switches the rules off in an emergency. Before 1.20.27 Duo stopped being asked when the grace ended. - With no license, or one that doesn’t verify, no Duo rule is enforced. People sign in without the Duo step. Your settings are kept and take effect again when a valid license is entered. The settings page says so: “Duo is not being enforced”.
What is recorded
Section titled “What is recorded”The audit log records:
- Updated Duo settings: who changed what. Never the secret.
- Confirmed with Duo and Failed the Duo check (denied, timed out, started in another window).
- Skipped Duo (bypass list), once per session.
- Let through while Duo was unreachable and Blocked while Duo was unreachable.
Your email and Duo
Section titled “Your email and Duo”By default CompassDocs sends a person’s email to Duo as their username. So while a Duo rule applies to someone, they can change their own email (Account → Profile) only from a session that has really passed Duo. A session that has not (the desk rule with no approval yet, or one that was let through while Duo was down) is told to confirm with Duo first.
An administrator changing someone else’s email in Settings → Users is not affected. Remember to update the person’s username or alias in Duo too.
Good to know
Section titled “Good to know”- An approval belongs to one session. Signing in on another browser asks again.
- Turning At sign-in on applies to people who are already signed in too: their next page sends them to the Duo step.
- A Duo request must be answered within five minutes. After that, select Try again.
- One browser session can ask for ten Duo requests in five minutes. Past that it has to wait. Another session of the same account is not affected.
- CompassDocs’ own authenticator codes (Account → Security) still work for password sign-ins. Duo comes after them.
- CompassDocs talks to
https://<your API hostname>only. The server needs outbound HTTPS to it.
