Microsoft Entra ID (Azure AD) Authentication Integration

This guide covers integrating Microsoft Entra ID (formerly Azure Active Directory) authentication into a web application — for example, a Docusaurus documentation site — using MSAL (Microsoft Authentication Library) and Cloudflare Pages environment variables.

Reference: Docusaurus authentication with Entra ID and MSAL

---

Prerequisites

• Access to Microsoft Entra admin center with permissions to register applications
• A deployed application with known redirect URIs (e.g. a Cloudflare Pages URL and a local dev URL)
• Basic familiarity with Single Page Application (SPA) authentication flows (OAuth 2.0 / PKCE)

---

1. Register the Application in Microsoft Entra ID

Entra ID requires an App Registration to identify your application and configure allowed redirect URIs.

Steps

1. Go to https://entra.microsoft.com/.

2. Navigate to App registrations in the left sidebar.

3. Click New registration.

4. Fill in the Register an application form:

   Field	Value
   Name	Your App Name
   Supported account types	Accounts in this organizational directory only (Single tenant)
   Redirect URI (Platform)	Single-page application
   Redirect URI (URL)	Your production URL, e.g. https://your-app.pages.dev/

5. Click Register.

You will be redirected to the application's Overview page.

---

2. Configure Redirect URIs

Your app needs a redirect URI for every environment it runs in (production, staging, local development).

1. In the left navigation, go to Authentication.

2. Under the Redirect URI configuration tab, click Add URI.

3. Add all required URIs as Single-page application type:

   Environment	URI
   Local development	http://localhost:9000
   Cloudflare preview	https://your-app.pages.dev/
   Production (custom domain)	https://your-domain.com/

4. Click Save.

Note: Redirect URIs must match exactly — including trailing slashes — or authentication will fail with an invalid_request error.

---

3. Retrieve Application Credentials

You will need two identifiers from your app registration to configure MSAL.

1. In the left navigation, go to Overview.

2. Copy the following values:

   Value	Where to find it
   Application (client) ID	Displayed prominently on the Overview page
   Directory (tenant) ID	Displayed prominently on the Overview page

These will be used as environment variables in your application.

---

4. Configure Environment Variables

Local Development

Add the credentials to your local .env file (do not commit this file to version control):

# Microsoft Entra ID (Azure AD) app registration
MSAL_CLIENT_ID=your-application-client-id
MSAL_TENANT_ID=your-directory-tenant-id

Cloudflare Pages (Production)

Store the credentials as encrypted secrets in Cloudflare Pages:

1. Go to Workers & Pages → your project → Settings tab.

2. Scroll to Variables and Secrets.

3. Add the following secrets:

   Type	Variable Name	Value
   Secret	MSAL_CLIENT_ID	Your Application (client) ID
   Secret	MSAL_TENANT_ID	Your Directory (tenant) ID

4. Click Save.

Important: Secrets are applied on the next deployment. Trigger a re-deploy if you add them to an already-deployed project.

---

5. MSAL Integration in Code

Install the MSAL browser library:

npm install @azure/msal-browser

Initialize MSAL using your environment variables:

import { PublicClientApplication } from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: process.env.MSAL_CLIENT_ID,
    authority: `https://login.microsoftonline.com/${process.env.MSAL_TENANT_ID}`,
    redirectUri: window.location.origin,
  },
  cache: {
    cacheLocation: "sessionStorage",
    storeAuthStateInCookie: false,
  },
};

const msalInstance = new PublicClientApplication(msalConfig);

Trigger login with a popup or redirect flow:

// Popup login
const loginRequest = { scopes: ["User.Read"] };

msalInstance.loginPopup(loginRequest)
  .then(response => {
    console.log("Logged in:", response.account);
  })
  .catch(error => console.error(error));

// Or redirect login
msalInstance.loginRedirect(loginRequest);

---

6. Token Acquisition

After login, acquire tokens silently for API calls:

const tokenRequest = {
  scopes: ["User.Read"],
  account: msalInstance.getAllAccounts()[0],
};

msalInstance.acquireTokenSilent(tokenRequest)
  .then(response => {
    const accessToken = response.accessToken;
    // Use token in API request headers
  })
  .catch(error => {
    // Fall back to interactive login if silent acquisition fails
    msalInstance.acquireTokenPopup(tokenRequest);
  });

---

Troubleshooting

Problem	Likely Cause	Fix
AADSTS50011: redirect URI mismatch	URI not registered in Entra	Add the exact URI to App Registration → Authentication
AADSTS700016: application not found	Wrong clientId	Verify the client ID in Entra Overview
Silent token acquisition fails	Session expired or no cached account	Fall back to acquireTokenPopup or loginRedirect
Variables not available at runtime	Not re-deployed after adding secrets	Trigger a fresh deployment

---

Security Considerations

• Never hardcode MSAL_CLIENT_ID or MSAL_TENANT_ID in source code committed to public repositories.
• Use sessionStorage over localStorage for token caching in security-sensitive contexts.
• Restrict the App Registration to single tenant unless multi-tenant access is explicitly required.
• Regularly review App Registration permissions and remove unused scopes.