Terminal
Terminal/Skill
Adds sign-in with Google, GitHub, Apple, Microsoft, Discord and other providers to an Ory project.
By Ory
Works with
npx skills add ory/claude-plugins --skill ory-social-loginYou are configuring social login (OAuth2/OIDC) providers for an Ory-powered application. This adds "Sign in with Google", "Sign in with GitHub", and similar buttons to the login and registration flows.
Strong recommendation: render the auth UI with Ory Elements.
With Ory Elements, social buttons appear automatically the moment a
provider is configured on the project — there is no frontend change
required for any of the providers below. If the app is using custom
flow rendering, point the user to /project:ory-login-flow and
recommend switching to Ory Elements before adding more providers.
Ory CLI — run ory version. If not installed:
brew install ory/tap/clinpm install -g @ory/cliOry project — run ory list projects to find the project ID.
If no project exists, suggest /project:ory-auth-setup first.
Auth pages built with Ory Elements — confirm the project uses
@ory/elements-react (look for <Login> / <Registration> from
@ory/elements-react/theme). If pages are not built yet, suggest
/project:ory-login-flow first. If a custom UI was hand-rolled,
recommend migrating to Ory Elements so social buttons render for
free.
Social login depends on the same wiring as the rest of Ory. Before
debugging providers, confirm the base app is correct per the Correctness
contract in /project:ory-auth-setup: a first-party SDK URL (the tunnel or local
gateway in dev, never *.oryapis.com in the browser), routes that match the
project config, and your app origin listed in allowed_return_urls. The
provider redirects the browser back through Ory to your app, so a missing
return URL or a cross-site SDK URL produces a post-login error or 404 that looks
like a provider bug but isn't.
Ask the user which social login providers they want. Common options:
| Provider | OIDC Type | What you need |
|---|---|---|
| OIDC | Google Cloud Console OAuth2 credentials | |
| GitHub | OAuth2 | GitHub OAuth App or GitHub App |
| Apple | OIDC | Apple Developer account, Service ID |
| Microsoft | OIDC | Azure AD app registration |
| Discord | OAuth2 | Discord Developer Portal application |
| Slack | OIDC | Slack API app |
| GitLab | OIDC | GitLab application |
| OAuth2 | Meta Developer app |
Guide the user through creating credentials for each selected provider. They will need to set these up in the provider's developer console.
https://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/googlehttps://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/githubhttps://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/apple.p8 filehttps://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/microsofthttps://<project-slug>.projects.oryapis.com/self-service/methods/oidc/callback/discordUse the Ory CLI to add each provider. The configuration uses JSON patches.
ory patch identity-config <project-id> \
--add '/selfservice/methods/oidc/config/providers/-={
"id": "google",
"provider": "google",
"client_id": "<GOOGLE_CLIENT_ID>",
"client_secret": "<GOOGLE_CLIENT_SECRET>",
"mapper_url": "base64://MAPPER_CONTENT",
"scope": ["openid", "email", "profile"]
}' \
--replace '/selfservice/methods/oidc/enabled=true'
ory patch identity-config <project-id> \
--add '/selfservice/methods/oidc/config/providers/-={
"id": "github",
"provider": "github",
"client_id": "<GITHUB_CLIENT_ID>",
"client_secret": "<GITHUB_CLIENT_SECRET>",
"mapper_url": "base64://MAPPER_CONTENT",
"scope": ["user:email"]
}' \
--replace '/selfservice/methods/oidc/enabled=true'
ory patch identity-config <project-id> \
--add '/selfservice/methods/oidc/config/providers/-={
"id": "apple",
"provider": "apple",
"client_id": "<APPLE_SERVICE_ID>",
"apple_team_id": "<TEAM_ID>",
"apple_private_key_id": "<KEY_ID>",
"apple_private_key": "<PRIVATE_KEY_CONTENTS>",
"mapper_url": "base64://MAPPER_CONTENT",
"scope": ["openid", "email", "name"]
}' \
--replace '/selfservice/methods/oidc/enabled=true'
ory patch identity-config <project-id> \
--add '/selfservice/methods/oidc/config/providers/-={
"id": "microsoft",
"provider": "microsoft",
"client_id": "<MICROSOFT_CLIENT_ID>",
"client_secret": "<MICROSOFT_CLIENT_SECRET>",
"microsoft_tenant": "common",
"mapper_url": "base64://MAPPER_CONTENT",
"scope": ["openid", "email", "profile"]
}' \
--replace '/selfservice/methods/oidc/enabled=true'
ory patch identity-config <project-id> \
--add '/selfservice/methods/oidc/config/providers/-={
"id": "discord",
"provider": "discord",
"client_id": "<DISCORD_CLIENT_ID>",
"client_secret": "<DISCORD_CLIENT_SECRET>",
"mapper_url": "base64://MAPPER_CONTENT",
"scope": ["identify", "email"]
}' \
--replace '/selfservice/methods/oidc/enabled=true'
Each provider needs a Jsonnet mapper that maps the provider's claims to Ory identity traits. Create a mapper file for each provider.
This works for Google, GitHub, Microsoft, Discord, and most providers:
local claims = {
email_verified: false,
} + std.extVar('claims');
{
identity: {
traits: {
[if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
},
},
}
Apple sends name data only on first login:
local claims = {
email_verified: false,
} + std.extVar('claims');
{
identity: {
traits: {
[if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
},
},
}
To use these mappers, either:
mapper_url: "base64://..."
in the provider configmapper_url: "https://..."
in the provider configTo base64-encode a mapper file:
base64 -i mapper.jsonnet
Then set mapper_url to "base64://<encoded-content>" in the provider configuration.
If the app uses Ory Elements (the recommended setup), no frontend
changes are needed. The <Login> and <Registration> components
read the available methods from the flow object and render the
appropriate social buttons automatically — including provider icons
and labels.
Reload the login page and confirm the new buttons appear. If they do not:
<Login flow={flow} /> from
@ory/elements-react/theme, not a custom UI.Use this only if the user has explicitly chosen not to use Ory Elements. In that case, render the OIDC nodes from the flow:
flow.ui.nodes
.filter(node => node.group === "oidc")
.map(node => {
// Each node represents a social login button.
// node.attributes contains the provider id and label.
// Render a button that submits the form with the provider value.
});
Before going down this path, recommend switching to Ory Elements via
/project:ory-login-flow so future provider additions don't require
frontend work.
For each configured provider:
ory list identities --project <project-id>When a user logs in with a social provider whose email matches an existing account, Ory can either:
Configure the linking strategy:
ory patch identity-config <project-id> \
--replace '/selfservice/methods/oidc/config/enabled=true'
When manual linking is required, Ory Elements renders the linking prompt automatically — no UI work needed.
https://<slug>.projects.oryapis.com/self-service/methods/oidc/callback/<provider-id>ory get identity-config <project-id> --format json | jq '.selfservice.methods.oidc'
Then reload the page so a fresh flow is initialized.flow.ui.nodes filtered by group === "oidc". The simplest
fix is to migrate to Ory Elements.ory tunnel to proxy requests — social
login requires proper cookie handling that localhost alone can't provide