Tooark.Securities.OpenId 4.7.0

Tooark.Securities.OpenId

Library that standardizes how Tooark projects configure OpenID Connect authentication in ASP.NET Core, with SSO presets for Microsoft Entra ID and Google and a generic path for any OIDC provider (Keycloak, Auth0, Okta...).

The package configures the native handlers of ASP.NET Core — OpenIdConnect, JwtBearer and cookie — and implements no protocol flow. There is no provider SDK, no authorization server, no code issuance and no PKCE verification of its own: that territory belongs to OpenIddict, Duende and Keycloak. The value is in the configuration standard: code flow with PKCE, token validation and claim mapping that are the same across every project.

🌍 Languages: 🇺🇸 English (this file) · 🇧🇷 Português

📑 Contents

• Overview
• Installation
• Configuration
• Presets
• Generic provider and custom presets
• Components
• Usage Examples
• Dependencies
• Best Practices
• Error Codes and Solutions
• Contributing
• Help & Security
• Support
• License

📖 Overview

Each provider is read from the OpenId:{name} subsection of appsettings.json, and the name becomes the authentication scheme registered in ASP.NET Core. There are two handlers per provider:

The Tooark defaults applied to the handlers:

• code flow with PKCE — the ASP.NET Core handler is born in id_token (implicit flow, abandoned by OAuth 2.1); the package pins authorization code and turns PKCE on.
• Claims with their OpenID Connect names — MapInboundClaims = false: sub, email and name arrive as they are, without becoming ClaimTypes.NameIdentifier and the like.
• Issuer, audience and lifetime validation always on, with a configurable clock skew.
• HTTPS required for the discovery document, unless explicitly relaxed for development.
• Fail at startup: missing ClientId, Authority/tenant and secret, invalid addresses and a multi-tenant tenant without issuers are reported on registration, not on the first login.

🔧 Installation

dotnet add package Tooark.Securities.OpenId

⚙️ Configuration

appsettings.json

Every provider lives under OpenId, one per subsection. The presets have a default name (Entra, Google); the generic provider uses the name you pass on registration.

{
  "OpenId": {
    "Entra": {
      "TenantId": "11111111-2222-3333-4444-555555555555",
      "ClientId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "ClientSecret": "secret-from-the-entra-registration"
    },
    "Google": {
      "ClientId": "1234567890-abc.apps.googleusercontent.com",
      "ClientSecret": "secret-from-the-google-console",
      "HostedDomain": "tooark.com"
    },
    "Keycloak": {
      "Authority": "https://sso.example.com/realms/tooark",
      "ClientId": "app-web",
      "ClientSecret": "client-secret"
    }
  }
}

Secrets go to the Secret Manager, environment variables or a vault — never to the repository. The equivalent environment key is OpenId__Entra__ClientSecret.

Program.cs

using Tooark.Securities.OpenId.Injections;

var builder = WebApplication.CreateBuilder(args);

// Login with Entra ID (web application)
builder.Services.AddTooarkEntraSso(builder.Configuration);

builder.Services.AddAuthorization();

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

Every method accepts the provider name and a programmatic configuration action, applied on top of appsettings.json:

builder.Services.AddTooarkEntraSso(builder.Configuration, "EntraCorp", options =>
{
  options.Scopes = ["openid", "profile", "email", "User.Read"];
  options.Prompt = "select_account";
});

OpenIdOptions properties

Apply to the presets and to the generic provider. The SSO and Bearer columns show in which handler the property takes effect.

The issuers in ValidIssuers add to the issuer of the discovery document, which the handler always accepts. ValidAudiences in the interactive handler only complements the ClientId, which is the audience of the id_token by definition.

Default schemes

The first registered provider sets the ASP.NET Core default schemes, and only when the application has not set them yet:

For mixed scenarios (site + API in the same application), register both with different names and point to the scheme in the API endpoints with [Authorize(AuthenticationSchemes = "EntraApi")], or set the defaults explicitly in AddAuthentication(options => ...) — whatever the application sets is preserved.

🔑 Presets

Microsoft Entra ID — EntraOptions

Preset derivations:

• Authority = {Instance}{TenantId}/v2.0 (an explicit Authority takes precedence).
• NameClaimType = preferred_username (UPN/login email); RoleClaimType = roles (app roles).
• ValidIssuers = the tenant's v2 issuer and the v1 issuer (https://sts.windows.net/{tenant}/), in the public cloud. APIs registered without requestedAccessTokenVersion: 2 receive v1 tokens — and the v1 issuer only matches when TenantId is the GUID.
• ValidAudiences (Bearer) = {ClientId} and api://{ClientId}, the default Application ID URI. A custom URI must be provided in ValidAudiences.
• Multi-tenant (TenantId = common, organizations or consumers): the discovery document publishes an issuer with the {tenantid} placeholder, which never matches; the preset requires ValidIssuers with the issuers of the accepted tenants and fails at startup without them.
• ClientSecret is required for SSO: Entra does not exchange the code of a web application without the secret (AADSTS7000218).

Out of scope: Graph API, distributed token cache and the on-behalf-of flow require Microsoft.Identity.Web. The criterion for a package of its own is "requires the provider SDK" — in that case, a Tooark.Securities.Entra satellite.

Google — GoogleOptions

Preset derivations:

• Authority = https://accounts.google.com.
• NameClaimType = email.
• ValidIssuers = https://accounts.google.com and accounts.google.com — Google uses both forms.
• HostedDomain: sent as the hd parameter on the login screen and checked against the token's hd claim. The hint on the screen restricts nothing by itself; accounts from another domain and personal accounts (without the claim) are rejected with OpenId.HostedDomain.Invalid. The check is chained after the consumer callback, so it survives ConfigureOpenIdConnect/ConfigureJwtBearer even when they replace Events.
• ClientSecret is required for SSO.
• Bearer: validates Google's id_token (JWT with aud = ClientId). Google's access token is opaque and does not go through this handler.

🧩 Generic provider and custom presets

For any OpenID Connect provider, provide the Authority and register by name:

builder.Services.AddTooarkOpenIdSso(builder.Configuration, "Keycloak");
builder.Services.AddTooarkOpenIdBearer(builder.Configuration, "Keycloak");

For a provider with its own conventions, inherit from OpenIdOptions and override what you need — that is exactly how EntraOptions and GoogleOptions are built:

public class KeycloakOptions : OpenIdOptions
{
  public string? BaseUrl { get; set; }
  public string? Realm { get; set; }

  // Derives the Authority when not provided
  public override string? Authority
  {
    get => base.Authority ?? (Realm is null ? null : $"{BaseUrl}/realms/{Realm}");
    set => base.Authority = value;
  }

  // Own validations, besides the common ones
  public override void Validate(bool interactive)
  {
    if (string.IsNullOrWhiteSpace(Realm))
    {
      throw new InternalServerErrorException("Options.OpenId.Keycloak.RealmNotConfigured");
    }

    base.Validate(interactive);
  }

  // Extra behavior on the handler (the consumer callback already ran inside base)
  public override void ConfigureHandler(OpenIdConnectOptions target)
  {
    base.ConfigureHandler(target);
    target.ClaimActions.MapJsonKey("realm_roles", "realm_access.roles");
  }
}

builder.Services.AddTooarkOpenIdSso<KeycloakOptions>(builder.Configuration, "Keycloak");

Available virtual members: Authority, ResolveValidIssuers(), ResolveValidAudiences(), Validate(bool interactive), ConfigureHandler(OpenIdConnectOptions) and ConfigureHandler(JwtBearerOptions).

📦 Components

Dependency Injection Extensions

Common signature: (IConfiguration configuration, string name, Action<TOptions>? configure = null) — in the presets, name has a default value. All of them return IServiceCollection.

Options

📝 Usage Examples

Web application with corporate login (Entra)

builder.Services.AddTooarkEntraSso(builder.Configuration);
builder.Services.AddAuthorization();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/profile", (ClaimsPrincipal user) => new
{
  Name = user.Identity?.Name,                 // preferred_username
  Id = user.FindFirst("oid")?.Value,          // user id in the tenant
  Roles = user.FindAll("roles").Select(claim => claim.Value)
}).RequireAuthorization();

app.MapGet("/login", () => Results.Challenge(
  new AuthenticationProperties { RedirectUri = "/" },
  ["Entra"]
));

app.MapGet("/logout", () => Results.SignOut(
  new AuthenticationProperties { RedirectUri = "/" },
  [CookieAuthenticationDefaults.AuthenticationScheme, "Entra"]
));

Two providers in the same application

The providers share the same cookie; the first registered is the default challenge. The login screen picks the provider by scheme:

builder.Services.AddTooarkEntraSso(builder.Configuration);
builder.Services.AddTooarkGoogleSso(builder.Configuration);

app.MapGet("/login/{provider}", (string provider) => Results.Challenge(
  new AuthenticationProperties { RedirectUri = "/" },
  [provider]   // "Entra" or "Google"
));

API protected by Entra tokens

builder.Services.AddTooarkEntraBearer(builder.Configuration);
builder.Services.AddAuthorization();

app.MapGet("/api/orders", () => Results.Ok()).RequireAuthorization();

Site and API in the same application (BFF)

builder.Services.AddTooarkEntraSso(builder.Configuration);                  // OpenId:Entra    → cookie + challenge
builder.Services.AddTooarkEntraBearer(builder.Configuration, "EntraApi");   // OpenId:EntraApi → API

app.MapGet("/api/orders", () => Results.Ok())
  .RequireAuthorization(new AuthorizeAttribute { AuthenticationSchemes = "EntraApi" });

Google restricted to the company domain

{
  "OpenId": {
    "Google": {
      "ClientId": "1234567890-abc.apps.googleusercontent.com",
      "ClientSecret": "secret",
      "HostedDomain": "tooark.com"
    }
  }
}

builder.Services.AddTooarkGoogleSso(builder.Configuration);

Custom cookie

Register the cookie first and provide SignInScheme; the package stops registering the default cookie:

builder.Services.AddAuthentication().AddCookie("AppCookie", options =>
{
  options.LoginPath = "/login";
  options.ExpireTimeSpan = TimeSpan.FromHours(8);
  options.SlidingExpiration = true;
});

builder.Services.AddTooarkEntraSso(builder.Configuration, configure: options => options.SignInScheme = "AppCookie");

Fine-tuning the handler

The callback is the last to run, so it can override any default:

builder.Services.AddTooarkOpenIdSso(builder.Configuration, "Keycloak", options =>
{
  options.ConfigureOpenIdConnect = oidc =>
  {
    oidc.ResponseMode = OpenIdConnectResponseMode.Query;
    oidc.Events.OnTokenValidated = context =>
    {
      // enrich the principal, audit the login...
      return Task.CompletedTask;
    };
  };
});

Development against a local provider

{
  "OpenId": {
    "Keycloak": {
      "Authority": "http://localhost:8080/realms/dev",
      "ClientId": "app-web",
      "RequireHttpsMetadata": false
    }
  }
}

Multiple instances or containers

The session cookie, the correlation cookies and the login state are protected by ASP.NET Core Data Protection. By default each instance has its own keys, and a login that starts on one instance and comes back through another fails with Correlation failed or Unable to unprotect the message.State. Share the key ring with AddTooarkDataProtection from Tooark.Securities:

builder.Services.AddTooarkDataProtection(builder.Configuration);        // DataProtection → shared key ring
builder.Services.AddTooarkEntraSso(builder.Configuration);              // OpenId:Entra    → cookie + challenge

{
  "DataProtection": {
    "ApplicationName": "app-web",
    "RequirePersistentKeyStorage": true,
    "KeysPath": "/var/dataprotection/keys",
    "CertificatePath": "/var/dataprotection/certificate.pfx",
    "CertificatePassword": "certificate-password"
  }
}

With RequirePersistentKeyStorage, the application does not start without the key storage. The other risks of multiple instances are in Clusters, containers and autoscaling.

📋 Dependencies

The package declares the Microsoft.AspNetCore.App shared framework: it exists to configure the ASP.NET Core authentication handlers and has no use outside an ASP.NET Core application.

🎯 Best Practices

1. One registration per application at the provider — site and API must have their own ClientId; the BFF above uses two.
2. Secrets out of the repository — Secret Manager in development, a vault or environment variables in production (OpenId__Entra__ClientSecret).
3. A specific tenant in Entra — prefer the tenant GUID over common/organizations; multi-tenant requires listing the accepted issuers and widens the surface of who can authenticate.
4. Check hd in Google — HostedDomain does that; without it, any Google account gets in.
5. Do not turn on SaveTokens without need — the tokens go into the cookie; turn it on only when the application calls other APIs on behalf of the user.
6. Keep MapInboundClaims = false — new code reads sub, email, name; turn it on only for legacy code tied to ClaimTypes.*.
7. RequireHttpsMetadata = false only in development — and never in the versioned appsettings.json; use appsettings.Development.json.
8. A shared key ring with more than one instance — without it, the login fails when the load balancer switches instances in the middle of the flow; see Multiple instances or containers.

⚠️ Error Codes and Solutions

Configuration errors are InternalServerErrorExceptions thrown on registration (Program.cs). The domain rejection happens during token validation and results in an authentication failure (401), with no exception.

🤝 Contributing

Contributions are welcome! Start with CONTRIBUTING.md — it covers the development workflow, the coding and commit conventions and the pull request checklist. Bugs and feature requests go through the issue templates of the Tooark repository.

By participating you agree to the Code of Conduct.

🆘 Help & Security

• ❓ Questions, bugs, feature ideas — see SUPPORT.md for the right channel
• 🔒 Security vulnerabilities — do not open a public issue; follow SECURITY.md

💖 Support

If Tooark helps your projects, consider supporting its development:

• 💙 GitHub Sponsors
• ☕ Ko-fi

Every contribution helps keep the project maintained and improving. Thank you! 🙏

📄 License

This project is licensed under the BSD 3-Clause License.