Plus One for Craft CMS

Plus One is a Craft 6 plugin. Craft 6 is still in beta, and so is Plus One (6.0.0-beta.1) — try it on staging first and use caution on production sites.

Providers

Providers live in Settings → Plugins → Plus One (stored in project config), or in config/craft/plusone.php under providers. Each row:

ColumnWhat it does
OnSwitch the provider off without deleting it.
HandleLower-case letters, numbers and dashes. It's in the URLs, so don't change it once people use it.
ProviderA Socialite driver, OpenID Connect (any provider), or an installed SocialiteProviders package.
NameShown on buttons: “Sign in with {name}”. Defaults to the provider's name.
Client IDLiteral or $ENV_VAR.
Client secretMust be $ENV_VAR.
Extra scopesAdded to the driver's defaults.
Sites* for every site, or site handles. See Multisite.
CP loginOffer it on the control panel's login page.
New usersIf public registration is on (Craft's setting), Always register or Never register.
Match by verified emailLet someone sign in to an existing account with the same email — only when the provider says it verified the address, Craft has verified the account's email too, and never for admins. See Security.
PKCEOn by default. Turn off only for a provider that rejects PKCE parameters.
Optionskey=value; key=value — see below.

Options

  • groups=handle, handle — extra user groups for people this provider registers (on top of the default group).
  • param.name=value — extra parameters for the authorization request, e.g. Google's param.hd=example.com (a hint only: use Allowed email domains to enforce it) or param.prompt=select_account.
  • OpenID Connect: authorize=https://…; token=https://…; userinfo=https://… (all three required, https).
  • SocialiteProviders: the package's own keys, e.g. Keycloak base_url=https://sso.example.com; realms=staff. Values may be $ENV_VAR references.

Callback URLs

Every Plus One provider returns to {site URL}/actions/plusone/callback/{handle}, one per site the provider is enabled on. The settings page lists them; register each with the provider. (Plus One uses an action URL rather than Craft's oauth/{handle}/callback because action URLs work on sites that live under a path, like https://example.com/fr/.)

Providers from oauthProviders in config/general.php keep Craft's own callback URL.

Built-in providers

Socialite's OAuth 2 drivers: Google, GitHub, GitLab, Bitbucket, Facebook, LinkedIn (OpenID), Slack (OpenID), Twitch and X. (Twitter's OAuth 1 driver isn't supported by Craft's OAuth.)

OpenID Connect (any provider)

For Authentik, Keycloak, Zitadel, Auth0, Okta, Microsoft Entra, a company SSO… anything that speaks OpenID Connect. Use its discovery document (/.well-known/openid-configuration) to find the three endpoints:

authorize=https://sso.example.com/application/o/authorize/; token=https://sso.example.com/application/o/token/; userinfo=https://sso.example.com/application/o/userinfo/

Scopes default to openid email profile. The provider's email_verified claim is what Match by verified email and Require a verified email rely on.

SocialiteProviders packages

SocialiteProviders has 100+ community providers. Install one with Composer and it appears in the Provider menu as socialiteproviders/<name> — no service provider or event listener to register:

composer require socialiteproviders/keycloak

Its extra settings go in Options (the settings page lists each installed package). OAuth 1 packages aren't supported.

Catalogue

ProviderTypeWhere to create the clientNotes
Googlebuilt-in googleconsole.cloud.google.com → APIs & Services → CredentialsSends email_verified. param.hd= hints a Workspace domain.
GitHubbuilt-in githubgithub.com/settings/developers → OAuth AppsOnly returns verified emails.
GitLabbuilt-in gitlabgitlab.com/-/user_settings/applicationsScopes read_user. Self-hosted: use OpenID Connect.
Microsoft / Entra IDsocialiteproviders/microsoft or OpenID Connectportal.azure.com → App registrationsEntra's email is not always verified: leave Match by verified email off.
Applesocialiteproviders/appledeveloper.apple.com → Identifiers → Services IDsNeeds a generated client secret (JWT); see the package's README.
Facebookbuilt-in facebookdevelopers.facebook.com → AppsNo email_verified claim: treated as unverified.
LinkedInbuilt-in linkedin-openidlinkedin.com/developers → AppsSends email_verified.
Slackbuilt-in slack-openidapi.slack.com/apps
Discordsocialiteproviders/discorddiscord.com/developers/applicationsSends verified; not mapped — treated as unverified.
Keycloaksocialiteproviders/keycloakKeycloak admin → ClientsOptions base_url=…; realms=….
Authentik, Zitadel, Auth0, OktaOpenID Connectthe provider's adminSends email_verified.

A provider that doesn't say an email is verified is treated as unverified: it can still sign people in to accounts they've connected, but can't register them while Require a verified email is on, and can't match existing accounts by email.

Providers in config/general.php

Craft's own oauthProviders config keeps working next to Plus One's. Plus One's sign-in rules (see Security) apply to those providers too, as long as they use Craft's default user resolver. A Plus One provider can't reuse a handle from that config.

More plugins

Pairs well with Plus One