Skip to main content

Microsoft

note

To add Microsoft as a social sign-in provider, you need an Azure account with an active subscription. Follow this link to create a free account.

Configuration in Ory Cloud Console​

Follow these steps to add Microsoft as a social sign-in provider for your Ory Cloud project using the Ory Cloud Console.

  1. Sign in to Ory Cloud Console and select Social Sign-in.

  2. Click the switch next to the Microsoft logo to start the configuration.

  3. Copy the Redirect URI from Ory and save it for later use.

  4. Go to the Azure portal → Azure Active Directory.

  5. From Overview, select Manage tenants from the top navigation. Choose the desired tenant or create a new one.

  6. Return to Overview, open the App registration dropdown menu and click App registration.

  7. Register a new application:

    • Define the app display name
    • Select the supported account types
    • Select the appropriate application type using the dropdown menu
    • Provide the Redirect URI copied from the Ory Console

  8. Copy the Application (client) ID from Azure and paste it into the corresponding field in the Ory Console.

  9. In Azure, click the Client credentials link and create a new client secret.

  10. Copy the Value of the client secret and paste it into the corresponding field in the Ory Console.

  11. Copy the Directory (tenant) ID from Azure and paste it into the corresponding field in the Ory Console.

  12. Click Save Configuration to enable Microsoft as a social sign-in provider.

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 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 to access additional user data, which is exposed as claims for data mapping.

For Microsoft, add the email and profile scopes for a basic setup.

Data Mapping​

The Data Mapping section allows you to map the data returned by the sign-in provider to traits as defined in the identity schema.

To define the mapping, create a Jsonnet code snippet. Read this document to learn more about Jsonnet data mapping.

local claims = 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.
      //
      // If connecting only to your organization (one tenant), claims.email is safe to use
      // if you haven't actively disabled e-mail verification during sign-up.
      //
      // The email might be empty if the account isn't 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,
    },
  },
}
warning

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 Cloud.

Selecting a Tenant​

When you add Microsoft as a social sign-in provider, you can define which user groups can sign in and sign up with Microsoft by setting a specific value of the Tenant field:

  1. To authenticate users that belong to a single, specific organization (Azure Active Directory), set the value to Directory (tenant) ID or the organization's domain, for example, example.onmicrosoft.com.

  2. To authenticate users with Microsoft accounts that are not limited to a specific organization, set Tenant value to:

    • organizations to allow users with work or school accounts
    • consumers to allow users with personal accounts
    • common to allow both kinds of accounts
info

To allow sign-in and sign-up for users with Microsoft accounts that don't belong to any organization (Azure Active Directory), you must adjust the Azure application configuration by editing the Manifest.

Learn more:

Configuration using the Ory CLI​

Follow these steps to add Microsoft as a social sign-in provider to your Ory Cloud project using the Ory CLI:

  1. Create an Azure AD Application and Tenant.

  2. Create a Jsonnet code snippet to map the desired claims to the Ory Identity schema.

  3. Encode the Jsonnet snippet with Base64 or host it under an URL accessible to Ory Cloud.

  4. Download the Identity Service config from your Ory Cloud project and save it to a file:

    ## List all available projects
    ory list projects

    ## Get config
    ory get identity-config <project-id> --format yaml > identity-config.yaml

  5. Add the social sign-in provider configuration to the downloaded config. Add the Jsonnet snippet with mappings as a Base64 string or provide an URL to the file.

    selfservice:
      methods:
        oidc:
          config:
            providers:
              - id: microsoft # this is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
                provider: microsoft
                client_id: .... # This is the the Application (client) ID from the App Registration
                client_secret: .... # This is the generated Secret value from the App Registration
                microsoft_tenant: .... # This allows you to select the tenant.
                mapper_url: "base64://<YOUR_BASE64_ENCODED_JSONNET_HERE>"
                # Alternatively, use an URL:
                # mapper_url: https://storage.googleapis.com/abc-cde-prd/9cac9717f007808bf17f22ce7f4295c739604b183f05ac4afb4
                scope:
                  - profile
                  - email
          enabled: true
    tip

    Read this section to learn more about selecting a Microsoft tenant.

  6. Update the Ory Cloud Identity Service configuration using the file you worked with:

    ory update identity-config <project-id> --file updated_config.yaml

Configuration for Self-hosted Instances​

Follow these steps to add Microsoft as a social sign-in provider when self-hosting Ory Kratos:

  1. Create an Azure AD Application and Tenant.

  2. Set the redirect URI to URL that follows this pattern:

    http(s)://<domain-of-ory-kratos>:<public-port>/self-service/methods/oidc/callback/<social-signin-provider-id>

  3. Create a Jsonnet code snippet to map the desired claims to the Ory Identity schema.

  4. Encode the Jsonnet snippet with Base64 or store it in a location available to your Ory Kratos instance.

  5. Add the social sign-in provider configuration to the Ory Kratos configuration. Add the Jsonnet snippet with mappings as a Base64 string or provide a path or an URL of the file.

tip

When running a self-hosted instance, you can pass the social sign-in provider configuration in the SELFSERVICE_METHODS_OIDC_CONFIG_PROVIDERS environment variable. For example:

SELFSERVICE_METHODS_OIDC_CONFIG_PROVIDERS='[{"id":"google","provider":"google","mapper_url":"<file_location>","client_id":"<client_id>","client_secret":"<client_secret>","scope":["openid","email","profile"],"auth_url":"https://accounts.google.com/o/oauth2/v2/auth","token_url":"https://www.googleapis.com/oauth2/v4/token","issuer_url":"https://accounts.google.com"}]'

Choosing source of subject identifier​

By default, Microsoft uses the identifier taken from the sub field of OIDC id_token. The same identifier is also returned by the standard OIDC /userinfo endpoint.

However, some systems use the id field returned by the https://graph.microsoft.com/v1.0/me endpoint as a subject identifier. To make migrating such systems to Kratos easier, you can use the identifier from obtained from the me endpoint.

To do that, add the subject_source field set to me to the social sign-in provider config for your Kratos instance.

kratos-config.yaml
  providers:
  - id: microsoft # this is `<provider-id>` in the Authorization callback URL. DO NOT CHANGE IT ONCE SET!
    provider: microsoft
    client_id: .... # This is the the Application (client) ID from the App Registration
    client_secret: .... # This is the generated Secret value from the App Registration
    microsoft_tenant: .... # This allows you to select the tenant.
    subject_source: me
    # or
    # subject_source: userinfo
    mapper_url: 'base64://<YOUR_BASE64_ENCODED_JSONNET_HERE>'
    scope:
    - profile
    - email

Prevent Having to Login after Sign-Up​

When adding social sign-in providers manually, remember to add the session hook to after/oidc/hooks. If you don't add this hook, users will have to login again after signing up to get a session.

selfservice:
  flows:
    registration:
      after:
        oidc:
          hooks:
            - hook: session