Startbit-Authy 1.0.1

dot-net-core-auth-library

One library. All authentication methods. Zero hardcoded secrets.

Startbit-Authy is a plug-and-play authentication library for ASP.NET Core 10 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 10 SDK
• Visual Studio 2026 or dotnet CLI

Step 1 — Clone and build

git clone https://github.com/anilprajapatistartbit/dot-net-core-auth-library.git
cd Startbit-Authy
dotnet build -c Release

Step 2 — Create a local output folder

mkdir C:\LocalPackages

Step 3 — Pack the project

Run from the solution root:

dotnet pack Startbit-Authy\Startbit-Authy.csproj             -c Release -o C:\LocalPackages

This produces .nupkg file 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 "Startbit-Authy Local"

Step 5 — Install in your app

dotnet add package Startbit-Authy --version 1.0.0

Or via Visual Studio NuGet Manager — switch source to Startbit-Authy Local and search for Startbit-Authy.

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>();

Get Real Credentials

Google 1.Go to https://console.cloud.google.com 2.Create a new project 3.Go to APIs & Services → Credentials 4.Click Create Credentials → OAuth 2.0 Client ID 5.Application type: Web application 6.Add Authorized redirect URI: http://localhost:5068/auth/callback/google 7.Copy ClientId and ClientSecret

GitHub 1.Go to https://github.com/settings/developers 2.Click New OAuth App 3.Homepage URL: http://localhost:5068 4.Authorization callback URL: http://localhost:5068/auth/callback/github 5.Copy ClientId and ClientSecret

Microsoft 1.Go to https://portal.azure.com 2.Search App registrations → New registration 3.Redirect URI: http://localhost:5068/auth/callback/microsoft 4.Go to Certificates & secrets → New client secret 5.Copy ClientId and ClientSecret

Okta 1.Go to https://developer.okta.com and create a free account 2.Go to Applications → Create App Integration 3.Select OIDC, then Web Application 4.Sign-in redirect URI: http://localhost:5068/auth/callback/okta 5.Copy Domain, ClientId and ClientSecret

Test in Browser

Once running, open your browser and navigate to: Provider URL to open in browser Google - http://localhost:5188/auth/login/google GitHub - http://localhost:5188/auth/login/github Microsoft - http://localhost:5188/auth/login/microsoft Okta - http://localhost:5188/auth/login/okta Each URL will redirect you to the provider's login page. After you log in, the provider sends the code back to your callback endpoint and you'll see the user info and token in the browser.

Sample Application

A Sample Application demonstrating all features is available in the SampleApp folder.