VisuAuth.EntraExternal 0.2.0

VisuAuth.EntraExternal

Microsoft Entra External ID (formerly Azure AD B2C) adapter for VisuAuth. Targets customer-facing tenants where end users sign up and sign in with email + password local accounts (and optionally federated social providers) managed by Microsoft.

The admin surface VisuAuth exposes is the same /visuauth/admin/* pages the Workforce adapter and the Identity adapter feed. Capability flags swap the experience automatically:

• Login — the email + password form on /visuauth/login disappears in favour of a "Sign in with Microsoft" hint, because SupportsLocalLogin = false. The actual hosted login lives at {tenant}.ciamlogin.com and is wired in the consumer's app via Microsoft.Identity.Web (see v0.3 PR-C).
• Admin — /visuauth/admin/users lists customers live from Microsoft Graph. Create / disable / 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. Shares the underlying Graph wiring with VisuAuth.Entra via the VisuAuth.EntraCore package.

When to pick this adapter over VisuAuth.Entra. Workforce = employees of your company (Entra ID). External = customers of your SaaS who sign up themselves (Entra External ID / customer identity). If you'd be issuing invite links via email to colleagues, you want Workforce. If users land on a signup page and self-onboard, you want External.

Table of contents

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

Install

dotnet add package VisuAuth
dotnet add package VisuAuth.EntraExternal

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

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

using VisuAuth;
using VisuAuth.EntraExternal.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

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

builder.Services.AddVisuAuthEntraExternal(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 External adapter declares:

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

Set up an Entra External tenant + app registration

Walkthrough that takes a fresh Microsoft account to a working VisuAuth.EntraExternal in ~25 minutes. Entra External tenants are free to create (unlike Workforce after the 2024 policy change), making this the lowest-friction path to try VisuAuth against a real Graph backend.

Step 1 — Create the External tenant

1. Browse to entra.microsoft.com, sign in.
2. Manage tenants (in the home page Shortcuts strip) → + Create.
3. Pick External → Continue.
4. Fill the form (Tenant name, Initial domain name, Location) and Review + create. The initial domain becomes {name}.onmicrosoft.com — that's your TenantDomain value (write it down).
5. After ~30 seconds, Go to tenant (or switch via the top-right account menu).
6. From the tenant Overview card, copy the Tenant ID (GUID) — that's your TenantId config value.

Step 2 — Register the management app

1. Sidebar Identity → Applications → App registrations → + New registration.
2. Name (e.g. VisuAuth Admin), Accounts in this organizational directory only, leave Redirect URI blank for now (PR-C will add an OIDC redirect for the customer-facing app — this management app doesn't need one).
3. After registering, copy from the Overview blade:
   • Application (client) ID → goes into VisuAuth:EntraExternal:ClientId.

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. 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 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.

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.

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

Dev:

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

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

VisuAuth__EntraExternal__TenantId
VisuAuth__EntraExternal__ClientId
VisuAuth__EntraExternal__ClientSecret
VisuAuth__EntraExternal__TenantDomain

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

Configure VisuAuth.EntraExternal in your app

EntraExternalOptions (everything bound from VisuAuth:EntraExternal):

Two AddVisuAuthEntraExternal overloads — pick whichever fits the wiring style:

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

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

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

Operations supported

IUserStore (admin user management)

IRoleStore (app role management)

Identical surface to the Workforce adapter — app roles are tenant-family-agnostic in Graph. See the Workforce adapter README for the per-method table.

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. The real customer-facing OIDC redirect lands in v0.3 PR-C via Microsoft.Identity.Web.

Known limitations

Troubleshooting

Samples

samples/Sample.EntraExternalWebApp — minimal External-only reference

A ~30-line Program.cs showing the shortest path to a working VisuAuth admin against Microsoft Graph for an External tenant. No Identity / SQLite / JWT / OAuth wire-up. Mirrors samples/Sample.EntraWebApp (the Workforce equivalent) for easy comparison.

cd samples/Sample.EntraExternalWebApp
dotnet run

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