Startbit-Authy 1.0.0

dot-net-core-auth-library

One library. All authentication methods. Zero hardcoded secrets.

UnifiedAuth is a plug-and-play authentication library for ASP.NET Core 9 that unifies JWT, OAuth 2.0, OIDC, and API Key authentication into a single consistent API. All credentials are managed through a single configuration file — no secrets in code, ever.

Features

• JWT — HS256 token generation, validation, and refresh token rotation
• OAuth 2.0 / OIDC — Google, GitHub, Microsoft Azure AD, and Okta built in
• API Key — header or query string, with per-key roles and active/inactive states
• OIDC Discovery — automatic endpoint resolution with 24-hour caching
• Zero hardcoded secrets — credentials live in unifiedauth.credentials.json or appsettings.json
• Single DI call — AddUnifiedAuth() wires everything into ASP.NET Core
• Token store abstraction — swap in Redis, SQL, or any custom store
• Auto template — missing credentials file is generated automatically on first run

Packages

Packaging the Library

Prerequisites

• .NET 9 SDK
• Visual Studio 2022 or dotnet CLI

Step 1 — Clone and build

git clone https://github.com/YourName/UnifiedAuth.git
cd UnifiedAuth
dotnet build -c Release

Step 2 — Create a local output folder

mkdir C:\LocalPackages

Step 3 — Pack all projects

Run from the solution root:

dotnet pack UnifiedAuth.Core\UnifiedAuth.Core.csproj             -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.Jwt\UnifiedAuth.Jwt.csproj               -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.OAuth\UnifiedAuth.OAuth.csproj           -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.Google\UnifiedAuth.Google.csproj         -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.GitHub\UnifiedAuth.GitHub.csproj         -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.Microsoft\UnifiedAuth.Microsoft.csproj   -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.Okta\UnifiedAuth.Okta.csproj             -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.ApiKey\UnifiedAuth.ApiKey.csproj         -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth.AspNetCore\UnifiedAuth.AspNetCore.csproj -c Release -o C:\LocalPackages
dotnet pack UnifiedAuth\UnifiedAuth.csproj                       -c Release -o C:\LocalPackages

This produces .nupkg files in C:\LocalPackages\.

Step 4 — Add local NuGet source

Visual Studio: Tools → Options → NuGet Package Manager → Package Sources → click +

CLI:

dotnet nuget add source C:\LocalPackages --name "UnifiedAuth Local"

Step 5 — Install in your app

dotnet add package UnifiedAuth --version 1.0.0

Or via Visual Studio NuGet Manager — switch source to UnifiedAuth Local and search for UnifiedAuth.

Quick Start

1. Add credentials file

Create unifiedauth.credentials.json in your project root. Right-click → Properties → Copy to Output Directory: Copy always.

{
  "Jwt": {
    "Secret": "your-strong-secret-min-32-characters!!",
    "Issuer": "your-app",
    "Audience": "your-users",
    "AccessTokenExpiryMinutes": 15,
    "RefreshTokenExpiryDays": 7,
    "UseRefreshTokens": true
  },
  "Google": {
    "ClientId": "YOUR_GOOGLE_CLIENT_ID",
    "ClientSecret": "YOUR_GOOGLE_CLIENT_SECRET",
    "CallbackPath": "/auth/callback/google"
  },
  "GitHub": {
    "ClientId": "YOUR_GITHUB_CLIENT_ID",
    "ClientSecret": "YOUR_GITHUB_CLIENT_SECRET",
    "CallbackPath": "/auth/callback/github"
  },
  "Microsoft": {
    "ClientId": "YOUR_MICROSOFT_CLIENT_ID",
    "ClientSecret": "YOUR_MICROSOFT_CLIENT_SECRET",
    "TenantId": "common",
    "CallbackPath": "/auth/callback/microsoft"
  },
  "Okta": {
    "Domain": "dev-xxxxxx.okta.com",
    "ClientId": "YOUR_OKTA_CLIENT_ID",
    "ClientSecret": "YOUR_OKTA_CLIENT_SECRET",
    "CallbackPath": "/auth/callback/okta"
  },
  "ApiKey": {
    "HeaderName": "X-Api-Key",
    "AllowQueryString": false,
    "Keys": [
      {
        "Key": "your-api-key-here",
        "OwnerId": "service-1",
        "OwnerName": "My Service",
        "Roles": ["read", "write"],
        "IsActive": true
      }
    ]
  }
}

Important: Add unifiedauth.credentials.json to .gitignore.

Alternatively, pass IConfiguration to read from appsettings.json:

builder.Services.AddUnifiedAuth(
    builder.Configuration,  // reads from appsettings.json
    auth => { auth.AddJwt(); auth.AddGoogle(); });

2. Register in Program.cs

using UnifiedAuth.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddUnifiedAuth(auth =>
{
    auth.AddJwt();       // enable JWT
    auth.AddGoogle();    // enable Google
    auth.AddGitHub();    // enable GitHub
    auth.AddMicrosoft(); // enable Microsoft
    auth.AddOkta();      // enable Okta
    auth.AddApiKey();    // enable API Key

    // Or enable all providers that have credentials configured:
    // auth.AddAllConfigured();
});

var app = builder.Build();

app.UseUnifiedAuth(); // token validation middleware

app.Run();

3. Generate and validate JWT tokens

using UnifiedAuth.Jwt.Services;
using UnifiedAuth.Core.Models;

// Generate tokens after verifying credentials against your DB
app.MapPost("/auth/login", (JwtTokenService tokenService) =>
{
    var user = new AuthUser
    {
        Id       = Guid.NewGuid().ToString(),
        Email    = "user@example.com",
        Name     = "John Doe",
        Provider = "JWT"
    };
    var tokens = tokenService.GenerateTokens(user);
    return Results.Ok(tokens);
});

// Access authenticated user on any protected endpoint
app.MapGet("/me", (HttpContext context) =>
{
    var user = context.Items["AuthUser"] as AuthUser;
    if (user is null) return Results.Unauthorized();
    return Results.Ok(user);
});

4. Handle OAuth callbacks

// Step 1 — Redirect user to provider login page
app.MapGet("/auth/login/google", () =>
    Results.Redirect(
        $"https://accounts.google.com/o/oauth2/v2/auth" +
        $"?client_id={clientId}" +
        $"&redirect_uri=http://localhost:5000/auth/callback/google" +
        $"&response_type=code&scope=openid%20email%20profile"));

// Step 2 — Handle the callback from the provider
app.MapGet("/auth/callback/google", async (
    HttpContext context,
    IEnumerable<IAuthProvider> providers) =>
{
    var code     = context.Request.Query["code"].ToString();
    var provider = providers.First(p => p.ProviderName == "Google");

    var result = await provider.AuthenticateAsync(new AuthContext
    {
        Code        = code,
        RedirectUri = "http://localhost:5000/auth/callback/google"
    });

    if (!result.Succeeded)
        return Results.BadRequest(result.Error);

    // result.User contains: Id, Email, Name, Provider, Claims
    return Results.Ok(result.User);
});

Provider Setup

Register the redirect URI in each provider's developer console before use.

Replace PORT with your application's actual port number. The redirect URI registered in the console must match exactly what your code sends.

Core Abstractions

Every provider implements the same interface:

public interface IAuthProvider
{
    string ProviderName { get; }
    Task<AuthResult> AuthenticateAsync(AuthContext context, CancellationToken ct = default);
    Task<AuthResult> RefreshAsync(string refreshToken, CancellationToken ct = default);
    Task RevokeAsync(string token, CancellationToken ct = default);
}

Replace the default in-memory token store with Redis, SQL, or any custom store:

public class RedisTokenStore : ITokenStore
{
    public Task SaveAsync(string key, TokenBundle tokens, CancellationToken ct = default) { ... }
    public Task<TokenBundle?> GetAsync(string key, CancellationToken ct = default) { ... }
    public Task RevokeAsync(string key, CancellationToken ct = default) { ... }
    public Task<bool> ExistsAsync(string key, CancellationToken ct = default) { ... }
}

// Register before calling AddUnifiedAuth
builder.Services.AddSingleton<ITokenStore, RedisTokenStore>();

Add a custom provider by extending OAuthProviderBase:

public class FacebookAuthProvider : OAuthProviderBase
{
    public override string ProviderName => "Facebook";

    protected override Task<string> GetTokenEndpointAsync(CancellationToken ct = default)
        => Task.FromResult("https://graph.facebook.com/v18.0/oauth/access_token");

    protected override Task<string> GetUserInfoEndpointAsync(CancellationToken ct = default)
        => Task.FromResult("https://graph.facebook.com/me?fields=id,name,email");

    public override async Task<AuthResult> AuthenticateAsync(
        AuthContext context, CancellationToken ct = default)
    {
        // your implementation here
    }
}

// Register it
builder.Services.AddSingleton<IAuthProvider, FacebookAuthProvider>();

Packaging the library

# Pack
dotnet pack UnifiedAuth\UnifiedAuth.csproj -c Release -o C:\LocalPackages