1. Docs
  2. Organizations
  3. Where customers configure sign-in

Where customers configure sign-in

Single sign-on and multi-factor authentication can be set in three places. They write the same policy, so the decision is who you want holding the controls.

The Three Routes

All three end at the same organization policy and the same connection records. Nothing is a lesser copy of anything else; they differ only in who sits at the keyboard.

The Developer Console — your own staff

Your team opens an organization and sets its policy directly, on Access Control → Organizations → the organization → Policy. Use it to onboard an enterprise customer whose contract calls for a setting, and to see or repair what a customer has done. It is not for your customers: they have no Console account, and giving them one would hand them your whole Environment.

Our API — inside your own product

You build the settings screen and call the organization endpoints behind it. Your customer never leaves your product and the page is yours to design. You own the work: the screens, the states, the copy, and keeping them current as the policy grows. Either your backend calls with an API key, or the customer's own admin calls with their session token.

The hosted portal — nothing to build

You link your customer's admins to the portal and we render it, wearing your product name, logo, and color. It covers members, the authentication policy, and single sign-on end to end, including the domain and provider steps. You build no screens; in exchange the pages are ours, so they follow our layout rather than yours.

Choosing One

The Console is for your staff and sits alongside whichever of the other two you pick. The real choice is between the API and the portal, and it comes down to one question: is configuring single sign-on part of the experience you want to design, or a chore you would rather hand off?

Pick the portal when you want this working this week, when single sign-on is a checkbox on your enterprise plan rather than a feature you market, or when you would rather not own the identity-provider screens as they change.Pick the API when the settings page must live inside your product's own navigation, when your design system is part of the sell, or when you already have a settings area these controls belong in.Pick one, not both. Two customer-facing front doors onto the same policy means two sets of copy to keep true and two places for a customer to be told different things. Nothing stops you switching later: the policy is stored in one place either way.

Whichever you pick, your staff keeps the Console, and the reserved permission decides who among your customer's people may use the portal or your own page.

Two Rules That Always Apply

Two things hold on all three routes, because they are enforced where the policy is stored rather than on any screen.

The Environment is the floor. An organization can tighten what you set for everyone and never loosen it. A write that would go below the floor is refused with organization.policy_loosens, whichever route sent it.The first admin comes from you. An organization's people cannot grant themselves the right to administer it. You assign a role carrying canopy:organization.manage when you provision the organization; after that its admins manage each other, and the last one cannot be removed.

Next Step

The reserved permission, the endpoints your own settings page calls, and the portal's own pages are all documented on the Organizations page.

Environment
API version
v1.0
 On this page Was this page helpful?

Tell us how we can improve this guide.

Canopy