Microsoft Identity Platform: OAuth 2.0, MSAL, and App Registration Guide

Why This Is Happening

Here's the scenario I see constantly: a developer spends an afternoon wiring up sign-in for their new app, hits "Run," and gets back something like AADSTS50011: The redirect URI specified in the request does not match or a blank screen with no error at all. I know how infuriating that is , especially when the official error message gives you almost nothing useful to go on.

The Microsoft identity platform is a cloud identity service that lets you build applications your users can sign in to using their Microsoft accounts , work or school accounts provisioned through Microsoft Entra ID, personal Microsoft accounts (Skype, Xbox, Outlook.com), or even social and local accounts via Azure AD B2C or Microsoft Entra External ID. That sounds simple enough. In practice, getting all the pieces to talk to each other correctly involves a handful of systems that each have their own quirks.

The platform itself is built on OAuth 2.0 and OpenID Connect (OIDC) standards, which is genuinely good news, those are well-understood protocols. But the implementation details, specifically around app registration in the Microsoft Entra admin center, redirect URI configuration, token scope declarations, and the Microsoft Authentication Library (MSAL) setup in your code, are where developers lose hours.

The most common root causes I've diagnosed break down like this:

• Redirect URI mismatch, the single biggest cause of AADSTS50011. The URI in your code doesn't exactly match what's registered in Entra, right down to the trailing slash.
• Wrong account type selected during registration, choosing "single tenant" when you need multi-tenant app sign-in, or vice versa, causes silent failures that are very hard to trace.
• Missing or wrong API permissions, your app requests a scope like User.Read but the permission was never granted admin consent in the tenant.
• Incorrect MSAL configuration, wrong client ID, wrong authority URL, or a mismatched tenant ID all produce authentication errors that look identical on the surface.
• Token cache issues, stale tokens in MSAL's token cache can cause silent authentication failures that look like the user is being repeatedly prompted to sign in.
• Using deprecated ADAL instead of MSAL, if you're maintaining an older app, ADAL (Azure AD Authentication Library) is retired; calls to ADAL endpoints silently fail in some tenants.

The reason Microsoft's error messages feel so opaque is that they're designed with tenant security in mind, they deliberately avoid revealing too much about the tenant configuration to unauthenticated callers. That's the right call from a security standpoint, but it makes debugging painful for developers.

Whether you're building a single-page app (SPA), a traditional server-side web app, a desktop or mobile app, a background daemon, or a protected web API, the Microsoft identity platform setup process follows the same core flow. This guide walks through every part of that flow with the exact settings, error codes, and MSAL configurations that actually fix the problem. Browse all Microsoft fix guides →

The Quick Fix, Try This First

If you're hitting an authentication error right now and need a fast answer, the single fix that resolves the majority of Microsoft identity platform issues is verifying your redirect URI registration. This is so often the culprit that I always check it first before anything else.

Here's what you do:

1. Open the Microsoft Entra admin center (formerly the Azure portal Azure AD blade).
2. Go to Applications > App registrations and find your app.
3. Click your app, then click Authentication in the left sidebar.
4. Under Platform configurations, find the platform type your app uses (Single-page application, Web, Mobile and desktop applications).
5. Check the Redirect URIs listed there. Copy one exactly, character for character.
6. Compare it to the redirectUri value in your MSAL configuration object in code.

They must be byte-for-byte identical. https://localhost:3000 and https://localhost:3000/ are different URIs. http:// and https:// are different. Uppercase letters matter. If there's any difference at all, fix either the portal entry or your code to make them match, redeploy, and test again.

If your redirect URI is correct and you're still seeing errors, the second fastest check is your client ID. In the Entra admin center, go to App registrations > your app > Overview. The "Application (client) ID" shown there is the GUID you must pass as clientId in MSAL. I've seen teams accidentally use the "Object ID" instead, they look similar but they are completely different values and the wrong one will always produce an authentication failure.

For MSAL.js (JavaScript/TypeScript), your config should look like this:

const msalConfig = {
  auth: {
    clientId: "your-application-client-id-guid",
    authority: "https://login.microsoftonline.com/your-tenant-id",
    redirectUri: "https://your-exact-registered-uri.com/callback"
  }
};

If neither of those fixes it, keep reading, there are several other configuration layers that can be the source of the problem.

Advanced Troubleshooting

If the steps above didn't resolve your issue, the problem is likely deeper in the configuration. Here's where I dig when the basics are ruled out.

Decoding JWT Tokens to Diagnose Claim Errors

The access token and ID token returned by the Microsoft identity platform are JSON Web Tokens (JWTs). When something is wrong with permissions, tenant, or audience, the token itself usually contains the evidence. Go to jwt.ms (Microsoft's own tool) and paste your token. You'll see every claim decoded in a readable format. Look at:

• tid, the tenant ID. Should match your registered app's tenant.
• aud, the audience. For Microsoft Graph tokens, this should be https://graph.microsoft.com. For your own API, it should be your API's client ID.
• scp, scopes granted. If the scope you requested isn't listed here, the permission wasn't granted or you forgot to request it.
• roles, application roles, if you use role-based access control.

Conditional Access Policy Blocks

In enterprise environments, tenant administrators often configure Conditional Access policies that require multi-factor authentication (MFA), compliant devices, or specific network locations. If a user's sign-in is blocked by a policy your app doesn't handle, MSAL returns an InteractionRequiredAuthError with a claims property attached. You need to pass those claims back in the next interactive authentication request:

try {
  await msalInstance.acquireTokenSilent(tokenRequest);
} catch (error) {
  if (error instanceof InteractionRequiredAuthError) {
    await msalInstance.acquireTokenRedirect({
      ...tokenRequest,
      claims: error.claims // Pass Conditional Access claims back
    });
  }
}

Multi-Tenant App Consent Issues

For multi-tenant apps, every tenant that uses your app needs to consent to it, either through user consent or admin consent. If a user from a new tenant hits AADSTS65001, their tenant admin hasn't consented yet. You can build an admin consent flow using the endpoint:

https://login.microsoftonline.com/{tenant}/adminconsent
  ?client_id={your-client-id}
  &redirect_uri={your-redirect-uri}

Direct tenant admins to this URL to pre-authorize your app in their organization.

Event Viewer for Azure AD Join & Hybrid Scenarios

On Windows devices that are Azure AD Joined or Hybrid Joined, Windows handles some authentication flows at the OS level via the Web Account Manager (WAM). If silent SSO is failing on Windows, open Event Viewer > Applications and Services Logs > Microsoft > Windows > AAD. Event IDs in the 1000–1100 range indicate WAM authentication failures with far more detail than MSAL's error messages alone.

App Roles and Role-Based Access Control

If your app uses roles to restrict access (e.g., only users in an "Admin" role can view certain pages), those roles must be defined in the app manifest. Go to App registrations > your app > App roles and create the roles there. Then assign users or groups to those roles in Enterprise applications > your app > Users and groups. The assigned roles appear in the JWT's roles claim.

Prevention & Best Practices

Once you've got the Microsoft identity platform working, keeping it working requires a bit of ongoing hygiene. These are the practices I recommend to every team building on this platform.

Use MSAL, always. The older Azure AD Authentication Library (ADAL) is retired. If you're maintaining a legacy application that still uses ADAL, migration to MSAL isn't optional, it's necessary. MSAL handles the latest security requirements, supports modern authentication flows including Authorization Code + PKCE, and receives active security patches. ADAL doesn't.

Never store client secrets in code. If your app is a confidential client (a server-side web app or daemon), you'll have a client secret or certificate. Never commit these to source control. Use environment variables in development and Azure Key Vault or your deployment platform's secrets management in production. A leaked client secret is a full app impersonation risk.

Request only the scopes you actually need. This isn't just a security best practice, it directly affects your app's user experience. The consent screen shows users every permission your app requests. Requesting Mail.ReadWrite when you only need User.Read will cause users to distrust your app or refuse consent entirely. Scope down to the minimum required.

Handle token expiry gracefully. Access tokens from the Microsoft identity platform typically expire in one hour. MSAL's acquireTokenSilent handles refresh automatically as long as the refresh token is valid (refresh tokens last up to 90 days for active sessions). But your code must handle the InteractionRequiredAuthError case and redirect to an interactive login when silent renewal fails. Don't assume a token is valid just because you acquired it earlier in the session.

Use separate app registrations for dev, staging, and production. Sharing one registration across environments is tempting but creates risks, a developer adding a test redirect URI to the production registration is a real thing that happens. Separate registrations give you clean separation of credentials, redirect URIs, and permissions per environment.

Frequently Asked Questions