1. Docs
  2. Authentication
  3. Configure Sign-In, MFA, and Self-Signup

Configure Sign-In, MFA, and Self-Signup

Turn sign-in methods on or off per Environment in the Developer Console, require MFA with a grace period, allow self-signup, set token lifetimes, the browser origins the API accepts, and where auth-email links land.

Sign-in methods and browser origins

In the Developer Console, Tenant → Authentication is one page for every Environment's end-user authentication, in five tabs: Multi-Factor Auth, Sign-in methods, Self-signup, Tokens and Signing keys. Each tab has one row per Environment.

Application
Developer Console
Path
TenantAuthentication
Opens with
  • auth_settings.view Read every Environment's sign-in methods, MFA enforcement, and self-signup settings, and the origins hosted pages may return people to.
Context
Account-wide. No Application or Environment selection applies.
Sign-in methods and browser origins
Open Authentication from the left nav under Tenant and choose the Sign-in methods tab. In Sign-in methods (Direct API), each Environment's row shows its Login methods, Allowed origins, and Login CAPTCHA. Expand a row.Under Login methods, Password is on by default, Passwordless email code is off, and Single Sign-On reads Not configured until a connection is bound. Turning every method off shows the warning No usable sign-in method. Every login attempt on this environment will fail.; leave at least one on.Under Allowed web origins, add each origin your browser app calls from, as scheme and host only, such as https://app.example.com. Self-service sign-up accepts only a listed origin while the list is set. The list is not a firewall: an empty one does not block browser calls, because the API's cross-origin policy admits any origin an Environment lists. Under SSO return URLs, add the exact URL your app returns to after an SSO sign-in; matching is exact. Under Roles an identity provider may grant, tick the roles a customer's identity provider may hand out through directory sync or a first single sign-on, and pick the one people arrive with. Every organization without a list of its own inherits it, which is what opens directory sync for them; the organization portal's SSO setup preselects the arrival role. Choose the least privilege that lets a new person in.Under Auth email links land on, enter your app's origin, such as https://app.example.com, and click Save. From then on the Environment's password-reset, invitation and verification emails link to your app at /reset-password, /accept-invite and /verify-email, each with a token query parameter, and your own pages finish the step by calling the Direct API. Leave it empty and the links go to Canopy's hosted pages. It must be a bare https origin (http only on localhost); anything with a path is refused.Under Sign-in URL, enter the page in your app that starts a sign-in, such as https://app.example.com/login, and save. Canopy's hosted pages that end with nothing to return to (an accepted invitation, a verified email, a finished password reset) link to it as Sign in when the app involved has no sign-in URL of its own, for example an invitation that names no app. Leave it empty to clear it. It must be https (http only on localhost).Below the table, Hosted page return origins applies to every Environment in the account. Add each origin a hosted page may send people back to when they finish, such as https://app.example.com, and click Save. A link to a hosted page with return_to pointing at a listed origin gets a way back to your app; any other origin gets no link at all. Origins are scheme and host only, https (http only on localhost); anything with a path is refused.Turn Require CAPTCHA on login on only once your login page renders the <canopy-captcha> widget, or logins will be rejected. Each list and field saves on its own Save; Reset discards an unsaved edit.Under Organizations, Require organization membership refuses a session to anyone who belongs to no organization in the Environment, at login, refresh and SSO alike, with 403 auth.organization_membership_required; it toggles immediately. The notice beneath it counts the current members in no organization, who are refused from their next sign-in or refresh until they are added to one. The section reads Organizations are switched off for this environment until the container is on, which is set per Environment on the Applications page.

Require MFA

MFA enforcement is per Environment. Existing sessions keep working; people are prompted to enrol at their next sign-in, and blocked once the grace period ends.

Require MFA
On the Multi-Factor Auth tab, in Identity MFA enforcement, toggle Require MFA on an Environment's row. The confirmation, Enable MFA for …?, spells out the effect; confirm it, and the row changes from Optional to Required.Expand the row. Grace period (days) is how long people have to enrol before sign-in is blocked; 0 challenges on the next sign-in. Remember device (days) is how long a device skips the challenge; 0, the default, challenges every sign-in, and no "remember this device" option is offered until you raise it.Under Allowed factors, choose between Authenticator app (TOTP), Email OTP, and WebAuthn / passkeys. At least one must remain allowed. The choice decides both what a sign-in challenge offers and what people can add on the security page or when asked to set up a method.Challenge after an SSO sign-in decides whether a single sign-on waives a second factor that is owed. On, it doesn't; off, SSO sign-ins skip the challenge. A provider that reports the factor it checked is never asked again either way.Under Passkey relying party, name your app's domain (Relying-party id, plus at least one Allowed origins entry) when your app runs the passkey ceremony itself. Leave both empty to use Canopy's. The hosted pages never use this setting: they use Canopy's relying party, or the custom auth domain they are served on. Changing the id orphans the passkeys created under the old one. Click Save changes.Toggling Require MFA off returns the row to Optional.

Allow self-signup

Self-signup lets anyone holding the Environment's publishable key register from your app. Registrations create unverified identities that must confirm their email before signing in.

Allow self-signup
On the Self-signup tab, toggle an Environment's row on. The confirmation, Enable self-service signup, notes that server-side and invite-based registration are unaffected; confirm with Enable signup. The row changes from Disabled to Enabled.Expand the row. Turn on Require CAPTCHA on sign-up once your signup page renders the <canopy-captcha> widget, and set a Daily signup cap per UTC day, where 0 means unlimited. Click Save changes; Discard changes drops an unsaved edit.Below the cap, Create an organization on sign-up gives every person who registers an organization of their own, named after them, with their first session already inside it. Choose the Role the creator receives, an active role of the Environment (one carrying canopy:organization.manage lets them run the organization from the portal); Save changes stays disabled while the switch is on with no role, since the API refuses that. The pair reads Organizations are switched off for this environment until the container is on, set per Environment on the Applications page.

Set token lifetimes

How long the sessions each Environment issues stay valid, and how long a machine client's tokens live. Changes apply to tokens issued after you save, including the next refresh of a session already running: each refresh mints its tokens with the lifetimes set then.

Set token lifetimes
On the Tokens tab, each Environment's row shows its Access token and Session lifetimes. Expand a row: Sign-in tokens holds what a person's sign-in issues, and Machine clients beside it what a machine client gets.Under Sign-in tokens, Access token lifetime is 60 to 3,600 seconds (15 minutes by default): shorter limits how long a leaked token stays usable, and apps refresh silently when it expires. Session lifetime is 1 to 365 days (180 by default) without re-authentication. Click Save changes, or Discard to drop an unsaved edit.Under Machine clients, Machine token lifetime is 60 to 3,600 seconds (5 minutes by default) for the tokens a machine client obtains with its client credentials; it asks again when one expires, since there is no refresh. Default audience is the audience such a token names when the request names none, usually your API's URL, one value with no spaces; leave it blank to make every request name an audience the client lists. See Machine Clients.With organizations on, Machine clients also holds Let organizations create integrations, which lets each organization's administrator create machine clients for their own systems from the hosted portal, pinned to that organization and holding roles you choose under Roles integrations may hold. It is off by default and needs a Default audience, which the integrations' tokens name, and at least one of those roles. See Machine Clients.

Signing keys

Every Environment is its own issuer with its own signing keys. The tokens it issues carry its issuer and verify only against its keys, so a token from one Environment never verifies for another. Keys rotate on their own every 90 days; this tab is where you read the values a relying party configures, and where you rotate early.

Signing keys
On the Signing keys tab, each Environment's row shows its Issuer, the Current key id and when it began signing. Expand a row to copy the Issuer, Discovery URL and JWKS URL: the issuer is what your backend or the @canopy-io/node SDK is configured with, and the two URLs are what an OIDC library reads from it.Under Published keys, Current signs new tokens, Next is published 7 days before a scheduled rotation so every verifier has seen it, and Previous stopped signing and stays published for 24 hours so the tokens it signed keep verifying.Rotate now replaces the current key the way the schedule would, keeping the old key published for 24 hours: nothing live is refused and nobody is signed out. Emergency rotation mints a fresh key and retires every other key at once, so every token they signed stops verifying on its next check and people sign in again. Use it for a suspected key compromise and nothing else. Both need auth_settings.manage; a reader holding only the view sees the keys and no buttons.
If you don't see this

Each control on this page exists only for someone who may use it. When something described above is missing, one of these is why:

Authentication is not in the left nav. Your administrator role does not carry auth_settings.view.The rows show but every toggle and field is disabled, with a notice explaining why. You hold auth_settings.view but not auth_settings.manage; the page is your read view of the settings.Single Sign-On reads Not configured. No SSO connection is bound to that Environment yet; bind one from Tenant → Single Sign-On.
How multi-factor authentication works → Direct API authentication →
Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy