Single Sign-On (SSO) | Canopy Docs

Overview

Single Sign-On lets people authenticate through an external identity provider (IdP) such as Okta, Microsoft Entra, or Google Workspace, instead of a Canopy password. Canopy speaks both SAML 2.0 and OIDC, and verifies every assertion or token before trusting it.

Two surfaces

Admin SSO and end-user SSO are separate

There are two independent SSO surfaces. Admin SSO lets your Account's admins sign into the Canopy Console through your corporate IdP, configured once per Account. End-user SSO lets your application's end users sign in through their corporate IdP, two ways: during the hosted OAuth flow (configured per OAuth client, so one client can accept several upstream IdPs) or through the Direct-API flow with a publishable key (bound per environment). Run either, both, or neither.

Connections

Each integration is a connection holding the IdP's details: SAML metadata, or an OIDC discovery URL plus client credentials. A connection moves through a simple lifecycle:

configuring: created but not yet complete; not accepting logins.

active: validated and live; users can authenticate through it.

disabled: turned off without being deleted.

Setup checklist

Work this checklist top to bottom. It's a two-sided exchange between Canopy and your IdP, plus a little routing on the Canopy side. The last step before activation differs for admin, hosted end-user, and Direct-API end-user SSO:

Create the connection. In Settings → Single Sign-On, add a connection, choose SAML 2.0 or OIDC, and name it.

Enter your IdP's details. Paste the SAML metadata XML (or the entity ID, sign-in URL, and signing certificate), or the OIDC discovery URL plus client ID and secret.

Copy Canopy's service-provider details into your IdP. Open the connection and copy the ACS / redirect URL, entity ID, and audience. End-user connections list endpoints for both the hosted-login (OAuth) and Direct-API (publishable-key) flows. Use the set that matches how your app signs users in.

Route users to the connection. For admin SSO, verify your email domain with a DNS-TXT record so admins route automatically. For end-user SSO, set the connection's email domains, or mark it the environment's default to send everyone there.

For Direct-API end-user SSO, bind the environment and allowlist your return URLs. Bind the connection to each environment that should accept it and set its placement (default node / role). Then add every post-login return URL under Settings → Browser auth. Canopy refuses to redirect anywhere that isn't on the allowlist.

Activate and test. Activate the connection once its config is complete, then run a full sign-in round-trip.

Security & provisioning

Verified, and provisioning depends on the surface

Canopy verifies each SAML assertion's signature, audience, and validity window, with IdP certificate pinning and replay protection, and validates OIDC tokens against the IdP's keys. What happens after verification depends on the surface. Admin SSO never auto-creates accounts: an admin must already be a member of the Account before they're admitted (a no-JIT pre-invite gate), so a misconfigured or rogue IdP can't mint Console admins. End-user SSO does just-in-time provisioning by design: on a verified user's first login Canopy creates their federated identity and grants them membership in the environment they signed into, so your app's users sign in without being pre-created. Verified email domains are exclusive to a single Account.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.