Two questions, every single time

Every time you open a page in the VS Platform, the system quietly asks two completely different questions about you. Almost all of security comes down to keeping these two apart.

What actually happens when you click "Sign In"

You're looking at the VS Platform single-page app in your browser. You click Sign In. From your point of view you blink and you're in. Under the hood, this happened:

Why is this spread across so many programs?

Here's the surprise for a lot of people: this isn't one login function in one file. In the VS Platform, the work is split across eight separate code repositories, each a different program with one job.

In the next module you'll meet all eight characters by name. For now, just hold this picture: a doorman (Keycloak) issues a badge (a token), and a border guard (the gateway) checks it before letting anything through.

Quick check

The cast list

Each of these is a separate repository named vs-plat-*. Hover any term you don't recognize — there's a definition behind every dashed underline.

The glue: everyone trusts the same doorman

For badges to mean anything, every service has to agree on who is allowed to issue them. The orchestrator guarantees this by stamping every service with the same issuer address at startup.

var authority = $"http://localhost:8080/realms/{realm}";
return resource
  .WithEnvironment("VSPlatformAuth__Authority", authority)
  .WithEnvironment("VSPlatformAuth__AdditionalValidIssuers__0", authority)
  .WithEnvironment("VSPlatformAuth__RequireHttpsMetadata", "false");

Match each actor to its job

Drag each character onto the role it plays. (On a phone, tap and drag.)

Quick check

The redirect dance

The pattern the platform uses is an industry standard called OpenID Connect. The clever part is the Authorization Code flow: your password goes only to Keycloak, and the app receives a badge instead.

Step through the dance — click Next Step:

How the browser is configured for this

The front-end sets up an OIDC helper once, telling it where the doorman lives and what kind of badge to request. This is the real configuration from the web client:

export const userManager = new UserManager({
  authority,
  client_id: clientId,
  redirect_uri: `${window.location.origin}/auth/callback`,
  response_type: 'code',
  scope: 'openid profile email vs-context vs-platform-gateway',
  stateStore: new WebStorageStateStore({ store: browserStorage }),
});

What's actually inside the badge?

The badge is a JWT — three parts separated by dots. Anyone can read the middle part, but only Keycloak can produce a valid signature, so nobody can forge or edit it.

Decoded, the claims part of a real badge looks like this (sensitive values replaced with placeholders):

{
  "iss": "http://localhost:8080/realms/vs-platform",
  "aud": "vs-platform-gateway",
  "sub": "<your-user-id>",
  "preferred_username": "<your-username>",
  "org_id": "<org-uuid>",
  "exp": 1735689600
}

Quick check

One badge can't open every door

Remember the aud (audience) claim from the last module? A badge stamped vs-platform-gateway is accepted only by the gateway. The business API rejects it on sight, because its name isn't on the stamp.

So how does a request actually reach the API? The gateway does three jobs, in order, for every single request.

Listen in on the border crossing

Here's the conversation between the four characters when you ask for the employee list. Play it message by message:

Why bother with a separate exchange office?

The badge-swap is done by the STS, not the gateway itself. That's deliberate: the dangerous secrets needed to mint new badges live in one tiny service, so a bug anywhere else can't leak them.

And critically — the gateway throws away the browser's original badge before forwarding. The inner service only ever sees the freshly-stamped one. Here's that exact moment in the gateway code:

transformContext.AddRequestTransform(requestContext =>
{
  requestContext.ProxyRequest.Headers.Authorization = null;

  if (requestContext.HttpContext.Items[ExchangedTokenItemKey] is string accessToken)
  {
    requestContext.ProxyRequest.Headers.Authorization =
      new AuthenticationHeaderValue("Bearer", accessToken);
  }
});

Quick check

Every endpoint guards itself

Inside the business API, individual actions are protected one at a time. Reading the employee list requires the employees.read permission. The check is a single line above the method:

[HttpGet]
[RequireVsPermission(ApiPermissions.EmployeesRead)]
public async Task<ActionResult> GetAll()
{
  var items = await dbContext.Employees…ToListAsync();
  return Ok(items);
}

The verdict is returned, never thrown

Behind that one-line check is a decision engine shared by every service (from the common rulebook library). It returns a verdict object explaining exactly why access was allowed or denied — which is gold when you're debugging.

These are the real reasons it can say "no":

One person, many organizations

A single user can belong to several organizations. But a badge carries exactly one org_id at a time — you act inside one org, then switch. Here's the choreography:

The list of organizations comes from the authz service, which guards it with its own permission:

[HttpGet("mine")]
[RequireVsPermission(AuthzPermissions.OrgsRead)]
public async Task<ActionResult<IReadOnlyList<OrgSummaryDto>>> GetMine(…)

The records office and the locksmith

Where do permissions actually live? Two places, kept in sync — and understanding this split explains a whole class of "why can't I do this?" bugs.

Quick check

The whole journey, one click

Everything from the last five modules, in a single trip. Step through it — by the end this should feel familiar, not mysterious:

A debugging field guide

When something fails, the symptom usually points straight at one stage of that journey. Here's where to look first:

Spot the bug

Here's a snippet of the business API's configuration. One line will make every request fail after it passes the gateway. Click the line you think is wrong:

You can now read the whole system

Six ideas, and you have the complete map:

Final check