App Service Built-in Authentication (Easy Auth)¶

App Service provides a built-in authentication and authorization service, often called Easy Auth. This platform-level feature handles user logins and provides identity information to your Node.js application through HTTP headers.

sequenceDiagram
    participant U as User
    participant FE as App Service Easy Auth
    participant IDP as Entra ID
    participant APP as Node.js App
    U->>FE: Request protected endpoint
    FE->>IDP: Redirect + token validation
    IDP-->>FE: Authenticated token
    FE->>APP: Forward request with X-MS-* headers
    APP-->>U: Response using claims

Overview¶

Easy Auth eliminates the need to manage security tokens or integrate complex authentication SDKs into your code. The platform validates incoming tokens and populates standard headers before the request reaches your application.

• No SDK required: Works with any language or framework.
• Token validation: Handled by the App Service platform.
• Multiple providers: Supports Microsoft Entra ID, Google, Facebook, GitHub, and more.

When to Use¶

Enable via Azure CLI¶

Use the following command to enable Microsoft Entra ID authentication for your web app:

# Enable Microsoft Entra ID auth
az webapp auth microsoft update \
  --name $APP_NAME \
  --resource-group $RG \
  --client-id "<your-app-id>" \
  --client-secret "<your-secret>" \
  --issuer "https://login.microsoftonline.com/<tenant-id>/v2.0" \
  --output json

Enable via Portal¶

1. Navigate to your App Service in the Azure Portal.
2. Select Authentication from the left menu.
3. Click Add identity provider.
4. Choose Microsoft (or your preferred provider).
5. Configure the app registration settings and save.

Access User Information in Node.js¶

Your application can retrieve user identity information from specific HTTP headers injected by the platform.

app.get('/api/profile', (req, res) => {
  const userId = req.headers['x-ms-client-principal-id'];
  const userName = req.headers['x-ms-client-principal-name'];

  res.json({ userId, userName });
});

// For full claims
app.get('/api/claims', (req, res) => {
  const principal = req.headers['x-ms-client-principal'];
  if (!principal) {
    return res.status(401).json({ error: 'Not authenticated' });
  }

  const claims = JSON.parse(Buffer.from(principal, 'base64').toString());
  res.json(claims);
});

Available Headers¶

Local Development¶

Easy Auth headers are only available when running on App Service. To simulate this environment during local development, use a simple middleware to mock these headers.

// Middleware to mock auth headers locally
if (process.env.NODE_ENV === 'development') {
  app.use((req, res, next) => {
    req.headers['x-ms-client-principal-id'] = 'dev-user-123';
    req.headers['x-ms-client-principal-name'] = 'Developer';
    next();
  });
}

Verification¶

After deployment, verify the setup with these steps:

1. Test unauthenticated access: Attempt to access a protected route without logging in. Depending on your configuration, it should either redirect to a login page or return a 401 Unauthorized error.
2. Test authenticated access: Log in and verify that the application receives the identity headers. You can log these headers to the console or display them in a debug view.

Troubleshooting¶

• Redirect loop: This often happens if the reply URL in your app registration doesn't match the actual URL of your App Service.
• Token not received: Verify that the token store is enabled in the Authentication settings.
• Claims missing: Ensure you've configured the correct scopes and permissions in your identity provider settings.

Advanced Topics¶

Run It in the Portal¶

Portal view: Authentication blade (empty state - Easy Auth entry point)¶

The Authentication blade in its empty state is the Portal entry point this recipe uses to enable Easy Auth. The visible Add identity provider action and provider list — Microsoft, Apple, Facebook, GitHub, Google, Twitter, and OpenID Connect — match the prerequisite on this page that an identity provider be configured before the Express app can rely on forwarded X-MS-* headers. Use this blade as the setup and verification surface for the recipe before testing that authenticated requests reach the Node.js app with X-MS-CLIENT-PRINCIPAL present.

See Also¶

• Security Operations
• Managed Identity

Sources¶

• Configure Azure App Service to use Microsoft Entra ID login (Microsoft Learn)
• Working with user identities in Azure App Service authentication (Microsoft Learn)