id | title |
---|---|
sign-in-with-github-google-facebook-linkedin |
Sign in with GitHub, GitLab, Google, Facebook, LinkedIn, Microsoft ... |
In this document we will take a look at setting up "Sign in with GitHub" using ORY Kratos.
Run the Quickstart with Docker Compose:
# This assumes that you have ORY Kratos checked out locally and
# that your current directory ("pwd") is the folder where ORY Kratos
# is.
$ make quickstart
:::info
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.
# $ kratos -c path/to/my/kratos/config.yml serve
selfservice:
flows:
registration:
after:
oidc:
hooks:
- hook: session
:::
<iframe width="560" height="315" src="https://www.youtube.com/embed/Hz_dP5c_qvc" frameborder="0" allowfullscreen />To set up "Sign in with GitHub" you must create a GitHub OAuth2 Client.
Set the "Authorization callback URL" to:
http://127.0.0.1:4433/self-service/methods/oidc/callback/github
The pattern of this URL is:
http(s)://<domain-of-ory-kratos>:<public-port>//self-service/methods/oidc/callback/<provider-id>
The provider ID must point to the provider's ID set in the ORY Kratos configuration file (explained in further detail at OpenID Connect and OAuth2 Credentials).
:::note
GitHub does not implement OpenID Connect. Therefore, ORY Kratos makes a request
to
GitHub's User API
and adds that data to std.extVar('claims')
. Check out what data is available
at
GitHub's Scope Docs.
Not all GitHub fields are supported however. Check the list of supported fields
in Kratos' source code.
:::
As explained in
OpenID Connect and OAuth2 Credentials,
you must also create a Jsonnet code snippet for the provider. Save the code in
<kratos-directory>/contrib/quickstart/kratos/email-password/oidc.github.jsonnet
.
The following JsonNet takes email_primary
and maps it to traits.email
:
local claims = {
email_verified: false
} + std.extVar('claims');
{
identity: {
traits: {
// Allowing unverified email addresses enables account
// enumeration attacks, especially if the value is used for
// e.g. verification or as a password login identifier.
//
// Therefore we only return the email if it (a) exists and (b) is marked verified
// by GitHub.
[if "email" in claims && claims.email_verified then "email" else null]: claims.email,
},
},
}
Now, enable the GitHub provider in the ORY Kratos config located at
<kratos-directory>/contrib/quickstart/kratos/email-password/.kratos.yml
.
# $ kratos -c path/to/my/kratos/config.yml serve
selfservice:
methods:
oidc:
enabled: true
config:
providers:
- id: github # this is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
provider: github
client_id: .... # Replace this with the OAuth2 Client ID provided by GitHub
client_secret: .... # Replace this with the OAuth2 Client Secret provided by GitHub
mapper_url: file:///etc/config/kratos/oidc.github.jsonnet
scope:
- user:email
Next, open the login endpoint of the SecureApp and you should see the GitHub Login option!
To set up "Sign in with GitLab" you must create a GitLab OAuth2 Application.
Set the "Redirect URI" to:
http://127.0.0.1:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/callback/gitlab
The pattern of this URL is:
http(s)://<domain-of-ory-kratos>:<public-port>/self-service/browser/flows/strategies/oidc/callback/<provider-id>
:::note
While you can use GitLab as an OIDC identity provider,
GitLab only returns the sub and sub_legacy claims in the ID token.
Therefore, ORY Kratos makes a request to GitLab's /oauth/userinfo API and adds the user info to std.extVar('claims')
.
:::
local claims = {
email_verified: false
} + std.extVar('claims');
{
identity: {
traits: {
// Allowing unverified email addresses enables account
// enumeration attacks, especially if the value is used for
// e.g. verification or as a password login identifier.
//
// Therefore we only return the email if it (a) exists and (b) is marked verified
// by GitLab.
[if "email" in claims && claims.email_verified then "email" else null]: claims.email,
},
},
}
Now, enable the GitLab provider in the ORY Kratos config located at
<kratos-directory>/contrib/quickstart/kratos/email-password/.kratos.yml
.
# $ kratos -c path/to/my/kratos/config.yml serve
selfservice:
strategies:
oidc:
enabled: true
config:
providers:
- id: gitlab # this is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
provider: gitlab
client_id: .... # Replace this with the OAuth2 Client ID provided by GitLab
client_secret: .... # Replace this with the OAuth2 Client Secret provided by GitLab
mapper_url: file:///etc/config/kratos/oidc.gitlab.jsonnet
scope:
- read_user
- openid
- profile
- email
GitLab is now an option to log in via Kratos.
This will enable you to log in using any Azure AD directory - Multitenant and personal Microsoft accounts (e.g. Skype, Xbox) depending on the settings made when creating the application in Azure AD.
To set up "Sign in with Microsoft" you must first register an application with the Microsoft identity platform.
Select "Web" as the "Redirect URI" type, and set the URI to:
http(s)://<domain-of-ory-kratos>:<public-port>//self-service/methods/oidc/callback/<provider-id>
After the "App Registration" is created, make note of the Application ID
and
Directory ID
on top of the Overview page. To create the client secret,
navigate to "Certificates & secrets" and click "+ New client secret". Remember
to copy the secret value as it will only be shown once.
Create a Jsonnet claims mapper as described in
OpenID Connect and OAuth2 Credentials.
Save the code in
<kratos-directory>/contrib/quickstart/kratos/email-password/oidc.microsoft.jsonnet
.
local claims = std.extVar('claims');
{
identity: {
traits: {
// Allowing unverified email addresses enables account
// enumeration attacks, especially if the value is used for
// e.g. verification or as a password login identifier.
//
// If connecting only to your organization (one tenant), claims.email is safe to use if you have not actively disabled e-mail verification during signup.
//
// The email might be empty if the account is not linked to an email address.
// For a human readable identifier, consider using the "preferred_username" claim.
[if "email" in claims then "email" else null]: claims.email,
},
},
}
Enable the Microsoft provider in the ORY Kratos config located at
<kratos-directory>/contrib/quickstart/kratos/email-password/.kratos.yml
.
selfservice:
methods:
oidc:
enabled: true
config:
providers:
- id: microsoft # this is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
provider: microsoft
client_id: .... # Replace this with the Application ID from the App Registration
client_secret: .... # Replace this with the generated Secret value from the App Registration
tenant: .... # Replace this with the Tenant of your choice (see below)
mapper_url: file:///etc/config/kratos/oidc.microsoft.jsonnet
scope:
- profile
- email
Azure AD is now an option to log in to kratos.
There are two ways to use the microsoft
provider for authentication:
- For authenticating users in a single Azure AD Directory (organisation), set
the
tenant
value to either theDirectory ID
from the "App Registration" page, or the organisation domain. E.g.8eaef023-2b34-4da1-9baa-8bc8c9d6a490
orcontoso.onmicrosoft.com
. - For authenticating any user in the Microsoft identity platform, set the
tenant
value to either:organizations
to allow users with work or school accounts, orconsumers
to allow users with personal accounts, orcommon
to allow both kind of accounts.
Connecting with other Social Sign In providers will be very similar to the GitHub flow. If you've managed to do it, add to this document by writing it down and making a PR! :)