A library to easily integrate Authentication in ASP.NET Core projects. Currently it supports JWT Bearer, API Key and Basic Authentication in both Controller-based and Minimal API projects.
Important
Update from Version 2.x to 3.x
Swashbuckle (Swagger) support has been moved out from SimpleAuthentication. If you're using the AddSimpleAuthentication extension method with AddSwaggerGen, now you need to install the SimpleAuthentication.Swashbuckle package.
The library is available on NuGet. Just search for SimpleAuthenticationTools in the Package Manager GUI or run the following command in the .NET CLI:
dotnet add package SimpleAuthenticationToolsTake a look to a quick demo showing how to integrate the library:
Authentication can be totally configured adding an Authentication section in the appsettings.json file:
"Authentication": {
"DefaultScheme": "Bearer", // Optional
"JwtBearer": {
"SchemeName": "Bearer" // Default: Bearer
//"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
//"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
"SecurityKey": "supersecretsecuritykey42!", // Required
"Algorithm": "HS256", // Default: HS256
"Issuers": [ "issuer" ], // Optional
"Audiences": [ "audience" ], // Optional
"ExpirationTime": "01:00:00", // Default: No expiration
"ClockSkew": "00:02:00", // Default: 5 minutes
"EnableJwtBearerService": true // Default: true
},
"ApiKey": {
"SchemeName": "ApiKey", // Default: ApiKey
// You can specify either HeaderName, QueryStringKey or both
"HeaderName": "x-api-key",
"QueryStringKey": "code",
//"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
//"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
// Uncomment this line if you want to validate the API Key against a fixed value.
// Otherwise, you need to register an IApiKeyValidator implementation that will be used
// to validate the API Key.
//"ApiKeyValue": "f1I7S5GXa4wQDgLQWgz0",
"UserName": "ApiUser" // Required if ApiKeyValue is used
},
"Basic": {
"SchemeName": "Basic", // Default: Basic
//"NameClaimType": "user_name", // Default: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
//"RoleClaimType": "user_role", // Default: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
// Uncomment the following lines if you want to validate user name and password
// against fixed values.
// Otherwise, you need to register an IBasicAuthenticationValidator implementation
// that will be used to validate the credentials.
//"UserName": "marco",
//"Password": "P@$$w0rd"
}
}
You can configure only the kind of authentication you want to use, or you can include all of them.
The DefaultScheme attribute is used to specify what kind of authentication must be configured as default. Allowed values are the values of the SchemeName attributes.
Registering authentication at Startup
usingSimpleAuthentication;varbuilder=WebApplication.CreateBuilder(args);// ...// Registers authentication schemes and services using IConfiguration information (see above).builder.Services.AddSimpleAuthentication(builder.Configuration);// ...varapp=builder.Build();//...// The following middlewares aren't strictly necessary in .NET 7.0 or higher, because they are automatically// added when detecting that the corresponding services have been registered. However, you may// need to call them explicitly if the default middlewares configuration is not correct for your// app, for example when you need to use CORS.// Check https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/middleware// for more information.//app.UseAuthentication();//app.UseAuthorization();//...app.Run();Integrating with Swashbuckle
If you're using Swashbuckle (Swagger) to document your API, you can integrate the authentication configuration with the Swagger documentation. Just search for SimpleAuthenticationTools.Swashbuckle in the Package Manager GUI or run the following command in the .NET CLI:
dotnet add package SimpleAuthenticationTools.SwashbuckleThen, you can use the AddSimpleAuthentication extension method:
builder.Services.AddSwaggerGen(options =>{// ...// Add this line to integrate authentication with Swagger.options.AddSimpleAuthentication(builder.Configuration);});Integrating with Microsoft.AspNetCore.OpenApi (.NET 9 or later)
Starting from version 9, .NET offer a built-in support for OpenAPI. If you're using the AddOpenApi extension method to provide OpenAPI support, you just need to add the corresponding extension method in its declaration (no extra package required):
builder.Services.AddOpenApi(options =>{// ...// Add this line to integrate authentication with OpenAPI.options.AddSimpleAuthentication(builder.Configuration);});Important
Known issue
Currently, to make the AddSimpleAuthentication extension method work with AddOpenApi, you need to have at least one endpoint that produces a Problem response, for example:
app.MapPost("api/auth/login",()=>{// ...}).ProducesProblem(StatusCodes.Status400BadRequest);This is a workaround that will be fixed in the next release.
Creating a JWT Bearer
When using JWT Bearer authentication, you can set the EnableJwtBearerService setting to true to automatically register an implementation of the IJwtBearerService interface to create a valid JWT Bearer, according to the setting you have specified in the appsettings.json file:
app.MapPost("api/auth/login",(LoginRequestloginRequest,IJwtBearerServicejwtBearerService)=>{// Check for login rights...// Add custom claims (optional).varclaims=newList<Claim>{new(ClaimTypes.GivenName,"Marco"),new(ClaimTypes.Surname,"Minerva")};vartoken=jwtBearerService.CreateToken(loginRequest.UserName,claims);returnTypedResults.Ok(newLoginResponse(token));});publicrecordclassLoginRequest(stringUserName,stringPassword);publicrecordclassLoginResponse(stringToken);The IJwtBearerService.CreateToken method allows to specify the issuer and the audience of the token. If you don't specify any value, the first ones defined in appsettings.json will be used.
Supporting multiple API Keys/Basic Authentication credentials
When using API Key or Basic Authentication, you can specify multiple fixed values for authentication:
"Authentication": {
"ApiKey": {
"ApiKeys": [
{
"Value": "key-1",
"UserName": "UserName1"
},
{
"Value": "key-2",
"UserName": "UserName2"
}
]
},
"Basic": {
"Credentials": [
{
"UserName": "UserName1",
"Password": "Password1"
},
{
"UserName": "UserName2",
"Password": "Password2"
}
]
}
}With this configuration, authentication will succedd if any of these credentials are provided.
Custom Authentication logic for API Keys and Basic Authentication
If you need to implement custom authentication login, for example validating credentials with dynamic values and adding claims to identity, you can omit all the credentials in the appsettings.json file and then provide an implementation of IApiKeyValidator.cs or IBasicAuthenticationValidator.cs:
builder.Services.AddTransient<IApiKeyValidator,CustomApiKeyValidator>();builder.Services.AddTransient<IBasicAuthenticationValidator,CustomBasicAuthenticationValidator>();//...publicclassCustomApiKeyValidator:IApiKeyValidator{publicTask<ApiKeyValidationResult>ValidateAsync(stringapiKey){varresult=apiKeyswitch{"ArAilHVOoL3upX78Cohq"=>ApiKeyValidationResult.Success("User 1"),"DiUU5EqImTYkxPDAxBVS"=>ApiKeyValidationResult.Success("User 2"),
_ =>ApiKeyValidationResult.Fail("Invalid User")};returnTask.FromResult(result);}}publicclassCustomBasicAuthenticationValidator:IBasicAuthenticationValidator{publicTask<BasicAuthenticationValidationResult>ValidateAsync(stringuserName,stringpassword){if(userName==password){varclaims=newList<Claim>(){new(ClaimTypes.Role,"User")};returnTask.FromResult(BasicAuthenticationValidationResult.Success(userName,claims));}returnTask.FromResult(BasicAuthenticationValidationResult.Fail("Invalid user"));}}The library provides services for adding permission-based authorization to an ASP.NET Core project. Just use the following registration at startup:
// Enable permission-based authorization.builder.Services.AddPermissions<T>();The AddPermissions extension method requires an implementation of the IPermissionHandler interface, that is responsible to check if the user owns the required permissions:
publicinterfaceIPermissionHandler{Task<bool>IsGrantedAsync(ClaimsPrincipaluser,IEnumerable<string>permissions);}The library provides the built-in ScopeClaimPermissionHandler class, that checks for permissions reading the default scope claims of the current user (scp or http://schemas.microsoft.com/identity/claims/scope). To use this default handler, we can just write this:
builder.Services.AddScopePermissions();// The line above is equivalent to builder.Services.AddPermissions<ScopeClaimPermissionHandler>();Based on the scenario, we can provide our own implementation, for example reading different claims or using external services (database, HTTP calls, etc.) to get user permissions.
Then, just use the PermissionAttribute or the RequirePermission extension method:
// In a Controller[Permission("profile")]publicActionResult<User>Get()=>newUser(User.Identity!.Name);// In a Minimal APIapp.MapGet("api/me",(ClaimsPrincipaluser)=>{returnTypedResults.Ok(newUser(user.Identity!.Name));}).RequirePermission("profile")With the ScopeClaimPermissionHandler mentioned above, the invocation succeeds if the user has a scp or http://schemas.microsoft.com/identity/claims/scope claim that contains the profile value, for example:
"scp": "profile email calendar:read"It is also possible to explicitly create a policy that requires the one or more permissions:
builder.Services.AddAuthorization(options =>{// Define permissions using a policy.options.AddPolicy("UserProfile", builder =>builder.RequirePermission("profile"));});// ...// In a Controller[Authorize(Policy="UserProfile")]publicActionResult<User>Get()=>newUser(User.Identity!.Name);// In a Minimal APIapp.MapGet("api/me",(ClaimsPrincipaluser)=>{returnTypedResults.Ok(newUser(user.Identity!.Name));}).RequireAuthorization(policyNames:"UserProfile")- JWT Bearer (Controller | Minimal API)
- API Key (Controller | Minimal API)
- Basic Authentication (Controller | Minimal API)
The project is constantly evolving. Contributions are welcome. Feel free to file issues and pull requests on the repo and we'll address them as we can.