Authentication Failures¶

1. Summary¶

This playbook applies when Azure App Service Authentication (Easy Auth), Microsoft Entra ID integration, login redirects, token injection, or identity-based access flows stop working. Use it when users cannot sign in, APIs return unauthorized responses unexpectedly, or App Service-managed identity context is missing or inconsistent.

Symptoms¶

• Users are redirected in loops during sign-in.
• The app returns 401, 403, or provider callback errors after authentication.
• X-MS-* identity headers are missing when the app expects Easy Auth.
• Token store or identity provider changes broke login, logout, or callback behavior.

Common error messages¶

• 401 Unauthorized or 403 Forbidden.
• AADSTS50011 redirect URI mismatch.
• The reply URL specified in the request does not match the reply URLs configured.
• App Service Authentication is not configured correctly.
• IDX10214 audience validation failed or issuer/tenant mismatch errors.

flowchart TD
    A[Authentication failure reported] --> B{Is the user reaching the identity provider?}
    B -->|No| H1[H1: App Service auth configuration issue]
    B -->|Yes| C{Does callback return successfully?}
    C -->|No| H2[H2: Redirect URI, issuer, or tenant mismatch]
    C -->|Yes| D{Are identity headers or tokens present?}
    D -->|No| H3[H3: Easy Auth injection or route configuration issue]
    D -->|Yes| E{Is authorization failing after sign-in?}
    E -->|Yes| H4[H4: Audience, role, claim, or app authorization mismatch]
    E -->|No| F[Review session cookie, logout, and browser state]

2. Common Misreadings¶

3. Competing Hypotheses¶

4. What to Check First¶

1. Inspect App Service auth configuration

   az webapp auth show \
       --resource-group $RG \
       --name $APP_NAME \
       --output json
   

   Command	Purpose
   az webapp auth show --resource-group $RG --name $APP_NAME --output json	Shows the App Service authentication (Easy Auth) configuration for the app.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --output json	Formats the command output as JSON for full-fidelity inspection.

2. Inspect Microsoft provider settings

   az webapp auth microsoft show \
       --resource-group $RG \
       --name $APP_NAME \
       --output json
   

   Command	Purpose
   az webapp auth microsoft show --resource-group $RG --name $APP_NAME --output json	Shows the Microsoft identity provider configuration used by App Service authentication.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --output json	Formats the command output as JSON for full-fidelity inspection.

3. Confirm app state and hostnames used in callback URLs

   az webapp show \
       --resource-group $RG \
       --name $APP_NAME \
       --query "{defaultHostName:defaultHostName,hostNames:hostNames,httpsOnly:httpsOnly}" \
       --output json
   

   Command	Purpose
   az webapp show --resource-group $RG --name $APP_NAME --query "{defaultHostName:defaultHostName,hostNames:hostNames,httpsOnly:httpsOnly}" --output json	Shows the hostname and HTTPS settings that must align with the callback URLs used for authentication.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "{defaultHostName:defaultHostName,hostNames:hostNames,httpsOnly:httpsOnly}"	Projects only these named top-level properties into a smaller object before formatting the output.
   --output json	Formats the command output as JSON for full-fidelity inspection.

4. Review related app settings

   az webapp config appsettings list \
       --resource-group $RG \
       --name $APP_NAME \
       --query "[?contains(name, 'WEBSITE_AUTH') || contains(name, 'MICROSOFT_PROVIDER')].{name:name,value:value}" \
       --output table
   

   Command	Purpose
   az webapp config appsettings list --resource-group $RG --name $APP_NAME --query "[?contains(name, 'WEBSITE_AUTH') \|\| contains(name, 'MICROSOFT_PROVIDER')].{name:name,value:value}" --output table	Lists app settings so you can verify the effective configuration keys involved in this scenario.
   --resource-group $RG	Selects the resource group that contains the target web app or related resource.
   --name $APP_NAME	Specifies the target web app name for this command.
   --query "[?contains(name, 'WEBSITE_AUTH') \|\| contains(name, 'MICROSOFT_PROVIDER')].{name:name,value:value}"	Filters the returned list with JMESPath, then projects only the named fields into a smaller object per item.
   --output table	Formats the command output as a readable table for quick triage.

Diagnose and solve problems is this playbook's Portal entry point for authentication failures. The Configuration and Management card links directly to Investigate EasyAuth errors, which is the detector to open before running the KQL queries below; neighboring links such as IP Address Configuration and All Scaling Operations provide context when an auth failure correlates with a network or scale change.

5. Evidence to Collect¶

Capture the full login journey: initial request, redirect to provider, callback, final app response, and any header/claim evidence at the app boundary.

5.1 KQL Queries¶

Query 1: HTTP status and auth path behavior¶

AppServiceHTTPLogs
| where TimeGenerated > ago(24h)
| where CsUriStem has_any ("/.auth", "/signin", "/login", "/api") or ScStatus in (401, 403)
| summarize Requests=count(), P95=percentile(TimeTaken,95) by CsUriStem, ScStatus
| order by Requests desc

Query 2: Console or app-side auth errors¶

AppServiceConsoleLogs
| where TimeGenerated > ago(24h)
| where ResultDescription has_any ("AADSTS", "IDX", "Unauthorized", "Forbidden", "token", "claims", "issuer", "audience")
| project TimeGenerated, Level, ResultDescription
| order by TimeGenerated desc

Query 3: Application Insights failed requests by result code (if enabled)¶

requests
| where timestamp > ago(24h)
| where resultCode in ("401", "403", "500")
| summarize Requests=count(), P95=percentile(duration,95) by name, resultCode, success
| order by Requests desc

5.2 CLI Investigation¶

# Show App Service auth configuration
az webapp auth show \
    --resource-group $RG \
    --name $APP_NAME \
    --output json

Sample output:

{
  "enabled": true,
  "runtimeVersion": "~1",
  "unauthenticatedClientAction": "RedirectToLoginPage"
}

Interpretation:

• enabled must be true for Easy Auth scenarios.
• unauthenticatedClientAction must match the app type: redirect for browsers, 401 patterns for APIs.

# Show Microsoft identity provider configuration
az webapp auth microsoft show \
    --resource-group $RG \
    --name $APP_NAME \
    --output json

Sample output:

{
  "clientId": "<app-registration-client-id>",
  "enabled": true,
  "loginParameters": [],
  "registration": {
    "openIdIssuer": "https://login.microsoftonline.com/<tenant-id>/v2.0"
  }
}

Interpretation:

• Client ID, issuer, and callback host assumptions must match the Entra app registration.
• Tenant mismatch here explains many immediate login failures.

6. Validation and Disproof by Hypothesis¶

H1: App Service Authentication misconfiguration¶

Proves if auth settings are disabled, inconsistent, or not aligned with the intended unauthenticated behavior.

Disproves if Easy Auth is enabled correctly and provider configuration matches design.

Validation steps:

1. Confirm auth is enabled and the desired provider is active.
2. Check whether browser apps use redirect mode and APIs use the expected auth response pattern.
3. Remove overlapping app-side auth middleware only if it is clearly duplicating Easy Auth behavior.

H2: Redirect URI, issuer, or tenant mismatch¶

Proves if the provider returns explicit reply URL or issuer errors.

Disproves if callback completes cleanly and headers appear in the app.

Validation steps:

1. Compare current hostnames with Entra app registration redirect URIs.
2. Ensure HTTPS-only and canonical hostname choices align with provider config.
3. Re-test after one coordinated update rather than many partial changes.

H3: Missing Easy Auth headers or tokens¶

Proves if sign-in succeeds but app code never receives X-MS-* context where expected.

Disproves if the app consistently sees injected identity headers after callback.

Validation steps:

1. Validate the request path is truly traversing App Service Authentication.
2. Confirm the app is not bypassing the front end with unsupported direct assumptions.
3. Check token store or forwarded header expectations only after provider sign-in is confirmed healthy.

H4: Authorization mismatch after successful authentication¶

Proves if the user signs in but only protected routes or specific roles fail.

Disproves if all login attempts fail before callback or header injection.

Validation steps:

1. Compare required roles, audiences, and claims to the actual principal.
2. Inspect app-side token validation errors.
3. Test with a user known to have the intended group or app-role assignment.

7. Likely Root Cause Patterns¶

8. Immediate Mitigations¶

1. If production login is broken, revert the most recent auth configuration or provider registration change.
2. For redirect URI errors, fix the callback URLs before changing token validation logic.
3. If only specific protected APIs fail, temporarily relax app-side authorization only when business risk permits and only long enough to restore service.
4. Remove duplicate redirect or auth middleware that competes with Easy Auth.
5. Re-test with one known-good user and capture the full callback path before widening changes.

9. Prevention¶

Prevention checklist¶

• [ ] Keep App Service auth settings and Entra app registration changes under change control.
• [ ] Document canonical hostnames and callback URLs for every environment.
• [ ] Test both browser sign-in and API authorization paths after changes.
• [ ] Monitor spikes in 401, 403, and callback failures.
• [ ] Avoid stacking multiple authentication layers unless the ownership boundary is explicit.

See Also¶

• Playbooks
• Authentication Architecture
• Security Operations
• Easy Auth

Sources¶

• Authentication and authorization in Azure App Service (Microsoft Learn)
• Tutorial: Authenticate users end-to-end in Azure App Service (Microsoft Learn)
• Configure Microsoft identity provider authentication for App Service (Microsoft Learn)