VisuAuth.Entra 0.2.0

VisuAuth.Entra

Microsoft Entra ID (Workforce) adapter for VisuAuth. Plugs into the same admin UI and end-user pages the rest of VisuAuth ships — capability flags swap the experience automatically:

• Login — the email + password form on /visuauth/login disappears and the page becomes a "Sign in with Microsoft" hint, because SupportsLocalLogin = false.
• Admin — /visuauth/admin/users lists the directory live from Microsoft Graph. Create / update / delete / reset password / revoke sessions all hit Graph endpoints under the consumer's app-only credentials.
• Roles — /visuauth/admin/roles surfaces the app roles declared in your registered app's manifest. Assign / remove via /users/{id}/appRoleAssignments.

Built against Microsoft.Graph 5.x with Azure.Identity ClientSecretCredential for the app-only flow.

Scope. v0.2 covers Entra ID Workforce tenants. Entra External ID (the B2C successor) is on the v0.3 roadmap (VisuAuth.EntraExternal) — admin CRUD shares the Graph endpoints, but the signup / signin flows and the user-shape (identities, user attributes) differ enough to deserve a dedicated adapter.

Table of contents

1. Install
2. What this adapter does and doesn't do (capabilities)
3. Set up an Entra tenant + app registration
4. Configure VisuAuth.Entra in your app
5. Multi-domain (verified custom domain)
6. Operations supported
7. Known limitations
8. Troubleshooting
9. Samples

Install

dotnet add package VisuAuth
dotnet add package VisuAuth.Entra

VisuAuth is the meta-package (Admin UI + End-user UI + Abstractions). VisuAuth.Entra brings Microsoft.Graph + Azure.Identity. Identity-adapter consumers don't pay this weight unless they reference VisuAuth.Entra.

Minimal Program.cs for an Entra-only app (the one in samples/Sample.EntraWebApp is ~30 lines):

using VisuAuth;
using VisuAuth.Entra.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddVisuAuthEntra(builder.Configuration);

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

No AddIdentity, no AddDbContext, no JWT issuer, no OAuth providers. Everything Identity-shaped is opt-in via the other adapter.

What this adapter does and doesn't do (capabilities)

UserBackendCapabilities drive every conditional render in the UI. The Entra adapter declares:

Every flag above is a real decision point in the UI — flipping one reshapes what the admin sees.

Set up an Entra tenant + app registration

Walkthrough that takes a fresh Microsoft account to a working VisuAuth.Entra in ~20 minutes.

Step 1 — Tenant (skip if you already have one)

Heads-up — Microsoft policy change (2024). Creating a new Workforce tenant now requires a paid license (M365 Business / Entra ID P1+). Tenants created before this change are grandfathered. Free options today: Entra External (different feature set — see "Scope" above) and your work-or-school account's existing tenant.

1. Browse to entra.microsoft.com, sign in.
2. Manage tenants (in the home page Shortcuts strip) → + Create.
3. Pick Workforce → Continue.
4. Fill the form (Organization name, Initial domain name, Country) and Create.
5. Switch into the new tenant when prompted; copy the Tenant ID (GUID) from the home card.

Step 2 — App registration

1. Sidebar Entra ID → App registrations → + New registration.
2. Name (e.g. VisuAuth Sample), Accounts in this organizational directory only, leave Redirect URI blank.
3. After registering, copy from the Overview blade:
   • Application (client) ID → goes into VisuAuth:Entra:ClientId.
   • Directory (tenant) ID → confirms the value from Step 1.

Step 3 — Microsoft Graph permissions

1. App's sidebar → API permissions → + Add a permission → Microsoft Graph → Application permissions (NOT Delegated).
2. Add all four:
   • User.Read.All
   • User.ReadWrite.All
   • AppRoleAssignment.ReadWrite.All
   • Application.Read.All
3. Optional, for the multi-domain Create-User dropdown:
   • Domain.Read.All — lets /admin/users/new offer a dropdown of the tenant's verified domains. Skip it on a single-domain tenant; without it the form falls back to the locked suffix.
4. Grant admin consent for {your tenant} at the top of the permissions table. Each row should show a green ✓ "Granted" check.

Forgetting "Grant admin consent" is the single most common setup mistake — without it Graph returns Authorization_RequestDenied on every call.

Step 4 — Client secret

1. App's sidebar → Certificates & secrets → + New client secret.
2. Description (any), Expires 180 or 365 days for dev. Add.
3. Immediately copy the Value column (not Secret ID) — it's only shown once, after that it stays masked. Lose it = delete and create a new one.

Step 5 — (Optional) Declare app roles

Skip if you don't need the /admin/roles page populated. Otherwise:

1. App's sidebar → App roles → + Create app role.
2. Display name Admin, value admin, Allowed member types: Users/Groups, Enabled.
3. Repeat for Editor or whatever roles your app needs.

App roles are declared statically in the app manifest — VisuAuth.Entra surfaces them read-only on /admin/roles and assigns/removes them via Graph at runtime, but Create/Rename/Delete have to happen in the portal.

Step 6 — Populate user-secrets (dev) or environment (prod)

Dev:

cd path/to/your/app
dotnet user-secrets set "VisuAuth:Entra:TenantId"     "<directory-guid>"
dotnet user-secrets set "VisuAuth:Entra:ClientId"     "<application-guid>"
dotnet user-secrets set "VisuAuth:Entra:ClientSecret" "<value-from-step-4>"

Production / containerised — use env vars with double-underscore (ASP.NET Core convention):

VisuAuth__Entra__TenantId
VisuAuth__Entra__ClientId
VisuAuth__Entra__ClientSecret

Or any other IConfiguration source (Key Vault, AWS Secrets Manager, etc.) under the section name VisuAuth:Entra.

That's it — dotnet run, browse /visuauth/admin/users, and you'll see the tenant's directory.

Configure VisuAuth.Entra in your app

EntraOptions (everything bound from VisuAuth:Entra):

Two AddVisuAuthEntra overloads — pick whichever fits the wiring style:

// Lambda — best when values come from code / env vars
builder.Services.AddVisuAuthEntra(o =>
{
    o.TenantId = builder.Configuration["VisuAuth:Entra:TenantId"]!;
    o.ClientId = builder.Configuration["VisuAuth:Entra:ClientId"]!;
    o.ClientSecret = builder.Configuration["VisuAuth:Entra:ClientSecret"]!;
});

// Configuration section — best with appsettings / user-secrets / Key Vault
builder.Services.AddVisuAuthEntra(builder.Configuration);

Both register the same service graph (TryAdd, so a consumer-registered test double wins): IUserStore → EntraUserStore, IRoleStore → EntraRoleStore, IAuthenticationFlow → EntraAuthenticationFlow, plus stub IAuditWriter / IJwtIssuer / ITenantContext / IExternalLoginFlow so the End-user UI can resolve without Identity wired alongside.

Edit settings from the admin UI (optional)

By default the Entra settings are read once at startup from IConfiguration / the configure lambda. To let an operator edit them at runtime from /visuauth/admin/entra-config instead, opt in:

// Needs a metadata DbContext (the VisuAuthAdapterConfigs table) — register one
// and surface it as IVisuAuthMetadataDbContext, then:
builder.Services.AddVisuAuthAdapterConfigStore();   // from VisuAuth.Identity
builder.Services.AddVisuAuthEntraDbConfig();         // from VisuAuth.Entra

Stored values overlay on top of the code/appsettings values (DB wins per key; keys with no override keep the code value), the ClientSecret is encrypted at rest via ASP.NET Core Data Protection, and a save takes effect on the next Graph call without restarting — the client is rebuilt when the effective options change. Without this opt-in the page stays hidden and the adapter reads its configuration exactly as before.

Multi-domain (verified custom domain)

Workforce tenants ship with one default domain ({tenant}.onmicrosoft.com). You can verify additional custom domains and create users under any of them. The Create-User UX picks one as the "default suggestion" via DefaultEmailDomain.

Add a custom domain

1. In the target tenant: Identity → Settings → Domain names → + Add custom domain.
2. Type the domain (e.g. acme.com) → Add domain.
3. Entra shows a TXT record. Copy the MS=ms… value.
4. In your DNS provider, add a TXT record:
   • Cloudflare: DNS → Records → + Add record → Type TXT, Name @, Content MS=..., Proxy DNS-only. Propagates in seconds.
   • Route53 / GoDaddy / Registro.br / others: add a TXT record at the apex (@) with the MS=... value. Propagation is usually 5-30 minutes.
5. Verify propagation: nslookup -type=TXT acme.com 1.1.1.1 should echo the MS=... value.
6. Back in Entra: Verify. Status flips to ✅ Verified.

Don't mark the custom domain as Primary unless you have a reason — keeping the *.onmicrosoft.com slug as Primary avoids subtle Graph URL changes.

Tell VisuAuth which domain to suggest

dotnet user-secrets set "VisuAuth:Entra:DefaultEmailDomain" "acme.com"

After restart, /admin/users/new renders a split input: free text for the local part, @acme.com locked as a non-editable suffix. The PageModel concatenates before calling CreateAsync.

To create users in a non-default verified domain, pass the full email through the API (CreateUserCommand.Email = "cto@subsidiary.com"); the PageModel skips the suffix concatenation when the value already contains @.

To go back to a free-text email input, remove the option (dotnet user-secrets remove "VisuAuth:Entra:DefaultEmailDomain").

Automatic domain dropdown

When the tenant has two or more verified domains, the Create-User form upgrades the locked suffix to a dropdown automatically — no extra configuration. The adapter registers an IEmailDomainSource (EntraEmailDomainSource) that reads the verified domains from Graph /domains (primary first, cached for the process lifetime) and the page renders a local-part input plus a domain <select>. The selected domain is validated server-side against the offered list before the address is assembled, so a tampered POST can't inject an unverified domain. A single-domain tenant keeps the locked-suffix UX above. Requires the Domain.Read.All application permission; without it the fetch fails quietly and the form falls back to the single suffix.

Operations supported

IUserStore (admin user management)

IRoleStore (app role management)

IAuthenticationFlow (end-user surface — capability-driven)

Every method returns either RedirectToExternalProvider (SignInWithPasswordAsync) or a UserResult.Failure with the "use Microsoft" message. The Login page hides the password form on its own via SupportsLocalLogin = false; this flow exists as a safety net for direct-API / CLI callers.

Known limitations

Troubleshooting

Samples

Two samples ship in the repo; both share the same UserSecretsId so dev secrets need to be set only once.

samples/Sample.WebApp — dual-backend toggle

The "everything" sample. Defaults to the Identity adapter against local SQLite. Set VISUAUTH_BACKEND=entra (or VisuAuth:Backend=entra in config) to flip to the Entra adapter — same admin UI, different store underneath. Used to demonstrate the capability flag system end-to-end.

cd samples/Sample.WebApp
$env:VISUAUTH_BACKEND="entra"
dotnet run

samples/Sample.EntraWebApp — minimal Entra-only reference

A ~30-line Program.cs showing the shortest path to a working VisuAuth admin against Microsoft Graph. No Identity / SQLite / JWT / OAuth wire-up. Good template for an app that only ever uses Entra.

cd samples/Sample.EntraWebApp
dotnet run

Lands on http://localhost:5240/visuauth/admin (the launch profile opens the browser there directly).