/configure-entraid

name: webiny-configure-entraid
description: >
  Configuring Microsoft Entra ID (formerly Azure AD) as a federated identity
  provider for Webiny projects using Cognito Federation. Use this skill when the
  developer asks about Entra ID, Azure AD, Microsoft SSO, OIDC with Microsoft,
  Microsoft login for Webiny, or configuring login.microsoftonline.com as an
  identity provider. Also relevant for tenant IDs, Entra application registration,
  or connecting Microsoft 365 accounts to Webiny.

Configure Microsoft Entra ID Authentication

TL;DR

Webiny supports Microsoft Entra ID (formerly Azure AD) as a federated identity provider through Cognito Federation. Unlike Okta or Auth0 which replace Cognito entirely, Entra ID works **alongside** Cognito — users authenticate via Microsoft, but Cognito remains the user pool. Configure it by adding `federation` to the `<Cognito />` extension in `webiny.config.tsx` with your Entra ID application's client ID, client secret, and issuer URL.

Prerequisites

Before configuring Webiny, you need to register an application in the Microsoft Entra ID portal:

1. Go to [Microsoft Entra admin center](https://entra.microsoft.com) > **App registrations** > **New registration** 2. Set a name (e.g., "Webiny Admin") 3. Set **Supported account types** (typically "Accounts in this organizational directory only") 4. Set **Redirect URI**: Web — use your Cognito domain callback URL (you'll get this after the first deploy: `https://{domain}.auth.{region}.amazoncognito.com/oauth2/idpresponse`) 5. After registration, note:

• **Application (client) ID** — this is your `client_id`
• **Directory (tenant) ID** — part of your issuer URL

6. Go to **Certificates & secrets** > **New client secret** — note the **Value** (this is your `client_secret`) 7. The **Issuer URL** is: `https://login.microsoftonline.com/{tenant-id}/v2.0`

Reference Tables

Required Entra ID Values

| Value | Where to find it | Used as | | ----------------------- | ----------------------------------------- | ------------------------------------ | | Application (client) ID | App registration > Overview | `client_id` in `providerDetails` | | Client secret value | App registration > Certificates & secrets | `client_secret` in `providerDetails` | | Directory (tenant) ID | App registration > Overview | Part of `oidc_issuer` URL |

Environment Variables

| Variable | Description | | --------------------- | ---------------------------------------------------- | | `ENTRA_CLIENT_ID` | Entra ID Application (client) ID | | `ENTRA_CLIENT_SECRET` | Entra ID client secret value | | `ENTRA_ISSUER` | `https://login.microsoftonline.com/{tenant-id}/v2.0` |

Attribute Mapping

When Cognito receives tokens from Entra ID, it maps the OIDC claims to Cognito user attributes. The default OIDC mapping is:

| Cognito Attribute | OIDC Claim | Description | | -------------------- | ------------- | ---------------------------------- | | `username` | `sub` | Unique user identifier | | `custom:id` | `sub` | Webiny internal user ID | | `email` | `email` | User's email address | | `given_name` | `given_name` | First name | | `family_name` | `family_name` | Last name | | `preferred_username` | `email` | Used as the Cognito username alias |

You can override this mapping with the `attributeMapping` property on the identity provider config. This is useful when:

• Your Entra ID uses non-standard claim names
• You want to skip `custom:id` mapping (e.g., when the `sub` value exceeds the attribute's max length on existing pools)
• You need to map additional custom attributes

{
    name: "EntraID",
    type: "oidc",
    label: "Sign in with Microsoft",
    providerDetails: { /* ... */ },
    attributeMapping: {
        username: "sub",
        email: "email",
        given_name: "given_name",
        family_name: "family_name",
        preferred_username: "email"
        // custom:id intentionally omitted
    }
}

When `attributeMapping` is provided, it **replaces** the defaults entirely — include all mappings you need.

Full Examples

Example 1: Basic Entra ID Federation

**Step 1: Set environment variables**

Add to your `.env` file:

# NOTE: these are made up example values
ENTRA_CLIENT_ID=f62ee823-2811-8314-a040-62848442c0d5
ENTRA_CLIENT_SECRET=~Gp7Q~97MAzTAUyeTLzTVzX31DRTY28chehU6c_a
ENTRA_ISSUER=https://login.microsoftonline.com/1cd0d912-0ac4-48a0-91b6-cd849ce9498f/v2.0

**Step 2: Create the extension**

Create `extensions/entraid/Extension.tsx`:

import React from "react";
import { Cognito } from "@webiny/cognito";

export const CognitoFederation = () => {
  return (
    <Cognito
      federation={{
        domain: "my-app-entraid",
        callbackUrls: ["http://localhost:3001"],
        responseType: "code",
        identityProviders: [
          {
            name: "EntraID",
            type: "oidc",
            label: "Sign in with Microsoft",
            providerDetails: {
              attributes_request_method: "POST",
              authorize_scopes: "email profile openid",
              client_id: String(process.env.ENTRA_CLIENT_ID),
              client_secret: String(process.env.ENTRA_CLIENT_SECRET),
              oidc_issuer: String(process.env.ENTRA_ISSUER)
            }
          }
        ]
      }}
    />
  );
};

**Step 3: Register in `webiny.config.tsx`**

import { CognitoFederation } from "@/extensions/entraid/Extension.js";

export const Extensions = () => {
  return (
    <>
      {/* Replace <Cognito /> with the federation extensi