Version: v0.4

Sign in with GitHub, 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

GitHub

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:4455/.ory/kratos/public/self-service/browser/flows/strategies/oidc/callback/github

The pattern of this URL is:

http(s)://<domain-of-ory-kratos>:<public-port>/self-service/browser/flows/strategies/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:

contrib/quickstart/kratos/email-password/oidc.github.jsonnet
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.

contrib/quickstart/kratos/email-password/.kratos.yml
# $ kratos -c path/to/my/kratos/config.yml serve
selfservice:
strategies:
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!

Microsoft

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.

Creating an 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/browser/flows/strategies/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.

Configuring Kratos

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.

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.

contrib/quickstart/kratos/email-password/.kratos.yml
selfservice:
strategies:
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.

Choosing Tenant

There are two ways to use the microsoft provider for authentication:

  1. For authenticating users in a single Azure AD Directory (organisation), set the tenant value to either the Directory ID from the "App Registration" page, or the organisation domain. E.g. 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 or contoso.onmicrosoft.com.
  2. For authenticating any user in the Microsoft identity platform, set the tenant value to either:
    • organizations to allow users with work or school accounts, or
    • consumers to allow users with personal accounts, or
    • common to allow both kind of accounts.

Google, LinkedIn, Facebook

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! :)

Last updated on by Vincent