Skip to main content

Deployed-app authentication

Require visitors to sign in with GitHub or Microsoft Entra ID before using your App Service Builder application.

At a glance​

  • Choose optional sign-in or require it for every visitor.
  • Choose GitHub or Microsoft Entra sign-in.

Enable in Portal​

  1. Open your app's Authentication page and set Sign-in to Optional or Required.
  2. Turn on GitHub or Microsoft Entra ID.
  3. To restrict access, turn on Limit to specific people for GitHub or Limit to specific identities for Entra ID, then add the allowed accounts. See access rules for each provider's options.
  4. If both providers are enabled, select Make default on the provider unauthenticated visitors are directed to. Visitors can still sign in with the other by visiting /.auth/login/<provider>.
  5. Save, then select Test sign-in to try it.

Builder CLI has no authentication configuration command. The ARM authentication reference describes provider fields, access rules, and update semantics.

Managed vs Your Own Applications​

Managed applications need no setup outside Builder. Your own application gives you more flexibility but requires more setup.

Managed applications​

Builder directs users to sign in to an application Builder owns. Because users sign in to a Builder application rather than yours, Builder shows a consent screen with your app's URL, asking users to consent to Builder sending their identity to your app. Once accepted, users are redirected back to your app. The consent screen is shown only once per user.

Your own applications​

You can create your own application with the identity provider and configure Builder to use it. Users sign in to your application and are redirected directly back to your Builder app.

Use your own GitHub OAuth application​

  1. On the app's Authentication page, enable GitHub and turn on Use your own application.
  2. Copy Authorization callback URL and register it in your GitHub OAuth application.
  3. Enter the OAuth application's Client ID and Client secret from GitHub.
  4. Configure the provider's access rules and Save.

Use your own Entra application​

You need an Entra app registration and a user-assigned managed identity assigned to the app, both in the same organizational tenant.

  1. On the app's Authentication page, enable Microsoft Entra ID and turn on Use your own application.
  2. Enter the registration's Application (client) ID, its home tenant ID, the Supported accounts setting, and the User-assigned managed identity.
  3. In the registration, add the displayed Redirect URI as a Web redirect, and add a federated credential (scenario: Managed identity).
  4. Configure the provider's access rules and Save.

Control access​

An empty access-rule list allows every account accepted by that provider application. Use explicit rules if your app is intended for a smaller audience.

ProviderWays to restrict access
GitHubEmail addresses or suffixes, usernames or suffixes, and numeric user IDs
Microsoft Entra IDTenant IDs, object IDs, and email addresses or suffixes

GitHub rules are alternatives: matching any one rule grants access. For Entra ID, tenant rules restrict the directory, and email or object-ID rules narrow the users within it. A tenant-only rule permits every authenticated identity in that tenant.

Without a tenant ID rule, Builder accepts a work-account email only when the sign-in token carries the verified-email claim xms_edov. The Builder-managed application provides this claim. If you use your own Entra application, configure xms_edov as an optional claim on the registration, or add a tenant ID rule alongside your email rules.

Tenant administrators can set users' email addresses; prefer object IDs when you need to identify specific users without relying on email. See the ARM reference for exact fields and limits.

Use these paths on your app's hostname:

EndpointPurpose
GET /.auth/login/githubStart GitHub sign-in
GET /.auth/login/aadStart Microsoft Entra sign-in
GET /.auth/meRead the signed-in identity, or [] when there is none
GET /.auth/logoutSign out and return to the app root
<a href="/.auth/login/aad?post_login_redirect_uri=/dashboard">Sign in</a>
<a href="/.auth/login/github?post_login_redirect_uri=/dashboard">Sign in with GitHub</a>
<a href="/.auth/logout?post_logout_redirect_uri=/">Sign out</a>

Redirect targets must be local application paths, not external URLs. /.auth/me does not return provider access or ID tokens.

Read the visitor identity​

App Service Builder supplies these headers after verifying a visitor:

Request headerMeaning
X-MS-CLIENT-PRINCIPAL-IDGitHub user ID or Entra object ID
X-MS-CLIENT-PRINCIPAL-NAMEIdentity name or login details, when available
X-MS-CLIENT-PRINCIPAL-IDPgithub or aad
X-MS-CLIENT-PRINCIPALBase64-encoded JSON claims describing the identity

Builder removes caller-supplied copies before adding verified identity headers, so callers can't spoof them. These headers are only present when your app runs on Builder; they aren't available on localhost or when the app is hosted elsewhere.

API tokens and application permissions​

For a customer Entra API, you may configure explicit allowedAudiences and use v2 access tokens, not browser ID tokens or ARM tokens.

Builder verifies the token and configured tenant/identity rules. It does not enforce your application's scopes or roles; implement those permission checks in your app.

When both Builder and your app require a bearer credential, send the Builder credential in X-Embr-Authorization and the app credential in Authorization. Both use the Bearer scheme. Builder forwards Authorization to your app unchanged. If you send only Authorization, Builder uses it to authenticate and removes it before forwarding, so your app doesn't receive it. Your app should validate its token's signature, issuer, audience, and lifetime before checking scopes or roles.

Last updated on