DNV.OAuth.Web.Extensions 1.17.1

DNV.OAuth.Web.Extensions

DNV.OAuth.Web.Extensions helps ASP.NET Core applications add optional OAuth web behaviors on top of DNV.OAuth.Web, including API-friendly cookie responses, MFA challenges, path-based multitenancy, and Veracity policy validation.

Overview

This package extends the DNV.OAuth.Web.AddOidc and OidcOptions model. It includes:

• Cookie redirect suppression for APIs.
• MFA request helpers that add mfa_required=true to OIDC authorization requests.
• Path-based tenant resolution and per-tenant cookie isolation.
• Veracity policy validation during OIDC token validation.
• Public policy validation interfaces for custom validation or violation handling.

Source repository: https://github.com/dnv-internal/SolutionPackage

Package registry: TODO: Confirm the NuGet feed or registry where this package is published.

When to use this

• Use this when a DNV.OAuth.Web application needs one of the optional web authentication behaviors provided here.
• Use this when API endpoints should return 401/403 instead of cookie-auth 302 redirects.
• Use this when a web app needs path-based tenant cookie isolation or Veracity policy validation.

When not to use this

• Do not use this without the base DNV.OAuth.Web OIDC setup.
• Do not use path-based multitenancy as a replacement for authorization or tenant data isolation.
• Do not use MFA helpers as proof of strong authentication unless the identity provider issues the expected mfaType claim.

Features

• SuppressOAuthRedirectForApi for 401/403 API responses.
• AddMfaSupport, ChallengeForMfaAsync, and SignedInWithMfa.
• UseMultitenancy and AddMultitenantAuthentication.
• AddPolicyValidation and PolicyValidationOptions.
• IPolicyValidator and IPolicyViolationHandler extension points.
• Targets net8.0 and net10.0.

Requirements

Installation

dotnet add package DNV.OAuth.Web.Extensions

If your environment uses a private NuGet feed, configure that feed before running the command.

Quick start

Configure base OIDC with DNV.OAuth.Web, then add the extensions you need.

using DNV.OAuth.Web;
using DNV.OAuth.Web.Extensions.Cookie;
using DNV.OAuth.Web.Extensions.Mfa;
using DNV.OAuth.Web.Extensions.Policy;
using Microsoft.IdentityModel.Protocols.OpenIdConnect;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();
builder.Services.AddDistributedMemoryCache();

var oidcOptions = new OidcOptions
{
    Authority = "https://login.veracity.com/tfp/<tenant>/b2c_1a_signinwithadfsidp/v2.0",
    ClientId = "<client-id>",
    ClientSecret = Environment.GetEnvironmentVariable("OAUTH_CLIENT_SECRET")!,
    Scopes = new[] { "api://example/user_impersonation", "offline_access" },
    ResponseType = OpenIdConnectResponseType.Code
};

oidcOptions.AddMfaSupport(request => request.Path.StartsWithSegments("/secure"));

builder.Services.AddOidc(oidcOptions)
    .AddPolicyValidation(options =>
    {
        options.VeracityPolicyApiConfigName = "VeracityMyPolicies";
        options.ServiceId = "<service-id>";
        options.PolicyValidationMode = PolicyValidationMode.All;
    });

builder.Services.SuppressOAuthRedirectForApi(request => request.Path.StartsWithSegments("/api"));

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

Expected result:

OIDC sign-in is configured, /secure challenges request MFA, policy validation runs after token validation, and /api redirects become 401/403 responses.

Use cases

Use case: Return 401/403 for API cookie challenges

Goal: Prevent API clients from receiving HTML login redirects.

Scenario: A web app has both MVC pages and /api endpoints protected by cookie authentication.

Prerequisites:

• Cookie authentication configured through DNV.OAuth.Web.AddOidc or ASP.NET Core cookie authentication.

Code:

using DNV.OAuth.Web.Extensions.Cookie;

var builder = WebApplication.CreateBuilder(args);

builder.Services.SuppressOAuthRedirectForApi(
    request => request.Path.StartsWithSegments("/api"));

Expected result:

Unauthenticated /api requests receive 401. Forbidden /api requests receive 403.

Why this works: The extension wraps OnRedirectToLogin and OnRedirectToAccessDenied on CookieAuthenticationOptions.

Common mistakes:

• Passing no predicate suppresses redirects for every request.
• Suppression applies only when the response status is still 200 OK.

Related:

• CookieAuthenticationExtensions source

Use case: Request MFA for sensitive routes

Goal: Ask the identity provider for MFA only when the request requires it.

Scenario: A signed-in user accesses /secure and the application wants an MFA challenge when the session does not already show MFA.

Prerequisites:

• OIDC configured with DNV.OAuth.Web.
• Identity provider support for the mfa_required parameter and mfaType claim values used by this package.

Code:

using DNV.OAuth.Web;
using DNV.OAuth.Web.Extensions.Mfa;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDistributedMemoryCache();

var oidcOptions = new OidcOptions
{
    Authority = "https://login.veracity.com/tfp/<tenant>/b2c_1a_signinwithadfsidp/v2.0",
    ClientId = "<client-id>",
    ClientSecret = Environment.GetEnvironmentVariable("OAUTH_CLIENT_SECRET")!,
    Scopes = new[] { "api://example/user_impersonation" }
};

oidcOptions.AddMfaSupport(request => request.Path.StartsWithSegments("/secure"));
builder.Services.AddOidc(oidcOptions);

public sealed class SecureController : Controller
{
    public async Task<IActionResult> Index()
    {
        if (!HttpContext.SignedInWithMfa())
        {
            await HttpContext.ChallengeForMfaAsync("/secure");
            return new EmptyResult();
        }

        return Content("MFA session");
    }
}

Expected result:

OIDC redirects for /secure include mfa_required=true until the signed-in principal has an accepted mfaType claim.

Why this works: AddMfaSupport wraps OnRedirectToIdentityProvider; ChallengeForMfaAsync stores the MFA flag in AuthenticationProperties.

Common mistakes:

• Calling ChallengeForMfaAsync with an empty redirect URL.
• Assuming SignedInWithMfa is true for all MFA mechanisms; it checks mfaType=phone or mfaType=federatedIdp.

Related:

• MfaExtensions source

Use case: Isolate authentication cookies by tenant path

Goal: Use the first URL path segment as a tenant alias and isolate authentication cookies.

Scenario: The same app serves /tenant-a and /tenant-b, but a user session for one tenant should not be reused by the other tenant.

Prerequisites:

• OIDC configured with DNV.OAuth.Web.
• UseMultitenancy called before routing and authentication.

Code:

using DNV.OAuth.Web;
using DNV.OAuth.Web.Extensions.Multitenancy;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDistributedMemoryCache();

builder.Services.AddOidc(new OidcOptions
{
    Authority = "https://login.veracity.com/tfp/<tenant>/b2c_1a_signinwithadfsidp/v2.0",
    ClientId = "<client-id>",
    ClientSecret = Environment.GetEnvironmentVariable("OAUTH_CLIENT_SECRET")!,
    Scopes = new[] { "api://example/user_impersonation", "offline_access" }
}).AddMultitenantAuthentication();

var app = builder.Build();

app.UseMultitenancy(path => path.StartsWithSegments("/health"));
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();
app.Run();

Expected result:

Requests such as /tenant-a/orders run with PathBase=/tenant-a, and cookie names receive tenant-aware postfixes.

Why this works: TenantResolutionMiddleware moves the first path segment to PathBase, while multitenant cookie options append .Super or .Sub postfixes.

Common mistakes:

• Calling UseMultitenancy after UseRouting or UseAuthentication.
• Treating path tenant resolution as data authorization. Always validate tenant access in application logic.

Related:

• Multitenancy source

Use case: Validate Veracity policies during sign-in

Goal: Require platform, service, or subscription policy validation as part of OIDC sign-in.

Scenario: A web app must ensure Veracity policies are accepted before the user is authorized.

Prerequisites:

• DNV.Veracity.Services.Api.My configuration for the named policy API config.
• A policy mode appropriate for the application.

Code:

using DNV.OAuth.Web;
using DNV.OAuth.Web.Extensions.Policy;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddDistributedMemoryCache();

builder.Services.AddOidc(new OidcOptions
{
    Authority = "https://login.veracity.com/tfp/<tenant>/b2c_1a_signinwithadfsidp/v2.0",
    ClientId = "<client-id>",
    ClientSecret = Environment.GetEnvironmentVariable("OAUTH_CLIENT_SECRET")!,
    Scopes = new[] { "api://example/user_impersonation", "offline_access" }
}).AddPolicyValidation(options =>
{
    options.VeracityPolicyApiConfigName = "VeracityMyPolicies";
    options.ServiceId = "<service-id>";
    options.PolicyValidationMode = PolicyValidationMode.All;
    options.AuthorizationPolicyName = PolicyValidationOptions.VeracityDefaultPolicy;
    options.AddAsDefaultPolicy = true;
});

Expected result:

Successful validation adds the vplcvdt claim and the configured authorization policy requires that claim.

Why this works: AddPolicyValidation wraps the OIDC OnTokenValidated event and registers an authorization policy requiring vplcvdt.

Common mistakes:

• Leaving PolicyValidationMode at the default value 0; validation fails because no mode is selected.
• Omitting VeracityPolicyApiConfigName; AddPolicyValidation throws ArgumentNullException.
• Omitting ServiceId when using modes that validate service policies.

Related:

• PolicyExtensions source

Use case: Override policy violation handling

Goal: Customize how policy validation failures are handled.

Scenario: The default handler redirects to the URL returned by the policy API, but an application wants a 403 response.

Prerequisites:

• A custom IPolicyViolationHandler registered before AddPolicyValidation.

Code:

using DNV.OAuth.Web.Extensions.Policy;
using DNV.Veracity.Services.Api.Models;
using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IPolicyViolationHandler, ForbiddenPolicyViolationHandler>();

public sealed class ForbiddenPolicyViolationHandler : IPolicyViolationHandler
{
    public Task HandleTermsAndConditionsViolated<TOptions>(
        RemoteAuthenticationContext<TOptions> ctx,
        PolicyValidationResult validationResult)
        where TOptions : AuthenticationSchemeOptions
        => WriteForbidden(ctx);

    public Task HandleServiceSubscriptionViolated<TOptions>(
        RemoteAuthenticationContext<TOptions> ctx,
        PolicyValidationResult validationResult)
        where TOptions : AuthenticationSchemeOptions
        => WriteForbidden(ctx);

    public Task HandleCompanyAffiliationViolated<TOptions>(
        RemoteAuthenticationContext<TOptions> ctx,
        PolicyValidationResult validationResult)
        where TOptions : AuthenticationSchemeOptions
        => WriteForbidden(ctx);

    private static Task WriteForbidden<TOptions>(RemoteAuthenticationContext<TOptions> ctx)
        where TOptions : AuthenticationSchemeOptions
    {
        ctx.HandleResponse();
        ctx.Response.StatusCode = StatusCodes.Status403Forbidden;
        return ctx.Response.WriteAsync("Policy validation failed.");
    }
}

Expected result:

Policy violations return 403 with a custom message instead of using the default redirect behavior.

Why this works: The package registers default policy services with TryAddSingleton, so earlier registrations win.

Common mistakes:

• Registering the custom handler after AddPolicyValidation.
• Writing sensitive policy API details into the response.

Related:

• IPolicyViolationHandler source

Configuration

API overview

Error handling and troubleshooting

Observability and diagnostics

PolicyValidator logs Veracity policy API errors with ILogger<PolicyValidator>. Other extensions rely on ASP.NET Core authentication and middleware logging.

Performance considerations

• Multitenancy creates cookie options per request through a custom IOptionsMonitor<CookieAuthenticationOptions>.
• Policy validation calls the Veracity policy API during OIDC token validation.
• Cookie suppression and MFA event wrappers add minimal per-request overhead.
• TODO: Confirm trimming and native AOT support.

Security notes

• Keep OIDC client secrets and Veracity API configuration secrets out of source control.
• MFA helpers request MFA and inspect specific mfaType claim values; they do not replace server-side authorization checks.
• Path-based tenant resolution isolates authentication cookies but does not enforce tenant data access. Validate tenant authorization in application code.
• Policy validation may redirect users to URLs returned by the policy API. Validate configuration and avoid exposing sensitive details in custom handlers.
• Authentication cookies and policy validation responses can reveal user state. Use HTTPS, secure cookies, and appropriate cache controls.
• Vulnerability reporting: TODO: Confirm the security contact or SECURITY.md process for this repository.

Examples

• DNV.OAuth.Web README
• Web test project

Versioning and compatibility

The project targets net8.0 and net10.0. Package versioning is controlled by repository MSBuild properties and BUILD_VERSION.

TODO: Confirm semantic versioning policy, supported package versions, and breaking-change process.

Contributing

From the repository root:

dotnet test src/OAuth/OAuth.sln

TODO: Confirm contribution guidelines and code review requirements.

Support

Package metadata lists author Albert Yang <albert.yang@dnv.com>.

TODO: Confirm the owning team, support contact, and issue reporting process.

License

TODO: Confirm the package license and add or link the repository license file.