https://github.com/loresoft/aspnetcore.securitykey
Security API Key Authentication Implementation for ASP.NET Core
https://github.com/loresoft/aspnetcore.securitykey
api-key api-key-authentication asp-net asp-net-core authentication
Last synced: 9 months ago
JSON representation
Security API Key Authentication Implementation for ASP.NET Core
- Host: GitHub
- URL: https://github.com/loresoft/aspnetcore.securitykey
- Owner: loresoft
- License: mit
- Created: 2024-03-21T02:17:53.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-06T19:32:33.000Z (9 months ago)
- Last Synced: 2025-05-07T04:47:57.249Z (9 months ago)
- Topics: api-key, api-key-authentication, asp-net, asp-net-core, authentication
- Language: C#
- Homepage:
- Size: 177 KB
- Stars: 3
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Security API Keys for ASP.NET Core
API Key Authentication Implementation for ASP.NET Core
[](https://github.com/loresoft/AspNetCore.SecurityKey/actions/workflows/dotnet.yml)
[](https://coveralls.io/github/loresoft/AspNetCore.SecurityKey?branch=main)
[](https://www.nuget.org/packages/AspNetCore.SecurityKey/)
## Passing API Key in a Request
- Request Headers
- Query Parameters
- Cookie
### Request Header
Example passing the security api key via a header
```
GET http://localhost:5009/users
Accept: application/json
X-API-KEY: 01HSGVBSF99SK6XMJQJYF0X3WQ
```
### Query Parameters
Example passing the security api key via a header
```
GET http://localhost:5009/users?X-API-KEY=01HSGVBSF99SK6XMJQJYF0X3WQ
Accept: application/json
```
## Security API Key Setup
### Set the Security API Key
Security API key in the appsetting.json
```json
{
"SecurityKey": "01HSGVBSF99SK6XMJQJYF0X3WQ"
}
```
Multiple keys supported via semicolon delimiter
```json
{
"SecurityKey": "01HSGVBGWXWDWTFGTJSYFXXDXQ;01HSGVBSF99SK6XMJQJYF0X3WQ"
}
```
### Register Services
```c#
var builder = WebApplication.CreateBuilder(args);
// add security api key scheme
builder.Services
.AddAuthentication()
.AddSecurityKey();
builder.Services.AddAuthorization();
// add security api key services
builder.Services.AddSecurityKey();
```
Configure Options
```c#
builder.Services.AddSecurityKey(options => {
options.ConfigurationName = "Authentication:ApiKey";
options.HeaderName = "x-api-key";
options.QueryName = "ApiKey";
options.KeyComparer = StringComparer.OrdinalIgnoreCase;
});
```
### Secure Endpoints
Secure Controller with `SecurityKeyAttribute`. Can be at class or method level
```c#
[ApiController]
[Route("[controller]")]
public class AddressController : ControllerBase
{
[SecurityKey]
[HttpGet(Name = "GetAddresses")]
public IEnumerable
Get()
{
return AddressFaker.Instance.Generate(5);
}
}
```
Secure via middleware. All endpoints will require security API key
```c#
public static class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization();
builder.Services.AddSecurityKey();
var app = builder.Build();
// required api key for all end points
app.UseSecurityKey();
app.UseAuthorization();
app.MapGet("/weather", () => WeatherFaker.Instance.Generate(5));
app.Run();
}
}
```
Secure Minimal API endpoint with filter, .NET 8+ only
```c#
public static class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAuthorization();
builder.Services.AddSecurityKey();
var app = builder.Build();
app.UseAuthorization();
app.MapGet("/users", () => UserFaker.Instance.Generate(10))
.RequireSecurityKey();
app.Run();
}
}
```
Secure with Authentication Scheme
```c#
public static class Program
{
public static void Main(string[] args)
{
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddAuthentication()
.AddSecurityKey();
builder.Services.AddAuthorization();
builder.Services.AddSecurityKey();
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/users", () => UserFaker.Instance.Generate(10))
.RequireAuthorization();
app.Run();
}
}
```
### Custom Security Key Validation
You can implement your own custom security key validation by implementing the `ISecurityKeyValidator` interface.
```c#
public class CustomSecurityKeyValidator : ISecurityKeyValidator
{
public Task ValidateAsync(HttpContext context, string key)
{
// custom validation logic
return Task.FromResult(true);
}
}
```
Use custom security key validator
```c#
builder.Services.AddSecurityKey();
```
### Custom Security Key Extractor
You can implement your own custom security key extractor by implementing the `ISecurityKeyExtractor` interface.
```c#
public class CustomSecurityKeyExtractor : ISecurityKeyExtractor
{
public Task ExtractAsync(HttpContext context)
{
// custom extraction logic
return Task.FromResult("custom-key");
}
}
```
Use custom security key validator and extrator
```c#
builder.Services.AddSecurityKey();
```
### Open API
Add Open API support in .NET 9+
```c#
var builder = WebApplication.CreateBuilder(args);
builder.Services
.AddAuthentication()
.AddSecurityKey();
builder.Services.AddAuthorization();
builder.Services.AddSecurityKey();
// add api key requirment to open api
builder.Services.AddOpenApi(options => options
.AddDocumentTransformer()
);
var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapOpenApi();
// use Scalar.AspNetCore package
app.MapScalarApiReference();
```