feat(portal-beheer): beheer portal + read-only catalogus viewer (closes #130) (#133)
CI / build (push) Successful in 4m31s
CI / lint (push) Successful in 4m48s
CI / unit (push) Successful in 1m50s
CI / frontend (push) Successful in 4m44s
CI / mutation (push) Successful in 7m12s
CI / verify-stack (push) Canceled after 0s

## What & why

S-15a, the first of the S-15 (#16) split. A new **beheer** portal (medewerker realm, like behandel) shows the ZTC catalogus — the published zaaktypen — **read-only**. A beheerder logs in and sees the seeded BIG-REGISTRATIE zaaktype.

Closes #130

### The vertical

portal → BFF `GET /beheer/catalogi/zaaktypen` (medewerker realm + `beheerder` role) → ACL `GET /catalogi/zaaktypen` → ZGW Catalogi API.

- **ACL**: new read-only `GET /catalogi/zaaktypen` listing published zaaktypen (reuses the ADR-0021 Catalogi client; public-safe `identificatie`/`omschrijving`).
- **BFF**: new typed `IAclClient` + `Downstream:Acl:BaseUrl`, and `GET /beheer/catalogi/zaaktypen` behind a new `beheerder` policy (reuses the medewerker bearer scheme + realm-role lifting). OpenAPI spec + generated Angular client regenerated.
- **Keycloak**: `beheerder` realm role + `bram-beheerder` test user in the medewerker realm.
- **Frontend**: new `apps/beheer` Angular app (copied from behandel) with a read-only catalogus page; `SECURE_API_ROUTES=['/beheer/']`.
- **Infra**: `beheer` compose service (port 8143), added to `WAIT_SVCS` + CI log-dump; a Playwright e2e (beheerder login → catalogus shows BIG-REGISTRATIE).

### New boundary → ADR-0025

The BFF now reaches the **ACL directly** for the catalogus read — a new service-to-service edge (§14). The catalogus is neither a domain nor a projection concern, and §8.1 means only the ACL may read ZGW; routing through the domain would pollute it with a non-domain passthrough. §8.1/§8.3 stay intact. Recorded in **ADR-0025**.

## Definition of Done

- [x] Failing test committed before each implementation (red→green per layer: ACL, BFF, frontend).
- [x] Conventional Commits referencing #130.
- [ ] CI green — pending Gitea Actions run.
- [x] `docker compose up` brings up `beheer` (health-gated in `WAIT_SVCS`).
- [x] Docs — ADR-0025 + demo-script S-15a note.
- [x] Demo note in `docs/demo-script.md`.

## Verified locally

lint (`dotnet format`) ✓ · .NET unit (Acl 57 / Big 152 / EventSubscriber 19 / Bff 40) ✓ · frontend lint+test (8 projects) ✓ · frontend build (4 apps) ✓. Mutation ratchet: added a gateway unit test for the new `ListZaaktypenAsync` mapping so the ACL score holds. verify-stack (compose smoke + e2e) runs in CI.

## Notes for reviewers

- The BFF drops the ZGW URL from `BeheerZaaktype` (public-safe: identificatie + omschrijving only).
- The catalogus e2e asserts on the stable seeded `BIG-REGISTRATIE` (not a per-test reference), safe on the shared verify stack.
- Follow-ups: **S-15b** (#131) default-fill CRUD, **S-15c** (#132) medewerker-realm MFA.

🤖 Generated with [Claude Code](https://claude.com/claude-code)Reviewed-on: #133
This commit was merged in pull request #133.
This commit is contained in:
not
2026-07-24 11:08:17 +00:00
parent d5dfbdc0b2
commit 4698c869f3
47 changed files with 1008 additions and 11 deletions
+6
View File
@@ -85,6 +85,12 @@ app.MapPost("/documenten", async (StoreDocumentRequest body, AclService acl, Can
return Results.Ok(new { informatieobjectUrl = url.ToString() });
});
// List the published zaaktypen — the read-only catalogus the beheer portal shows (S-15a). The BFF
// proxies this behind medewerker-realm + beheerder authorization; the ACL trusts its callers (§8.3)
// and is the only code allowed to read the ZGW Catalogi API (§8.1).
app.MapGet("/catalogi/zaaktypen", async (AclService acl, CancellationToken ct) =>
Results.Ok(await acl.ListZaaktypenAsync(ct)));
app.Run();
public sealed record OpenZaakRequest(string Bsn, string Reference);
@@ -42,6 +42,11 @@ public sealed class AclService(IZaakGateway gateway, AclDefaults defaults, IZaak
await gateway.SetZaakToCancellationStatusAsync(zaakUrl, await catalog.GetZaaktypeUrlAsync(ct), clock.Today, ct);
}
/// <summary>The published zaaktypen, for the beheer catalogus viewer (S-15a). Read-only passthrough:
/// no default-fill, the ACL is simply the only code allowed to read ZGW (§8.1).</summary>
public Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default) =>
gateway.ListZaaktypenAsync(ct);
/// <summary>The zaak's reference (its ZGW identificatie), for the read projection (#78).</summary>
public Task<string> GetZaakReferenceAsync(Uri zaakUrl, CancellationToken ct = default)
{
@@ -40,4 +40,8 @@ public interface IZaakGateway
/// <summary>Resolve the URL of the published informatieobjecttype with the given
/// <paramref name="omschrijving"/> from the Catalogi API (S-27). Throws if none matches.</summary>
Task<Uri> ResolveInformatieobjecttypeUrlAsync(string omschrijving, CancellationToken ct = default);
/// <summary>List the published zaaktypen from the Catalogi API — the read-only catalogus the beheer
/// portal shows (S-15a). The ACL is the only code allowed to read ZGW (§8.1).</summary>
Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default);
}
@@ -0,0 +1,6 @@
namespace Acl.Application;
/// <summary>A published zaaktype as the beheer catalogus viewer shows it (S-15a). Public-safe: the
/// business <see cref="Identificatie"/> + human <see cref="Omschrijving"/> and the ZGW <see cref="Url"/>
/// (the URL is the ACL's own reference, not shown to end users).</summary>
public sealed record ZaaktypeSummary(string Identificatie, string Omschrijving, Uri Url);
@@ -170,6 +170,16 @@ public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) :
return new Uri(match.Url);
}
public async Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default)
{
// Only published zaaktypen (status=definitief excludes concepts) — the read-only catalogus the
// beheer portal shows. Public-safe fields only.
var page = await GetAsync<ZaaktypePage>("/catalogi/api/v1/zaaktypen?status=definitief", "zaaktypen", ct);
return (page.Results ?? [])
.Select(z => new ZaaktypeSummary(z.Identificatie ?? "", z.Omschrijving ?? "", new Uri(z.Url)))
.ToList();
}
// GETs an absolute-by-path ZGW resource with auth (no CRS — catalogi is not a geo API).
private async Task<T> GetAsync<T>(string pathAndQuery, string label, CancellationToken ct)
{
@@ -346,7 +356,8 @@ public sealed class OpenZaakGateway(HttpClient http, OpenZaakOptions options) :
private sealed record ZaaktypeDto(
[property: JsonPropertyName("url")] string Url,
[property: JsonPropertyName("identificatie")] string? Identificatie);
[property: JsonPropertyName("identificatie")] string? Identificatie,
[property: JsonPropertyName("omschrijving")] string? Omschrijving = null);
private sealed record InformatieobjecttypePage(
[property: JsonPropertyName("results")] IReadOnlyList<InformatieobjecttypeDto>? Results);
+22
View File
@@ -65,6 +65,14 @@ public class AclServiceTests
ResolvedByOmschrijving = omschrijving;
return Task.FromResult(ResolvedInformatieobjecttype);
}
public IReadOnlyList<ZaaktypeSummary> Zaaktypen { get; } =
[
new("BIG-REGISTRATIE", "BIG-registratie", new Uri("http://openzaak/catalogi/api/v1/zaaktypen/big")),
];
public Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default) =>
Task.FromResult(Zaaktypen);
}
private static AclDefaults Defaults() => new()
@@ -225,4 +233,18 @@ public class AclServiceTests
await Assert.ThrowsAsync<ArgumentNullException>(() => service.GetZaakReferenceAsync(null!));
Assert.Null(gateway.ReadReferenceFor);
}
[Fact]
public async Task Listing_zaaktypen_returns_the_gateways_published_zaaktypen(/* S-15a */)
{
var gateway = new FakeGateway();
var service = ServiceWith(gateway, Defaults(), new DateOnly(2026, 6, 4));
var zaaktypen = await service.ListZaaktypenAsync();
var only = Assert.Single(zaaktypen);
Assert.Equal("BIG-REGISTRATIE", only.Identificatie);
Assert.Equal("BIG-registratie", only.Omschrijving);
Assert.Equal(new Uri("http://openzaak/catalogi/api/v1/zaaktypen/big"), only.Url);
}
}
@@ -824,4 +824,51 @@ public class OpenZaakGatewayTests
await Assert.ThrowsAnyAsync<ArgumentException>(() => Gateway(handler).ResolveZaaktypeUrlAsync(" "));
await Assert.ThrowsAnyAsync<ArgumentException>(() => Gateway(handler).ResolveInformatieobjecttypeUrlAsync(" "));
}
[Fact]
public async Task Listing_zaaktypen_queries_published_zaaktypen_and_maps_them(/* S-15a */)
{
HttpRequestMessage? seen = null;
var handler = new StubHandler(req =>
{
seen = req;
const string json = """
{"results":[
{"url":"http://openzaak/catalogi/api/v1/zaaktypen/big","identificatie":"BIG-REGISTRATIE","omschrijving":"BIG-registratie"},
{"url":"http://openzaak/catalogi/api/v1/zaaktypen/her","identificatie":"BIG-HERREGISTRATIE","omschrijving":"BIG-herregistratie"}
]}
""";
return Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent(json, Encoding.UTF8, "application/json"),
});
});
var zaaktypen = await Gateway(handler).ListZaaktypenAsync();
// Only the published zaaktypen collection is queried (status=definitief excludes concepts).
Assert.Contains("/catalogi/api/v1/zaaktypen", seen!.RequestUri!.ToString());
Assert.Contains("status=definitief", seen.RequestUri!.ToString());
// Authenticated like the other catalogi reads.
Assert.Equal("Bearer", seen.Headers.Authorization!.Scheme);
// Each result maps to a public-safe summary (identificatie + omschrijving + url).
Assert.Equal(2, zaaktypen.Count);
Assert.Equal("BIG-REGISTRATIE", zaaktypen[0].Identificatie);
Assert.Equal("BIG-registratie", zaaktypen[0].Omschrijving);
Assert.Equal(new Uri("http://openzaak/catalogi/api/v1/zaaktypen/big"), zaaktypen[0].Url);
Assert.Equal("BIG-HERREGISTRATIE", zaaktypen[1].Identificatie);
}
[Fact]
public async Task Listing_zaaktypen_returns_empty_when_the_catalogus_has_none()
{
var handler = new StubHandler(_ => Task.FromResult(new HttpResponseMessage(HttpStatusCode.OK)
{
Content = new StringContent("""{"results":[]}""", Encoding.UTF8, "application/json"),
}));
var zaaktypen = await Gateway(handler).ListZaaktypenAsync();
Assert.Empty(zaaktypen);
}
}
@@ -36,6 +36,7 @@ public class ZaaktypeCatalogTests
public Task SetZaakToCancellationStatusAsync(Uri z, Uri zt, DateOnly d, CancellationToken ct = default) => throw new NotSupportedException();
public Task<string> GetZaakIdentificatieAsync(Uri z, CancellationToken ct = default) => throw new NotSupportedException();
public Task<Uri> StoreDocumentAsync(DocumentRequest r, CancellationToken ct = default) => throw new NotSupportedException();
public Task<IReadOnlyList<ZaaktypeSummary>> ListZaaktypenAsync(CancellationToken ct = default) => throw new NotSupportedException();
}
private static AclDefaults Defaults() => new()
+21
View File
@@ -54,6 +54,19 @@ public interface IProjectionClient
Task<IReadOnlyList<ProjectionEntry>> GetRegisterAsync(CancellationToken ct = default);
}
/// <summary>A published zaaktype as the beheer catalogus viewer shows it (S-15a): the business
/// <c>Identificatie</c> + human <c>Omschrijving</c>. The ZGW URL the ACL also returns is dropped — an
/// internal reference, not shown in the portal.</summary>
public sealed record BeheerZaaktype(string Identificatie, string Omschrijving);
/// <summary>Port to the ACL for read-only catalogus queries (beheer portal, S-15a). The BFF reaches the
/// ACL directly for this read: the catalogus isn't a domain concern, and the ACL is the only code
/// allowed to read the ZGW Catalogi API (§8.1, ADR-0025).</summary>
public interface IAclClient
{
Task<IReadOnlyList<BeheerZaaktype>> GetZaaktypenAsync(CancellationToken ct = default);
}
/// <summary>Calls the Domain Service's <c>POST /registrations</c>.</summary>
public sealed class DomainClient(HttpClient http) : IDomainClient
{
@@ -121,3 +134,11 @@ public sealed class ProjectionClient(HttpClient http) : IProjectionClient
public async Task<IReadOnlyList<ProjectionEntry>> GetRegisterAsync(CancellationToken ct = default)
=> await http.GetFromJsonAsync<List<ProjectionEntry>>("register", ct) ?? [];
}
/// <summary>Calls the ACL's <c>GET /catalogi/zaaktypen</c> (S-15a). The ACL also returns each zaaktype's
/// ZGW URL; deserializing into <see cref="BeheerZaaktype"/> keeps only the public-safe fields.</summary>
public sealed class AclClient(HttpClient http) : IAclClient
{
public async Task<IReadOnlyList<BeheerZaaktype>> GetZaaktypenAsync(CancellationToken ct = default)
=> await http.GetFromJsonAsync<List<BeheerZaaktype>>("catalogi/zaaktypen", ct) ?? [];
}
+33 -2
View File
@@ -40,6 +40,10 @@ var domainBaseUrl = builder.Configuration["Downstream:Domain:BaseUrl"]
?? throw new InvalidOperationException("Missing configuration 'Downstream:Domain:BaseUrl'");
var projectionBaseUrl = builder.Configuration["Downstream:Projection:BaseUrl"]
?? throw new InvalidOperationException("Missing configuration 'Downstream:Projection:BaseUrl'");
// The beheer portal's read-only catalogus view reaches the ACL directly (ADR-0025): the catalogus is
// not a domain concern, and only the ACL may read the ZGW Catalogi API (§8.1).
var aclBaseUrl = builder.Configuration["Downstream:Acl:BaseUrl"]
?? throw new InvalidOperationException("Missing configuration 'Downstream:Acl:BaseUrl'");
// Validate Keycloak-issued tokens (ADR-0010). Audience validation is off for the walking skeleton —
// Keycloak's audience mapping is a later hardening; signature/issuer/expiry are validated.
@@ -67,14 +71,24 @@ builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
};
});
builder.Services.AddAuthorization(options =>
{
options.AddPolicy(BehandelAuth.Policy, policy => policy
.AddAuthenticationSchemes(BehandelAuth.Scheme)
.RequireAuthenticatedUser()
.RequireRole(BehandelAuth.BehandelaarRole)));
.RequireRole(BehandelAuth.BehandelaarRole));
// Beheer endpoints reuse the medewerker scheme (same realm, same realm-role lifting) but require the
// beheerder role rather than behandelaar (S-15a).
options.AddPolicy(BeheerAuth.Policy, policy => policy
.AddAuthenticationSchemes(BehandelAuth.Scheme)
.RequireAuthenticatedUser()
.RequireRole(BeheerAuth.BeheerderRole));
});
// The BFF is the portals' only backend; it fans out to the domain and projection (§8.3).
// The BFF is the portals' only backend; it fans out to the domain and projection (§8.3), and reaches
// the ACL for the beheer catalogus read (ADR-0025).
builder.Services.AddHttpClient<IDomainClient, DomainClient>(c => c.BaseAddress = new Uri(domainBaseUrl));
builder.Services.AddHttpClient<IProjectionClient, ProjectionClient>(c => c.BaseAddress = new Uri(projectionBaseUrl));
builder.Services.AddHttpClient<IAclClient, AclClient>(c => c.BaseAddress = new Uri(aclBaseUrl));
builder.Services.AddHealthChecks();
// Clear the auto-populated `servers` block so the committed spec is stable regardless of the host
@@ -205,6 +219,15 @@ app.MapPost("/behandel/registrations/{id}/decide",
.Produces(StatusCodes.Status401Unauthorized)
.Produces(StatusCodes.Status403Forbidden);
// Beheer catalogus viewer (S-15a): the published zaaktypen, read-only. Reached only with a medewerker-
// realm token carrying the beheerder role; the BFF proxies the ACL's read (ADR-0025). Public-safe.
app.MapGet("/beheer/catalogi/zaaktypen", async (IAclClient acl, CancellationToken ct) =>
Results.Ok(await acl.GetZaaktypenAsync(ct)))
.RequireAuthorization(BeheerAuth.Policy)
.Produces<IReadOnlyList<BeheerZaaktype>>(StatusCodes.Status200OK)
.Produces(StatusCodes.Status401Unauthorized)
.Produces(StatusCodes.Status403Forbidden);
app.Run();
/// <summary>The behandelaar's decision on a registration.</summary>
@@ -257,5 +280,13 @@ internal static class BehandelAuth
private sealed record RealmAccess([property: JsonPropertyName("roles")] string[] Roles);
}
// Beheer (medewerker-realm) authorization wiring (S-15a). Reuses the "medewerker" bearer scheme
// (BehandelAuth.Scheme) and its realm-role lifting; only the required role differs.
internal static class BeheerAuth
{
public const string Policy = "beheerder";
public const string BeheerderRole = "beheerder";
}
// Exposed so the test host (WebApplicationFactory<Program>) can boot the app.
public partial class Program;
+2 -1
View File
@@ -12,6 +12,7 @@
},
"Downstream": {
"Domain": { "BaseUrl": "http://localhost:8130/" },
"Projection": { "BaseUrl": "http://localhost:8120/" }
"Projection": { "BaseUrl": "http://localhost:8120/" },
"Acl": { "BaseUrl": "http://localhost:8100/" }
}
}
@@ -0,0 +1,57 @@
using System.Net;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using Bff.Api;
namespace Bff.Tests;
/// <summary>
/// The beheer catalogus viewer (S-15a): reached only with a medewerker-realm token carrying the
/// <c>beheerder</c> role. A missing token is 401; an authenticated medewerker without the role (e.g.
/// a plain behandelaar) is 403; a beheerder gets the read-only list of published zaaktypen.
/// </summary>
public class BeheerEndpointTests
{
private static HttpRequestMessage Zaaktypen(string? bearer)
{
var request = new HttpRequestMessage(HttpMethod.Get, "/beheer/catalogi/zaaktypen");
if (bearer is not null)
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", bearer);
return request;
}
[Fact]
public async Task Rejects_the_catalogus_without_a_token()
{
using var factory = new BffFactory();
var response = await factory.CreateClient().SendAsync(Zaaktypen(bearer: null));
Assert.Equal(HttpStatusCode.Unauthorized, response.StatusCode);
}
[Fact]
public async Task Rejects_a_medewerker_without_the_beheerder_role()
{
using var factory = new BffFactory();
var response = await factory.CreateClient().SendAsync(Zaaktypen(TestTokens.Medewerker("behandelaar")));
Assert.Equal(HttpStatusCode.Forbidden, response.StatusCode);
}
[Fact]
public async Task Serves_the_published_zaaktypen_to_a_beheerder()
{
using var factory = new BffFactory();
factory.Acl.Zaaktypen.Add(new BeheerZaaktype("BIG-REGISTRATIE", "BIG-registratie"));
var response = await factory.CreateClient().SendAsync(Zaaktypen(TestTokens.Medewerker("beheerder")));
Assert.Equal(HttpStatusCode.OK, response.StatusCode);
var items = await response.Content.ReadFromJsonAsync<List<BeheerZaaktype>>();
var item = Assert.Single(items!);
Assert.Equal("BIG-REGISTRATIE", item.Identificatie);
Assert.Equal("BIG-registratie", item.Omschrijving);
}
}
+12
View File
@@ -23,6 +23,7 @@ internal sealed class BffFactory : WebApplicationFactory<Program>
public FakeDomainClient Domain { get; } = new();
public FakeProjectionClient Projection { get; } = new();
public FakeAclClient Acl { get; } = new();
private static void ValidateWithTestKey(IServiceCollection services, string scheme) =>
services.Configure<JwtBearerOptions>(scheme, options =>
@@ -54,11 +55,13 @@ internal sealed class BffFactory : WebApplicationFactory<Program>
builder.UseSetting("Keycloak:MedewerkerAuthority", "https://keycloak.invalid/realms/medewerker");
builder.UseSetting("Downstream:Domain:BaseUrl", "http://domain.invalid/");
builder.UseSetting("Downstream:Projection:BaseUrl", "http://projection.invalid/");
builder.UseSetting("Downstream:Acl:BaseUrl", "http://acl.invalid/");
builder.ConfigureTestServices(services =>
{
services.AddSingleton<IDomainClient>(Domain);
services.AddSingleton<IProjectionClient>(Projection);
services.AddSingleton<IAclClient>(Acl);
// Both realms validate locally against the test key (no live Keycloak). The medewerker
// scheme keeps its OnTokenValidated role-lifting from Program.cs — only the validation
@@ -138,3 +141,12 @@ internal sealed class FakeProjectionClient : IProjectionClient
public Task<IReadOnlyList<ProjectionEntry>> GetRegisterAsync(CancellationToken ct = default)
=> Task.FromResult<IReadOnlyList<ProjectionEntry>>(Entries);
}
/// <summary>Serves a configurable set of catalogus zaaktypen (beheer viewer, S-15a).</summary>
internal sealed class FakeAclClient : IAclClient
{
public List<BeheerZaaktype> Zaaktypen { get; } = [];
public Task<IReadOnlyList<BeheerZaaktype>> GetZaaktypenAsync(CancellationToken ct = default)
=> Task.FromResult<IReadOnlyList<BeheerZaaktype>>(Zaaktypen);
}
+44 -1
View File
@@ -227,10 +227,53 @@
}
}
}
},
"/beheer/catalogi/zaaktypen": {
"get": {
"tags": [
"Bff.Api"
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"$ref": "#/components/schemas/BeheerZaaktype"
}
}
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
}
}
}
}
},
"components": {
"schemas": {
"BeheerZaaktype": {
"required": [
"identificatie",
"omschrijving"
],
"type": "object",
"properties": {
"identificatie": {
"type": "string"
},
"omschrijving": {
"type": "string"
}
}
},
"CurrentRegistration": {
"required": [
"registrationId",
@@ -343,4 +386,4 @@
"name": "Bff.Api"
}
]
}
}