Social Login | Canopy Docs

How social login works

A person clicks Continue with Google, signs in at Google, and comes back signed in to your application, with no password of yours to set. The same works for GitHub, Microsoft, Apple and any OpenID Connect provider you add.

Each Environment holds its own providers and its own credentials from them, so Development and Production sign in through separate apps at the provider.

An enabled provider is a sign-in method like a password or an emailed code: it shows as a button on the hosted sign-in and sign-up pages, is listed in social_providers on GET /v1/identity/auth/config for your own login page, and an organization's policy can narrow it.

A provider account belongs to one identity, and an identity can hold several, Google and GitHub, say. Once linked, the account signs that identity in, whatever email the provider reports later.

Social login is on every plan.

Set up a provider

Create the credentials at the provider, then add them in the Developer Console under Authentication, on the Social sign-in tab (step by step). At the provider, register the Callback URL the dialog shows as the redirect URI: the API's address followed by /v1/identity/auth/social/<name>/callback, where the name is google, github, microsoft, apple, or the Name in Canopy you give a custom provider.

Provider	Credentials	What to enter	Verified email
Google	An OAuth client ID of type Web application in the Google Cloud console.	Client ID and Client secret	An address Google reports as verified.
GitHub	An OAuth app under Developer settings in GitHub.	Client ID and Client secret	The primary address GitHub has verified.
Microsoft	An application in the Microsoft Entra admin center, for accounts in any organization and personal Microsoft accounts.	Client ID and Client secret	A personal Microsoft account's address, or a work or school address on a domain its organization verified. Any other work address was typed by an administrator and does not count.
Apple	A Services ID and a Sign in with Apple key in your Apple Developer account.	Services ID, Team ID, Key ID and Private key (.p8)	An address Apple reports as verified.
Custom OpenID Connect	Register Canopy as a client of your provider.	Button label, Name in Canopy, Discovery URL, Client ID, Client secret and Scopes	An address the provider vouches for with `email_verified`, in the ID token or from its userinfo.

Google, GitHub, Microsoft and Apple can each be added once per Environment, and up to 20 custom providers. A custom provider is saved off: run Test sign-in on it, and once a test succeeds, turn on Offer this provider at sign-in. Client secrets and Apple's key are write-only, and stored encrypted.

Which identity a sign-in reaches

Canopy works out who is signing in, in this order:

A linked account signs in the identity it is linked to.

Otherwise the email decides, so the provider must have verified it (see the table above). An address it did not verify is refused with social.email_unverified.

An identity with that email is linked and signed in. An identity holds one account at each provider, so one that already has an account at this provider is signed in without a second link. If the identity's own email was never verified, its password is removed and the address marked verified: the provider proved who owns the address, and whoever set that password may not.

No identity with that email: with self-signup on, one is created with its email verified, under the same daily limit, plan limit and organization on sign-up as a password sign-up. With self-signup off, the sign-in is refused with social.no_identity.

Whichever way it is reached, the identity must be a member of the Environment and must not be deactivated (auth.account_deactivated). An identity its organization's single sign-on manages is never linked, by its email, from the security page or through the Direct API (social.identity_sso_managed); an account it had already linked still signs it in while its organization's policy allows that provider. Every refusal code is listed on the Direct API page.

Where people sign in

Hosted login. Each enabled provider is a Continue with button above the sign-in form, and above the sign-up form while self-signup is on. After the provider, a brief Signing you in page finishes the sign-in on the address it started on, your custom auth domain included, so a remembered device still skips the second factor, and your application receives a code as after any hosted sign-in. A refusal comes back to the page the person started on, with its reason. See Hosted Login.

Your own login page. Redirect the browser to /v1/identity/auth/social/:provider/start with your publishable key, a return URL from the Environment's Redirect URLs and a state, then exchange the sso_token it returns with at POST /v1/identity/auth/sso/authenticate. A sign-in not finished at the provider within 10 minutes is refused. See Direct API.

Organizations and MFA

An organization's sign-in policy can keep or refuse each provider as a method of its own: google, github, microsoft, apple, or oidc:<name> for a custom one, but never one the Environment has turned off. A member signing in with a refused provider gets organization.sign_in_method_not_allowed. See Organizations.

An organization that requires single sign-on refuses social sign-in for its members, and for any email whose domain routes to its connection (organization.sso_required).

A social sign-in owes the second factor as a password sign-in does: the Environment's and the organization's MFA requirements apply. It is never treated as single sign-on, so an Environment that waives MFA after SSO does not waive it here. The tokens record the provider in amr, for example ["fed", "google"].

Linked accounts

On the self-service security page, a person sees a row per provider the Environment offers. Link adds an account and Unlink removes one, each after the person confirms it's them: with their current password, a second factor, or a code emailed to their verified address when they have neither. An unlink that would leave no way to sign in is refused. An app with its own account screen offers the same through the Direct API, at /v1/identity/auth/social-links, with the same proof and the same refusals (see Direct API, account management). A person links one account at each provider; a second is refused until the first is unlinked.

Someone who signed up through a provider has no password. The same page offers them Set password.

Administrators see the links, read-only: in social_links on GET /api/v1/identities/:id, and as Linked accounts in the identity's panel in the Console and the Admin Workspace. Erasing an identity deletes its links.

Each link and unlink is in the audit log and fires a webhook, identity.social_link.added or identity.social_link.removed. See Webhook Event Types.

Environment

API version

v1.0

On this page

Was this page helpful?

Tell us how we can improve this guide.