Authentication

Authentication is the third step in the request flow. It occurs after parsing and before model retrieval. Multiple Authentication Providers can be attached to a single route and will be executed in order until authentication succeeds. If no Auth Provider succeeds, an exception of type AuthFailedException will be thrown. Authentication Providers are optional and if none are specified this step is skipped, and the User property of the request's IApiContext<TModel, TUser> will be null.

Note

This execution method means that if any Auth Provider succeeds, the request will be considered authenticated.

Note

The SimpleExceptionHandler exception handler added by the CatchExceptions(Boolean) method will fall through to the next route specified for that route pattern if authentication fails. Additionally, routes with the same pattern are executed in order of the number of Auth Providers they have. This way, an anonymous user can be presented with an alternate API route for the same route pattern. See below for an example.

Api Context

See Also: IApiContext<TModel, TUser>

This step will set the User property on the request's IApiContext<TModel, TUser> with an object containing additional user information. This can be set to any instance of the TUser type parameter for the API. However, Auth Providers may also return null even if authentication succeeds, indicating that there is no additional user information.

NoUser

If no TUser type parameter is provided to the app.UseSeltzr method when creating the API, the user context type is set to NoUser. This is a token class with no properties, but makes additional extension methods available for authentication methods that don't return a user context. See below for an example.

Builder Methods

Low-Level Methods

These methods are primarily used when you've implemented your own IAuthProvider<TModel, TUser> and want to attach it to a route.

• AddAuthProvider(IAuthProvider<TModel, TUser>)
• AddAuthProvider<TProvider>()
• ClearAuthProviders()

High-Level Methods

Builder Prefix: Auth

• Auth(Func<IApiContext<TModel, TUser>, TUser>)
• AuthAspNetIdentity()
• AuthAspNetIdentity(String, String[])
• AuthAspNetIdentityRole(String[])
• AuthAsync(Func<IApiContext<TModel, TUser>, Task<TUser>>)
• AuthBasic(Func<String, String, TUser>)
• AuthBasicAsync(Func<String, String, Task<TUser>>)
• AuthHeader(String, Func<String, TUser>)
• AuthHeaderAsync(String, Func<String, Task<TUser>>)
• AuthQuery(String, Func<String, TUser>)
• AuthQueryAsync(String, Func<String, Task<TUser>>)

Extension Methods:

• Auth<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, Func<IApiContext<TModel, NoUser>, Boolean>)
• AuthAsync<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, Func<IApiContext<TModel, NoUser>, Task<Boolean>>)
• AuthBasic<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, Func<String, String, Boolean>)
• AuthBasic<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, String)
• AuthBasicAsync<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, Func<String, String, Task<Boolean>>)
• AuthHeader<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, Func<String, Boolean>)
• AuthHeader<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, String)
• AuthHeaderAsync<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, Func<String, Task<Boolean>>)
• AuthQuery<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, Func<String, Boolean>)
• AuthQuery<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, String)
• AuthQueryAsync<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, Func<String, Task<Boolean>>)

Examples

Using ASP.NET Core Identity Authentication

See Authenticating with ASP.NET Core Identity.

Hosting Anonymous and Authenticated Content on the Same Route

There are two ways of hosting both unauthenticated and authenticated routes with the same pattern.

• The first uses SetupAnonymousGet(Action<SeltzrOptionsBuilder<TModel, TUser>>) to clear all Auth Providers before setting up the route:

C#

Copy

options.UseSeltzr<MyModel, MyUser>(options => {
	options
		.AuthAspNetIdentity()
		.SetupGet("/get", authed => authed.WriteString("Authenticated Content"))
		.SetupAnoymousGet("/get", anon => anon.WriteString("Anonymous Content"));
});

• The second defines the anonymous route before adding the Auth Provider:

C#

Copy

options.UseSeltzr<MyModel, MyUser>(options => {
	options
		.SetupGet("/get", anon => anon.WriteString("Anonymous Content"))
		.AuthAspNetIdentity()
		.SetupGet("/get", authed => authed.WriteString("Authenticated Content"));
});

Note

There are no SetupAnonymous methods for the POST, PUT, PATCH, and DELETE methods, so you must use the second option, or call ClearAuthProviders() when setting up the route.

Authenticating with NoUser

The following example uses an extension method, AuthBasic<TModel>(SeltzrOptionsBuilder<TModel, NoUser>, String, String), which is only available when the API's user context is set to NoUser

C#

Copy

options.UseSeltzr<MyModel>(options => {
	options
		.AuthBasic("Username", "Password1")
		.SetupGet(authed => authed.WriteString("Authenticated Content"));
});