Skip to main content

Ory

This document explains how to add Ory OAuth2 as an OIDC provider to your Ory Network project.

The setup we will describe here is as follows:

  1. An Ory Network project that serves as the SSO provider, manages user identities, and provides OAuth2/OIDC endpoints for authentication and authorization. It represents a Sign in with $YourBrand service.
  2. Another Ory Network project that uses this SSO provider for "social" sign-in. This represents a third-party app, service or website, or an independently operating subsidy or brand, that authenticates users via the SSO provider.

Setting up the SSO provider​

You can create projects and OAuth2 clients using either Ory Console or the Ory CLI.

The following snippet shows how to create it using the CLI:

ory create project --name "OAuth2 Server - Example Corp"
# Note down the project ID
export project_id=your-project-id # replace with your project ID

ory create oauth2-client --project "$PROJECT_ID" \
 --name "Example Corp" \
 --grant-type authorization_code,refresh_token \
 --response-type code \
 --scope openid,offline_access,email \
 --redirect-uri https://your-project-slug.projects.oryapis.com/self-service/methods/oidc/callback/H1o_k--i # replace with your redirect URI

The SSO provider projects define the identity schema and authentication methods for all projects that use it for sign-in.

With the SSO provider set up, you can now connect apps and other projects to it. OAuth2-enabled apps can sign in users via the SSO provider using the OAuth2 authorization code flow straight away.

Connecting a project to the SSO provider​

Third-party applications will typically

  • offer a Sign in with $YourBrand button, and optionally, more ways to register and log in like passkeys, passwords, or other social sign-in providers.
  • store identities for the application's user base, which is a subset of the identities managed by the SSO provider, plus any identities who sign in through other means.
  • store additional user data, which is not managed by the SSO provider, alongside a subset of the identity traits managed by the SSO provider.

Depending on your requirements, your "client" project will have a separate identity schema, authentication configuration and Account Experience theme.

Setting up authentication through the upstream SSO provider​

Adding Ory OAuth2 as a "social" sign-in provider is straightforward since Ory follows the OAuth2/OIDC specification. Because of this, you can add Ory OAuth2 as a generic OIDC provider without any extra setup. To add your Ory OAuth2 server as a social sign-in provider, you need the following configuration details:

  • Client ID - you get this when creating the client
  • Client Secret - you get this when creating the client
  • Issuer URL - this is the URL of the Ory Network project or Ory Hydra Federation server instance.

Follow these steps to add an Ory OAuth2 provider to your project using the Ory Console:

  1. Go to Authentication → Social Sign-In in the Ory Console.
  2. Click the Add new OpenID Connect provider button.
  3. Define the Label. This name is used for identification purposes only.
  4. Paste the configuration details obtained from your social sign-in provider into the corresponding fields in the Console:
    • Client ID
    • Client Secret
    • Issuer URL
  5. Copy the Redirect URI from the Console and add it to the OAuth2 client you created earlier. You can do this in the Ory Console or using the Ory CLI.
  6. Click Save Configuration to finish.
note

These steps cover the basic configuration of a social sign-in provider integration. At this point, the user experience is incomplete. To complete the configuration and ensure a smooth and secure user experience, configure the scopes and data mapping as described in the next section.

Additional configuration​

When adding a generic social sign-in provider, you can customize the integration by defining the OAuth scopes Ory requests from the provider and by setting up custom data mappings.

Scopes​

The Scopes section allows you to define the OAuth scopes Ory requests from the sign-in provider. Defining scopes allows you to interact with the provider's APIs on behalf of the user, or access additional user data, which is exposed as claims for data mapping.

For an out-of-the-box setup, use the default scopes openid, offline_access, and email.

Data mapping​

In the Data Mapping field of the form in the Ory Console, add the following Jsonnet code snippet, which maps the desired claims to the Ory Identity schema:

local claims = {
  email_verified: false,
} + std.extVar('claims');

{
  identity: {
    traits: {
      // Allowing unverified email addresses enables account
      // enumeration attacks,  if the value is used for
      // verification or as a password login identifier.
      //
      // Therefore we only return the email if it (a) exists and (b) is marked verified.
      [if 'email' in claims && claims.email_verified then 'email' else null]: claims.email,
    },
  },
}
danger

Don't save secrets such as API keys, credentials, or personal data directly in Jsonnet code snippets. Jsonnet code snippets used for data mapping aren't stored in an encrypted format in Ory Network.

Troubleshooting​

When you add a social sign-in provider, you can encounter common problems such as:

  • Redirect URI mismatch
  • Redirect loops during registration
  • Domain verification issues

To troubleshoot those issues, read Social sign-in troubleshooting.

Ory Network

The most flexible and scalable way to manage identi­ties, authen­tication, autho­rization and access control.Explore Ory Network

Explore Ory Network