oidc method uses OpenID Connect, or OAuth2 where OpenID Connect is not
supported, to authenticate identities using a third-party identity provider,
such as Google, Microsoft, GitHub - or any other OAuth2 / OpenID Connect
provider (for example ORY Hydra). "Social Sign In"
or "Sign in with ..." are common aliases for this flow.
This strategy expects that you've set up your Default Identity JSON Schema.
You can configure multiple OAuth2 / OpenID Connect providers. First, enable the
Next, you need to configure the providers you want to use (e.g. GitHub).
The most important configuration key is the provider's
id. Once set, you
should never remove or change that
id. Otherwise, your existing users will no
longer be able to sign in.
The provider configuration looks as follows:
It is very important to add the "session" hook to the after oidc registration hooks. Otherwise your users need to use the login flow again to be able to get a session.
Data Mapping with Jsonnet
The data provided by Google, GitHub, Facebook, and others will vary in payloads.
One service might include the
phone_number while another might
Therefore you need to specify how this data maps to the identity's traits. You can do that by writing a Jsonnet Code Snippet and referencing that in your ORY Kratos config file:
ORY Kratos adds an external variable called
claims to the data mapper. It
contains all the claims (e.g. username, email, ...) for the OpenID Connect or
OAuth2 Provider. Keep in mind that the claims will vary per provider and per
flow - depending on what permissions the user grants you (e.g. "App XYZ cannot
see my private email"). Your Jsonnet code must return a JSON object that looks
For more information on Jsonnet check out our Jsonnet Documentation.
To debug Jsonnet payloads, use the
--dev flag and set
LOG_LEVEL=debug kratos serve --dev). Logs with detailed payloads will be
emitted once you complete an OpenID Connect / OAuth2 login or registration.
The Jsonnet code snippet
when the ID Token body (or the OAuth2 equivalent) returned by the OpenID Connect provider contains:
which is then being used for the identity's traits.
sub field, which is returned by OpenID Connect and OAuth2 servers alike is
used as the primary credential identifier for the provider. This allows ORY
Kratos to link the identity to the "social sign in profile" for future login
std.ExtVar('claims') object has the following structure and keys
Identity Traits Validation and Data Completion
Sometimes the data provided by OpenID Connect or OAuth2 Providers is not enough. A common example is asking the user to consent to the terms of service. No OpenID Connect or OAuth2 provider will be able to give you this information because these are your terms. Another example would be a user not agreeing to share his/her email address with you when authorizing your OAuth2 app.
If such a validation error occurs, the user will be redirected to the Registration UI. The Registration Request includes all the valid and invalid fields:
When submitting the form again, the data provided by the user and the data coming from the OpenID Connect / OAuth2 provider will be merged. This process repeats itself
until the identity's traits are valid against the defined JSON Schema.
For more information on this flow (network flow, examples, UI, ...) head over to the OpenID Connect and OAuth2 Self-Service Strategy Documentation.