VisuAuth.EntraExternal.Web 0.2.0

VisuAuth.EntraExternal.Web

End-user OIDC sign-in for the VisuAuth Entra External adapter. Opt-in sub-package: wraps Microsoft.Identity.Web so the consumer's /visuauth/login page renders a working "Sign in with Microsoft" button that round-trips through the External tenant's hosted page at {tenant}.ciamlogin.com.

Why a separate package. Microsoft.Identity.Web is a heavy dependency (cookies, OpenIdConnect, token caching, MSAL). Consumers who only want admin CRUD against the directory (via VisuAuth.EntraExternal) don't pay that weight. Add this package only when you want the End-user UI to actually authenticate customers.

Install

dotnet add package VisuAuth
dotnet add package VisuAuth.EntraExternal
dotnet add package VisuAuth.EntraExternal.Web

Minimal Program.cs:

using VisuAuth;
using VisuAuth.EntraExternal.DependencyInjection;
using VisuAuth.EntraExternal.Web.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddVisuAuth()
    .AddAdminUi()
    .AddEndUserUi();

builder.Services.AddVisuAuthEntraExternal(builder.Configuration);
builder.Services.AddVisuAuthEntraExternalSignIn(builder.Configuration);

var app = builder.Build();
app.UseStaticFiles();
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.MapVisuAuth();
app.Run();

The sign-in section binds from VisuAuth:EntraExternal:Web by default — distinct from the admin Graph section (VisuAuth:EntraExternal) because sign-in and Graph use different app registrations in a typical deployment.

Configure

Profile attribute sync (claims → Graph user)

When your sign-up user flow collects attributes and emits them as token claims, VisuAuth can copy them onto the directory user on each sign-in — no Graph claims-mapping policy or beta API needed. It's off by default; opt in:

"VisuAuth": {
  "EntraExternal": {
    "Web": {
      "ProfileSync": {
        "Enabled": true,
        "ClaimToGraphProperty": {
          // given_name -> givenName and family_name -> surname are always included.
          // Add your custom-attribute claims here:
          "extension_<appId>_country": "country",
          "extension_<appId>_company": "companyName"
        }
      }
    }
  }
}

On a successful sign-in, every mapped claim present on the token is PATCHed onto the user via the standard v1.0 PATCH /users/{id}. Notes:

• Supported target properties (the map's values, case-insensitive): givenName, surname, displayName, jobTitle, department, companyName, city, state, country, postalCode, streetAddress. Unknown targets are skipped (logged), so a typo can't break sign-in.
• Best-effort: a Graph PATCH failure is logged and swallowed — it never blocks a sign-in the customer already completed.
• Claims are the source of truth on each sign-in while enabled: a mapped property is overwritten from the token whenever the claim is present. Properties with no corresponding claim are left untouched.
• Custom directory extension properties (schema-qualified) are out of scope here — they need the schema extension registered first. This path writes only the standard User properties listed above.

Why not a user-flow admin page? Listing / editing user flows + their attributes lives in the beta Microsoft Graph API; this adapter stays on the stable v1.0 SDK. Manage the flows themselves in the Entra portal; VisuAuth maps the resulting claims.

* Required unless the app registration is a public client.

Two app registrations explained

Entra External deployments typically split admin and end-user flows across two separate registered apps in the same tenant:

The admin app needs Graph User.ReadWrite.All + friends with admin consent. The end-user app needs a redirect URI configured for your domain (e.g. https://app.example.com/signin-oidc) and the OIDC scopes (openid profile email).

Sharing a single app between the two flows is technically possible but adds security surface (the same client secret signs both admin Graph requests and end-user redirects). The Microsoft documentation recommends keeping them separate.

How sign-in works end-to-end

1. User visits /visuauth/login — VisuAuth's End-user page reads IExternalLoginFlow.GetProvidersAsync(). With this package wired, that returns one provider: Sign in with Microsoft.
2. User clicks the button. The form POSTs to /visuauth/external-login/start with scheme=MicrosoftEntraExternal.
3. StartModel issues ChallengeAsync against the registered OIDC handler. Microsoft.Identity.Web redirects the user to {tenant}.ciamlogin.com/{tenant-id}/v2.0/authorize.
4. User signs in on Microsoft's hosted page.
5. Microsoft posts back to /signin-oidc. Microsoft.Identity.Web validates the id_token, writes the Cookies scheme cookie, redirects to /visuauth/external-login/callback.
6. The Callback page calls _externalLogin.CompleteSignInAsync(strategy). This package's implementation reads the authenticated principal's oid claim, verifies the user exists in Graph via IUserStore.GetAsync, and returns Success with the directory id.
7. Callback page redirects to returnUrl (or /).

The user is now signed in — HttpContext.User.Identity.IsAuthenticated == true, claims include their Graph object id, email, name.

First-time strategy

VisuAuth's ExternalLoginOptions.FirstTimeStrategy (defaults to AutoCreate) controls what happens on the very first sign-in when the local store doesn't yet have the user. For Entra External:

In practice, leave the default. v0.3 PR D adds the signup user-flow integration that lets the consumer point the "Sign in with Microsoft" button at a sign-up flow rather than a sign-in flow when they want self-service registration.

Known limitations

Sample

samples/Sample.EntraExternalWebApp wires this package — see its Program.cs for end-to-end setup including the VisuAuth:EntraExternal:Web configuration section in appsettings.json.