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.
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:
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:
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
options.UseSeltzr<MyModel>(options => {
options
.AuthBasic("Username", "Password1")
.SetupGet(authed => authed.WriteString("Authenticated Content"));
});