--- title: Overview of ASP.NET Core Authentication author: mjrousos description: Learn about authentication in ASP.NET Core. ms.author: riande ms.custom: mvc ms.date: 10/18/2022 uid: security/authentication/index --- # Overview of ASP.NET Core authentication :::moniker range=">= aspnetcore-7.0" By [Mike Rousos](https://github.com/mjrousos) Authentication is the process of determining a user's identity. [Authorization](xref:security/authorization/introduction) is the process of determining whether a user has access to a resource. In ASP.NET Core, authentication is handled by the authentication service, , which is used by authentication [middleware](xref:fundamentals/middleware/index). The authentication service uses registered authentication handlers to complete authentication-related actions. Examples of authentication-related actions include: * Authenticating a user. * Responding when an unauthenticated user tries to access a restricted resource. The registered authentication handlers and their configuration options are called "schemes". Authentication schemes are specified by registering authentication services in `Program.cs`: * By calling a scheme-specific extension method after a call to , such as or . These extension methods use to register schemes with appropriate settings. * Less commonly, by calling `AuthenticationBuilder.AddScheme` directly. For example, the following code registers authentication services and handlers for cookie and JWT bearer authentication schemes: ```csharp builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options => builder.Configuration.Bind("JwtSettings", options)) .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options => builder.Configuration.Bind("CookieSettings", options)); ``` The `AddAuthentication` parameter is the name of the scheme to use by default when a specific scheme isn't requested. If multiple schemes are used, authorization policies (or authorization attributes) can [specify the authentication scheme (or schemes)](xref:security/authorization/limitingidentitybyscheme) they depend on to authenticate the user. In the example above, the cookie authentication scheme could be used by specifying its name ( by default, though a different name could be provided when calling `AddCookie`). In some cases, the call to `AddAuthentication` is automatically made by other extension methods. For example, when using [ASP.NET Core Identity](xref:security/authentication/identity), `AddAuthentication` is called internally. The Authentication middleware is added in `Program.cs` by calling . Calling `UseAuthentication` registers the middleware that uses the previously registered authentication schemes. Call `UseAuthentication` before any middleware that depends on users being authenticated. ## Authentication concepts Authentication is responsible for providing the for authorization to make permission decisions against. There are multiple authentication scheme approaches to select which authentication handler is responsible for generating the correct set of claims: * [Authentication scheme](#authentication-scheme) * The default authentication scheme, discussed in the next two sections. * Directly set . When there is only a single authentication scheme registered, it becomes the default scheme. If multiple schemes are registered and the default scheme isn't specified, a scheme must be specified in the authorize attribute, otherwise, the following error is thrown: > InvalidOperationException: No authenticationScheme was specified, and there was no DefaultAuthenticateScheme found. The default schemes can be set using either AddAuthentication(string defaultScheme) or AddAuthentication(Action\ configureOptions). ### `DefaultScheme` When there is only a single authentication scheme registered, the single authentication scheme: * Is automatically used as the . * Eliminates the need to specify the `DefaultScheme` in or . To disable automatically using the single authentication scheme as the `DefaultScheme`, call `AppContext.SetSwitch("Microsoft.AspNetCore.Authentication.SuppressAutoDefaultScheme")`. ### Authentication scheme The [authentication scheme](xref:security/authorization/limitingidentitybyscheme) can select which authentication handler is responsible for generating the correct set of claims. For more information, see [Authorize with a specific scheme](xref:security/authorization/limitingidentitybyscheme). An authentication scheme is a name that corresponds to: * An authentication handler. * Options for configuring that specific instance of the handler. Schemes are useful as a mechanism for referring to the authentication, challenge, and forbid behaviors of the associated handler. For example, an authorization policy can use scheme names to specify which authentication scheme (or schemes) should be used to authenticate the user. When configuring authentication, it's common to specify the default authentication scheme. The default scheme is used unless a resource requests a specific scheme. It's also possible to: * Specify different default schemes to use for authenticate, challenge, and forbid actions. * Combine multiple schemes into one using [policy schemes](xref:security/authentication/policyschemes). ### Authentication handler An authentication handler: * Is a type that implements the behavior of a scheme. * Is derived from or . * Has the primary responsibility to authenticate users. Based on the authentication scheme's configuration and the incoming request context, authentication handlers: * Construct objects representing the user's identity if authentication is successful. * Return 'no result' or 'failure' if authentication is unsuccessful. * Have methods for challenge and forbid actions for when users attempt to access resources: * They're unauthorized to access (forbid). * When they're unauthenticated (challenge). ### `RemoteAuthenticationHandler` vs `AuthenticationHandler` is the class for authentication that requires a remote authentication step. When the remote authentication step is finished, the handler calls back to the `CallbackPath` set by the handler. The handler finishes the authentication step using the information passed to the callback path. [OAuth 2.0](https://oauth.net/2/) and [OIDC](https://openid.net/developers/how-connect-works/) both use this pattern. JWT and cookies don't since they can directly use the bearer header and cookie to authenticate. The remotely hosted provider in this case: * Is the authentication provider. * Examples include [Facebook](xref:security/authentication/facebook-logins), [Twitter](xref:security/authentication/twitter-logins), [Google](xref:security/authentication/google-logins), [Microsoft](xref:security/authentication/microsoft-logins), and any other OIDC provider that handles authenticating users using the handlers mechanism. ### Authenticate An authentication scheme's authenticate action is responsible for constructing the user's identity based on request context. It returns an indicating whether authentication was successful and, if so, the user's identity in an authentication ticket. See . Authenticate examples include: * A cookie authentication scheme constructing the user's identity from cookies. * A JWT bearer scheme deserializing and validating a JWT bearer token to construct the user's identity. ### Challenge An authentication challenge is invoked by Authorization when an unauthenticated user requests an endpoint that requires authentication. An authentication challenge is issued, for example, when an anonymous user requests a restricted resource or follows a login link. Authorization invokes a challenge using the specified authentication scheme(s), or the default if none is specified. See . Authentication challenge examples include: * A cookie authentication scheme redirecting the user to a login page. * A JWT bearer scheme returning a 401 result with a `www-authenticate: bearer` header. A challenge action should let the user know what authentication mechanism to use to access the requested resource. ### Forbid An authentication scheme's forbid action is called by Authorization when an authenticated user attempts to access a resource they're not permitted to access. See . Authentication forbid examples include: * A cookie authentication scheme redirecting the user to a page indicating access was forbidden. * A JWT bearer scheme returning a 403 result. * A custom authentication scheme redirecting to a page where the user can request access to the resource. A forbid action can let the user know: * They're authenticated. * They're not permitted to access the requested resource. See the following links for differences between challenge and forbid: * [Challenge and forbid with an operational resource handler](xref:security/authorization/resourcebased#challenge-and-forbid-with-an-operational-resource-handler). * [Differences between challenge and forbid](xref:security/authorization/secure-data#challenge). ## Authentication providers per tenant ASP.NET Core doesn't have a built-in solution for multi-tenant authentication. While it's possible for customers to write one using the built-in features, we recommend customers consider [Orchard Core](https://www.orchardcore.net/), [ABP Framework](https://abp.io/), or [Finbuckle.MultiTenant](https://www.finbuckle.com/multitenant) for multi-tenant authentication. Orchard Core is: * An open-source, modular, and multi-tenant app framework built with ASP.NET Core. * A content management system (CMS) built on top of that app framework. See the [Orchard Core](https://github.com/OrchardCMS/OrchardCore) source for an example of authentication providers per tenant. [ABP Framework](https://abp.io/) supports various architectural patterns including modularity, microservices, domain driven design, and multi-tenancy. See [ABP Framework source on GitHub](https://github.com/abpframework/abp). Finbuckle.MultiTenant: * Open source * Provides tenant resolution * Lightweight * Provides data isolation * Configure app behavior uniquely for each tenant ## Additional resources * * * * [Globally require authenticated users](xref:security/authorization/secure-data#rau) * [GitHub issue on using multiple authentication schemes](https://github.com/dotnet/aspnetcore/issues/26002) :::moniker-end :::moniker range="= aspnetcore-6.0" By [Mike Rousos](https://github.com/mjrousos) Authentication is the process of determining a user's identity. [Authorization](xref:security/authorization/introduction) is the process of determining whether a user has access to a resource. In ASP.NET Core, authentication is handled by the authentication service, , which is used by authentication [middleware](xref:fundamentals/middleware/index). The authentication service uses registered authentication handlers to complete authentication-related actions. Examples of authentication-related actions include: * Authenticating a user. * Responding when an unauthenticated user tries to access a restricted resource. The registered authentication handlers and their configuration options are called "schemes". Authentication schemes are specified by registering authentication services in `Program.cs`: * By calling a scheme-specific extension method after a call to , such as or . These extension methods use to register schemes with appropriate settings. * Less commonly, by calling `AuthenticationBuilder.AddScheme` directly. For example, the following code registers authentication services and handlers for cookie and JWT bearer authentication schemes: ```csharp builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options => builder.Configuration.Bind("JwtSettings", options)) .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options => builder.Configuration.Bind("CookieSettings", options)); ``` The `AddAuthentication` parameter is the name of the scheme to use by default when a specific scheme isn't requested. If multiple schemes are used, authorization policies (or authorization attributes) can [specify the authentication scheme (or schemes)](xref:security/authorization/limitingidentitybyscheme) they depend on to authenticate the user. In the example above, the cookie authentication scheme could be used by specifying its name ( by default, though a different name could be provided when calling `AddCookie`). In some cases, the call to `AddAuthentication` is automatically made by other extension methods. For example, when using [ASP.NET Core Identity](xref:security/authentication/identity), `AddAuthentication` is called internally. The Authentication middleware is added in `Program.cs` by calling . Calling `UseAuthentication` registers the middleware that uses the previously registered authentication schemes. Call `UseAuthentication` before any middleware that depends on users being authenticated. ## Authentication concepts Authentication is responsible for providing the for authorization to make permission decisions against. There are multiple authentication scheme approaches to select which authentication handler is responsible for generating the correct set of claims: * [Authentication scheme](#authentication-scheme) * The default authentication scheme, discussed in the next section. * Directly set . There's no automatic probing of schemes. If the default scheme isn't specified, the scheme must be specified in the authorize attribute, otherwise, the following error is thrown: > InvalidOperationException: No authenticationScheme was specified, and there was no DefaultAuthenticateScheme found. The default schemes can be set using either AddAuthentication(string defaultScheme) or AddAuthentication(Action\ configureOptions). ### Authentication scheme The [authentication scheme](xref:security/authorization/limitingidentitybyscheme) can select which authentication handler is responsible for generating the correct set of claims. For more information, see [Authorize with a specific scheme](xref:security/authorization/limitingidentitybyscheme). An authentication scheme is a name that corresponds to: * An authentication handler. * Options for configuring that specific instance of the handler. Schemes are useful as a mechanism for referring to the authentication, challenge, and forbid behaviors of the associated handler. For example, an authorization policy can use scheme names to specify which authentication scheme (or schemes) should be used to authenticate the user. When configuring authentication, it's common to specify the default authentication scheme. The default scheme is used unless a resource requests a specific scheme. It's also possible to: * Specify different default schemes to use for authenticate, challenge, and forbid actions. * Combine multiple schemes into one using [policy schemes](xref:security/authentication/policyschemes). ### Authentication handler An authentication handler: * Is a type that implements the behavior of a scheme. * Is derived from or . * Has the primary responsibility to authenticate users. Based on the authentication scheme's configuration and the incoming request context, authentication handlers: * Construct objects representing the user's identity if authentication is successful. * Return 'no result' or 'failure' if authentication is unsuccessful. * Have methods for challenge and forbid actions for when users attempt to access resources: * They're unauthorized to access (forbid). * When they're unauthenticated (challenge). ### `RemoteAuthenticationHandler` vs `AuthenticationHandler` is the class for authentication that requires a remote authentication step. When the remote authentication step is finished, the handler calls back to the `CallbackPath` set by the handler. The handler finishes the authentication step using the information passed to the callback path. [OAuth 2.0](https://oauth.net/2/) and [OIDC](https://openid.net/developers/how-connect-works/) both use this pattern. JWT and cookies don't since they can directly use the bearer header and cookie to authenticate. The remotely hosted provider in this case: * Is the authentication provider. * Examples include [Facebook](xref:security/authentication/facebook-logins), [Twitter](xref:security/authentication/twitter-logins), [Google](xref:security/authentication/google-logins), [Microsoft](xref:security/authentication/microsoft-logins), and any other OIDC provider that handles authenticating users using the handlers mechanism. ### Authenticate An authentication scheme's authenticate action is responsible for constructing the user's identity based on request context. It returns an indicating whether authentication was successful and, if so, the user's identity in an authentication ticket. See . Authenticate examples include: * A cookie authentication scheme constructing the user's identity from cookies. * A JWT bearer scheme deserializing and validating a JWT bearer token to construct the user's identity. ### Challenge An authentication challenge is invoked by Authorization when an unauthenticated user requests an endpoint that requires authentication. An authentication challenge is issued, for example, when an anonymous user requests a restricted resource or follows a login link. Authorization invokes a challenge using the specified authentication scheme(s), or the default if none is specified. See . Authentication challenge examples include: * A cookie authentication scheme redirecting the user to a login page. * A JWT bearer scheme returning a 401 result with a `www-authenticate: bearer` header. A challenge action should let the user know what authentication mechanism to use to access the requested resource. ### Forbid An authentication scheme's forbid action is called by Authorization when an authenticated user attempts to access a resource they're not permitted to access. See . Authentication forbid examples include: * A cookie authentication scheme redirecting the user to a page indicating access was forbidden. * A JWT bearer scheme returning a 403 result. * A custom authentication scheme redirecting to a page where the user can request access to the resource. A forbid action can let the user know: * They're authenticated. * They're not permitted to access the requested resource. See the following links for differences between challenge and forbid: * [Challenge and forbid with an operational resource handler](xref:security/authorization/resourcebased#challenge-and-forbid-with-an-operational-resource-handler). * [Differences between challenge and forbid](xref:security/authorization/secure-data#challenge). ## Authentication providers per tenant ASP.NET Core doesn't have a built-in solution for multi-tenant authentication. While it's possible for customers to write one using the built-in features, we recommend customers to consider [Orchard Core](https://www.orchardcore.net/) or [ABP Framework](https://abp.io/) for multi-tenant authentication. Orchard Core is: * An open-source, modular, and multi-tenant app framework built with ASP.NET Core. * A content management system (CMS) built on top of that app framework. See the [Orchard Core](https://github.com/OrchardCMS/OrchardCore) source for an example of authentication providers per tenant. [ABP Framework](https://abp.io/) supports various architectural patterns including modularity, microservices, domain driven design, and multi-tenancy. See [ABP Framework source on GitHub](https://github.com/abpframework/abp). ## Additional resources * * * * [Globally require authenticated users](xref:security/authorization/secure-data#rau) * [GitHub issue on using multiple authentication schemes](https://github.com/dotnet/aspnetcore/issues/26002) :::moniker-end :::moniker range="< aspnetcore-6.0" By [Mike Rousos](https://github.com/mjrousos) Authentication is the process of determining a user's identity. [Authorization](xref:security/authorization/introduction) is the process of determining whether a user has access to a resource. In ASP.NET Core, authentication is handled by the authentication service, , which is used by authentication [middleware](xref:fundamentals/middleware/index). The authentication service uses registered authentication handlers to complete authentication-related actions. Examples of authentication-related actions include: * Authenticating a user. * Responding when an unauthenticated user tries to access a restricted resource. The registered authentication handlers and their configuration options are called "schemes". Authentication schemes are specified by registering authentication services in `Startup.ConfigureServices`: * By calling a scheme-specific extension method after a call to (such as or , for example). These extension methods use to register schemes with appropriate settings. * Less commonly, by calling `AuthenticationBuilder.AddScheme` directly. For example, the following code registers authentication services and handlers for cookie and JWT bearer authentication schemes: ```csharp services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(JwtBearerDefaults.AuthenticationScheme, options => Configuration.Bind("JwtSettings", options)) .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options => Configuration.Bind("CookieSettings", options)); ``` The `AddAuthentication` parameter is the name of the scheme to use by default when a specific scheme isn't requested. If multiple schemes are used, authorization policies (or authorization attributes) can [specify the authentication scheme (or schemes)](xref:security/authorization/limitingidentitybyscheme) they depend on to authenticate the user. In the example above, the cookie authentication scheme could be used by specifying its name ( by default, though a different name could be provided when calling `AddCookie`). In some cases, the call to `AddAuthentication` is automatically made by other extension methods. For example, when using [ASP.NET Core Identity](xref:security/authentication/identity), `AddAuthentication` is called internally. The Authentication middleware is added in `Startup.Configure` by calling . Calling `UseAuthentication` registers the middleware that uses the previously registered authentication schemes. Call `UseAuthentication` before any middleware that depends on users being authenticated. When using endpoint routing, the call to `UseAuthentication` must go: * After , so that route information is available for authentication decisions. * Before , so that users are authenticated before accessing the endpoints. ## Authentication concepts Authentication is responsible for providing the for authorization to make permission decisions against. There are multiple authentication scheme approaches to select which authentication handler is responsible for generating the correct set of claims: * [Authentication scheme](#authentication-scheme) * The default authentication scheme, discussed in the next section. * Directly set . There's no automatic probing of schemes. If the default scheme isn't specified, the scheme must be specified in the authorize attribute, otherwise, the following error is thrown: > InvalidOperationException: No authenticationScheme was specified, and there was no DefaultAuthenticateScheme found. The default schemes can be set using either AddAuthentication(string defaultScheme) or AddAuthentication(Action\ configureOptions). ### Authentication scheme The [authentication scheme](xref:security/authorization/limitingidentitybyscheme) can select which authentication handler is responsible for generating the correct set of claims. For more information, see [Authorize with a specific scheme](xref:security/authorization/limitingidentitybyscheme). An authentication scheme is a name that corresponds to: * An authentication handler. * Options for configuring that specific instance of the handler. Schemes are useful as a mechanism for referring to the authentication, challenge, and forbid behaviors of the associated handler. For example, an authorization policy can use scheme names to specify which authentication scheme (or schemes) should be used to authenticate the user. When configuring authentication, it's common to specify the default authentication scheme. The default scheme is used unless a resource requests a specific scheme. It's also possible to: * Specify different default schemes to use for authenticate, challenge, and forbid actions. * Combine multiple schemes into one using [policy schemes](xref:security/authentication/policyschemes). ### Authentication handler An authentication handler: * Is a type that implements the behavior of a scheme. * Is derived from or . * Has the primary responsibility to authenticate users. Based on the authentication scheme's configuration and the incoming request context, authentication handlers: * Construct objects representing the user's identity if authentication is successful. * Return 'no result' or 'failure' if authentication is unsuccessful. * Have methods for challenge and forbid actions for when users attempt to access resources: * They're unauthorized to access (forbid). * When they're unauthenticated (challenge). ### `RemoteAuthenticationHandler` vs `AuthenticationHandler` is the class for authentication that requires a remote authentication step. When the remote authentication step is finished, the handler calls back to the `CallbackPath` set by the handler. The handler finishes the authentication step using the information passed to the callback path. [OAuth 2.0](https://oauth.net/2/) and [OIDC](https://openid.net/developers/how-connect-works/) both use this pattern. JWT and cookies don't since they can directly use the bearer header and cookie to authenticate. The remotely hosted provider in this case: * Is the authentication provider. * Examples include [Facebook](xref:security/authentication/facebook-logins), [Twitter](xref:security/authentication/twitter-logins), [Google](xref:security/authentication/google-logins), [Microsoft](xref:security/authentication/microsoft-logins), and any other OIDC provider that handles authenticating users using the handlers mechanism. ### Authenticate An authentication scheme's authenticate action is responsible for constructing the user's identity based on request context. It returns an indicating whether authentication was successful and, if so, the user's identity in an authentication ticket. See . Authenticate examples include: * A cookie authentication scheme constructing the user's identity from cookies. * A JWT bearer scheme deserializing and validating a JWT bearer token to construct the user's identity. ### Challenge An authentication challenge is invoked by Authorization when an unauthenticated user requests an endpoint that requires authentication. An authentication challenge is issued, for example, when an anonymous user requests a restricted resource or follows a login link. Authorization invokes a challenge using the specified authentication scheme(s), or the default if none is specified. See . Authentication challenge examples include: * A cookie authentication scheme redirecting the user to a login page. * A JWT bearer scheme returning a 401 result with a `www-authenticate: bearer` header. A challenge action should let the user know what authentication mechanism to use to access the requested resource. ### Forbid An authentication scheme's forbid action is called by Authorization when an authenticated user attempts to access a resource they're not permitted to access. See . Authentication forbid examples include: * A cookie authentication scheme redirecting the user to a page indicating access was forbidden. * A JWT bearer scheme returning a 403 result. * A custom authentication scheme redirecting to a page where the user can request access to the resource. A forbid action can let the user know: * They're authenticated. * They're not permitted to access the requested resource. See the following links for differences between challenge and forbid: * [Challenge and forbid with an operational resource handler](xref:security/authorization/resourcebased#challenge-and-forbid-with-an-operational-resource-handler). * [Differences between challenge and forbid](xref:security/authorization/secure-data#challenge). ## Authentication providers per tenant ASP.NET Core framework doesn't have a built-in solution for multi-tenant authentication. While it's possible for customers to write an app with multi-tenant authentication, we recommend using one of the following asp.net core application frameworks that support multi-tenant authentication: ### Orchard Core [Orchard Core](https://orchardcore.net/). See the [Orchard Core](https://github.com/OrchardCMS/OrchardCore) source for an example of authentication providers per tenant. ### ABP Framework [ABP Framework](https://abp.io/) supports various architectural patterns including modularity, microservices, domain driven design, and multi-tenancy. See [ABP Framework source on GitHub](https://github.com/abpframework/abp). ## Additional resources * * * * [Globally require authenticated users](xref:security/authorization/secure-data#rau) * [GitHub issue on using multiple authentication schemes](https://github.com/dotnet/aspnetcore/issues/26002) :::moniker-end