Skip to main content
The OIDC (OpenID Connect) strategy enables social sign-in with third-party identity providers like Google, GitHub, Microsoft, and any OIDC-compliant provider.

​
Overview

The OIDC strategy provides:
  • Registration and login with social providers
  • Account linking with existing identities
  • Automatic data mapping from provider claims
  • Support for multiple providers simultaneously
  • Organization-specific OIDC providers

​
Configuration

​
Enable OIDC authentication

Configure OIDC providers in your Kratos configuration:
kratos.yml
selfservice:
  methods:
    oidc:
      enabled: true
      config:
        providers:
          - id: google
            provider: google
            client_id: YOUR_GOOGLE_CLIENT_ID
            client_secret: YOUR_GOOGLE_CLIENT_SECRET
            mapper_url: file:///etc/config/kratos/oidc.google.jsonnet
            scope:
              - email
              - profile
          - id: github
            provider: github
            client_id: YOUR_GITHUB_CLIENT_ID
            client_secret: YOUR_GITHUB_CLIENT_SECRET
            mapper_url: file:///etc/config/kratos/oidc.github.jsonnet
            scope:
              - user:email

​
Supported providers

Kratos includes built-in support for popular providers: 
- id: google
  provider: google
  client_id: YOUR_CLIENT_ID
  client_secret: YOUR_CLIENT_SECRET
  scope:
    - email
    - profile
Issuer: https://accounts.google.comImplementation: selfservice/strategy/oidc/provider_google.go:25
Other supported providers include:
  • Apple
  • Discord
  • Facebook
  • GitLab
  • LinkedIn
  • Slack
  • Spotify
  • Twitch
  • VK
  • Yandex
  • And more (see selfservice/strategy/oidc/provider_*.go files)

​
Identity schema configuration

​
Configure OIDC in schema

The identity schema doesn’t require specific OIDC configuration, but you should define the traits that will be populated from the provider:
identity.schema.json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "traits": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "title": "E-Mail"
        },
        "name": {
          "type": "object",
          "properties": {
            "first": {
              "type": "string",
              "title": "First Name"
            },
            "last": {
              "type": "string",
              "title": "Last Name"
            }
          }
        },
        "picture": {
          "type": "string",
          "format": "uri"
        }
      },
      "required": ["email"]
    }
  }
}

​
Data mapping with Jsonnet

​
Basic mapper

Use Jsonnet to map provider claims to identity traits:
oidc.google.jsonnet
local claims = std.extVar('claims');

{
  identity: {
    traits: {
      email: claims.email,
      name: {
        first: claims.given_name,
        last: claims.family_name,
      },
      picture: claims.picture,
    },
  },
}

​
Advanced mapper with conditions

oidc.github.jsonnet
local claims = std.extVar('claims');

{
  identity: {
    traits: {
      email: claims.email,
      username: claims.preferred_username,
      name: {
        first: if std.objectHas(claims, 'given_name') then claims.given_name else claims.name,
        last: if std.objectHas(claims, 'family_name') then claims.family_name else '',
      },
    },
  },
}
Jsonnet mappers have access to the claims object containing all data from the OIDC provider.

​
User flows

​
Registration with OIDC

1

Initialize registration

Create a registration flow and display OIDC provider buttons.
2

Initiate OIDC flow

Redirect the user to the provider:
curl -X POST https://your-kratos-instance/self-service/registration?flow=<flow-id> \
  -H "Content-Type: application/json" \
  -d '{
    "method": "oidc",
    "provider": "google"
  }'
The user is redirected to the provider’s authorization page.
3

Provider callback

After authentication, the provider redirects back to Kratos:
https://your-kratos-instance/self-service/methods/oidc/callback/google?code=...
4

Identity created

Kratos exchanges the code for tokens, validates them, and creates the identity using the Jsonnet mapper.

​
Login with OIDC

The login flow is identical to registration: 
curl -X POST https://your-kratos-instance/self-service/login?flow=<flow-id> \
  -H "Content-Type: application/json" \
  -d '{
    "method": "oidc",
    "provider": "google"
  }'
If the identity already exists (matched by email or provider subject), the user is logged in.

​
Account linking

Users can link additional OIDC providers through the settings flow: 
curl -X POST https://your-kratos-instance/self-service/settings?flow=<flow-id> \
  -H "Content-Type: application/json" \
  -H "Cookie: ory_kratos_session=<session-token>" \
  -d '{
    "method": "oidc",
    "link": "github"
  }'
The user can then log in using any of their linked providers.

​
Routes and endpoints

The OIDC strategy exposes these routes (defined in selfservice/strategy/oidc/strategy.go:60-65):
  • POST /self-service/methods/oidc/auth/{flow} - Initiate OIDC authentication
  • GET /self-service/methods/oidc/callback/{provider} - Provider callback URL
  • GET /self-service/methods/oidc/callback - Generic callback URL
  • GET /self-service/methods/oidc/organization/{organization}/callback/{provider} - Organization-specific callback

​
Security considerations

​
Configure redirect URIs

Always configure allowed return URLs to prevent open redirect vulnerabilities.
kratos.yml
selfservice:
  allowed_return_urls:
    - https://your-app.com
    - https://your-app.com/dashboard

​
Provider trust

When using OIDC:
  1. Only configure trusted providers
  2. Validate provider certificates (enabled by default)
  3. Use HTTPS for all redirect URIs
  4. Keep client secrets secure
  5. Regularly rotate client credentials

​
Email verification

Some providers return verified email claims. Configure your mapper to trust them: 
local claims = std.extVar('claims');

{
  identity: {
    traits: {
      email: claims.email,
    },
    verifiable_addresses: [
      {
        value: claims.email,
        verified: claims.email_verified,
        via: 'email',
      },
    ],
  },
}

​
Advanced features

​
Organization-specific providers

Configure OIDC providers per organization:
kratos.yml
selfservice:
  methods:
    oidc:
      config:
        providers:
          - id: enterprise-sso
            provider: generic
            organization: org_123
            issuer_url: https://sso.enterprise.com
            client_id: ORG_CLIENT_ID
            client_secret: ORG_CLIENT_SECRET

​
Custom claims and scopes

Request additional scopes and access custom claims:
kratos.yml
providers:
  - id: custom
    provider: generic
    issuer_url: https://provider.com
    scope:
      - openid
      - email
      - profile
      - custom_scope
    requested_claims:
      id_token:
        custom_claim:
          essential: true

​
Offline access

Request refresh tokens for offline access: 
providers:
  - id: google
    provider: google
    scope:
      - email
      - profile
      - offline_access  # For Google, this is handled automatically
For Google, offline_access is automatically converted to access_type=offline (see selfservice/strategy/oidc/provider_google.go:66-68).

​
API reference

​
Strategy implementation

  • Strategy ID: oidc
  • AAL Level: AAL1 (first factor authentication)
  • Base Route: /self-service/methods/oidc
See selfservice/strategy/oidc/strategy.go for full implementation.

​
Configuration schema

selfservice:
  methods:
    oidc:
      enabled: true
      config:
        providers:
          - id: google
            provider: google
            client_id: CLIENT_ID
            client_secret: CLIENT_SECRET
            mapper_url: file:///etc/config/oidc.jsonnet

​
Next steps

Build docs developers (and LLMs) love

Get started for freeTalk to us