Authentication and authorization in Azure App Service and Azure Functions

  • Article

Azure App Service provides built-in authentication (signing in users) and authorization (providing access to secure data) capabilities. These capabilities are sometimes called Easy Auth. You can use them to sign in users and access data by writing little or no code in your web app, RESTful API, mobile server, and functions.

Note

Starting June 1, 2024, newly created App Service apps can generate a unique default hostname that uses the naming convention <app-name>-<random-hash>.<region>.chinacloudsites.cn. Existing app names remain unchanged. For example:

myapp-ds27dh7271aah175.chinanorth3-01.chinacloudsites.cn

This article describes how App Service helps simplify authentication and authorization for your app.

Reasons to use built-in authentication

To implement authentication and authorization, you can use the bundled security features in your web framework of choice, or you can write your own tools. Implementing a secure solution for authentication and authorization can take significant effort. You need to follow industry best practices and standards. You also need to ensure that your solution stays up to date with the latest security, protocol, and browser updates.

The built-in capabilities of App Service and Azure Functions can save you time and effort by providing out-of-the-box authentication with federated identity providers, so you can focus on the rest of your application.

With App Service, you can integrate authentication capabilities into your web app or API without implementing them yourself. This feature is built directly into the platform and doesn't require any particular language, SDK, security expertise, or code. You can integrate it with multiple sign-in providers, such as Microsoft Entra, Facebook, Google, and X.

Your app might need to support more complex scenarios, such as Visual Studio integration or incremental consent. Several authentication solutions are available to support these scenarios. To learn more, see Authentication scenarios and recommendations.

Identity providers

The following identity providers are available by default:

Provider Sign-in endpoint How-to guidance
Microsoft Entra /.auth/login/aad App Service Microsoft Entra platform sign-in
Any OpenID Connect provider /.auth/login/<providerName> App Service OpenID Connect sign-in

When you configure this feature with one of these providers, its sign-in endpoint is available for user authentication and for validation of authentication tokens from the provider. You can provide your users with any number of these sign-in options.

Considerations for using built-in authentication

Enabling built-in authentication causes�all requests to your application to be automatically redirected to HTTPS, regardless of the App Service configuration setting to enforce HTTPS. You can disable this automatic redirection by using the requireHttps setting in the V2 configuration. However, we recommend that you keep using HTTPS and ensure that no security tokens are ever transmitted over nonsecure HTTP connections.

You can use App Service for authentication with or without restricting access to your site content and APIs. Set access restrictions in the Settings > Authentication > Authentication settings section of your web app:

  • To restrict app access to only authenticated users, set Action to take when request is not authenticated to�sign in with one of the configured identity providers.
  • To authenticate but not restrict access, set Action to take when request is not authenticated to Allow anonymous requests (no action).

Important

You should give each app registration its own permission and consent. Avoid permission sharing between environments by using separate app registrations for separate deployment slots. When you're testing new code, this practice can help prevent problems from affecting the production app.

How it works

Feature architecture

The authentication and authorization middleware component is a feature of the platform that runs on the same virtual machine as your application. When you enable it, every incoming HTTP request passes through that component before your application handles it.

Architecture diagram that shows a process in the site sandbox interacting with identity providers before allowing traffic to the deployed site.

The platform middleware handles several things for your app:

  • Authenticates users and clients with the specified identity providers
  • Validates, stores, and refreshes OAuth tokens that the configured identity providers issued
  • Manages the authenticated session
  • Injects identity information into HTTP request headers

The module runs separately from your application code. You can configure it by using Azure Resource Manager settings or by using a configuration file. No SDKs, specific programming languages, or changes to your application code are required.

Authentication flow

The authentication flow is the same for all providers. It differs depending on whether you want to sign in with the provider's SDK:

  • Without provider SDK: The application delegates federated sign-in to App Service. This delegation is typically the case with browser apps, which can present the provider's sign-in page to the user. The server code manages the sign-in process, so it's also called server-directed flow or server flow.

    This case applies to browser apps and mobile apps that use an embedded browser for authentication.

  • With provider SDK: The application signs in users to the provider manually. Then it submits the authentication token to App Service for validation. This process is typically the case with browserless apps, which can't present the provider's sign-in page to the user. The application code manages the sign-in process, so it's also called client-directed flow or client flow.

    This case applies to REST APIs, Azure Functions, and JavaScript browser clients, in addition to browser apps that need more flexibility in the sign-in process. It also applies to native mobile apps that sign in users by using the provider's SDK.

The following table shows the steps of the authentication flow.

Step Without provider SDK With provider SDK
1. Sign in the user Provider redirects the client to /.auth/login/<provider>. Client code signs in the user directly with the provider's SDK and receives an authentication token. For more information, see the provider's documentation.
2. Conduct post-authentication Provider redirects the client to /.auth/login/<provider>/callback. Client code posts the token from the provider to /.auth/login/<provider> for validation.
3. Establish an authenticated session App Service adds an authenticated cookie to the response. App Service returns its own authentication token to the client code.
4. Serve authenticated content Client includes an authentication cookie in subsequent requests (automatically handled by the browser). Client code presents the authentication token in the X-ZUMO-AUTH header.

For client browsers, App Service can automatically direct all unauthenticated users to /.auth/login/<provider>. You can also present users with one or more /.auth/login/<provider> links to sign in to your app by using their provider of choice.

Authorization behavior

In the Azure portal, you can configure App Service with various behaviors when an incoming request isn't authenticated. The following sections describe the options.

Important

By default, this feature provides only authentication, not authorization. Your application might still need to make authorization decisions, in addition to any checks that you configure here.

Restricted access

  • Allow unauthenticated requests: This option defers authorization of unauthenticated traffic to your application code. For authenticated requests, App Service also passes along authentication information in the HTTP headers.

    This option provides more flexibility in handling anonymous requests. For example, it lets you present multiple sign-in providers to your users. However, you must write code.

  • Require authentication: This option rejects any unauthenticated traffic to your application. Specific action to take is specified in the Unauthenticated requests section later in this article.

    With this option, you don't need to write any authentication code in your app. You can handle finer authorization, such as role-specific authorization, by inspecting the user's claims.

    Caution

    Restricting access in this way applies to all calls to your app. This behavior might not be desirable for apps that have a publicly available home page, as in many single-page applications.

When you're using the Microsoft identity provider for users in your organization, the default behavior is that any user in your Microsoft Entra tenant can request a token for your application. You can configure the application in Microsoft Entra if you want to restrict access to your app to a defined set of users. App Service also offers some basic built-in authorization checks that can help with some validations. To learn more about authorization in Microsoft Entra, see Microsoft Entra authorization basics.

Logging and tracing

If you enable application logging, authentication and authorization traces appear directly in your log files. If you see an authentication error that you didn't expect, you can conveniently find all the details by looking in your existing application logs.

If you enable failed request tracing, you can see exactly what role the authentication and authorization module might play in a failed request. In the trace logs, look for references to a module named EasyAuthModule_32/64.

Mitigation of cross-site request forgery

App Service authentication mitigates cross-site request forgery by inspecting client requests for the following conditions:

  • It's a POST request that authenticated through a session cookie.
  • The request came from a known browser, as determined by the HTTP User-Agent header.
  • The HTTP Origin or HTTP Referer header is missing or isn't in the configured list of approved external domains for redirection.
  • The HTTP Origin header is missing or isn't in the configured list of cross-origin resource sharing (CORS) origins.

When a request fulfills all these conditions, App Service authentication automatically rejects it. You can work around this mitigation logic by adding your external domain to the redirect list in Settings > Authentication > Edit authentication settings > Allowed external redirect URLs.

Considerations for using Azure Front Door

For samples, see: