Identity provider

Every protected API call carries a bearer token your identity provider issued. The engine verifies each token against the provider’s published keys and reads the caller’s roles from it; it keeps no passwords and no user list of its own. The screens your staff and your investors use are your own, or your systems integrator’s: they sign their users in at your provider and call the API with the token it issues.

What the engine checks

The token is verified by Spring Security’s OAuth2 resource server, on every request to a protected route and before the request reaches a route. The engine’s own rules then decide what the verified caller may do:

Check	Rule
Signature	RS256 or ES256, under a key from the provider’s key set (JWKS). A token signed any other way, `none` included, is refused before its claims are read
Type	The `typ` header is `JWT`, or absent
Issuer and audience	`iss` equals the configured issuer exactly; `aud` contains the engine’s audience
Time	`exp` is present and not past, and `nbf` is not in the future, with a minute’s slack by default
Subject	`sub` is present: it is the identity four eyes compares. A subject reserved for the engine’s own scheduler is refused
Roles	Read from the roles claim, `roles` by default: a JSON array, or one string separated by spaces or commas. A value that names no NodeAsset role is ignored, so the same token can carry other applications’ roles
Holder	For an investor, its holder id, from the holder claim, `holder` by default. An investor’s token reads and acts for that holder only
Route	The caller holds one of the roles the route admits. Four eyes and an investor’s own records are the engine’s rules too

A public route, such as GET /v1/health, reads no token, so a stale one there is no refusal. A refusal is a problem document:

Status	Slug	When
401	`unauthenticated`	No token, or one that fails a check above. The answer carries `WWW-Authenticate: Bearer` and the reason, never the token
403	`role-refused`	A valid token whose roles the route does not admit. The answer names the roles that would
503	`idp-unavailable`	The provider’s keys could not be fetched: the token may be fine. The answer carries `Retry-After`

Names in the record

The engine records the token’s name and email claims beside its subject, where the token carries them: on each operation, on each four-eyes action for its maker, each approver and whoever decided it, and in each audit log entry. The record then reads without the provider: an auditor sees who acted, not only an opaque subject. The claims decide nothing; the subject alone is the identity. Another provider’s claim names are set in the configuration.

Set up the provider

A client for the engine

Register the engine as an audience at your provider. Tokens meant for the engine carry that audience; tokens for anything else are refused.

The roles claim

Map your groups to NodeAsset’s role names, such as operator, approver or auditor, in a claim the access token carries. Segregation of duties lists every role.

One subject per person

Four eyes compares subjects. Give each person a subject of their own, never a shared account: a person holding two roles still cannot approve their own action.

Investors

An investor’s token carries the investor role and its holder id in the holder claim, as the venue registered it.

Systems

Give each system a client of its own, with its service role: app for an integrating application’s backend, feed for a statement connector, monitor for monitoring, and registrar for the register keeper’s own systems, which read what the venue asks of it.

The engine

Set the sign-in mode to idp, with the provider’s issuer, the engine’s audience and the provider’s key set URL (Configuration reference). The engine refuses to start under idp without all three.

Check it

GET /v1/whoami answers what the engine read from a token: its subject, roles, holder, client, issuer, name and email.

Example tokens

The claims the engine reads, for a person, an investor and a system:

{ "iss": "https://idp.example/realms/nodeasset", "aud": "nodeasset-engine", "sub": "c41f0d2e", "exp": 1790000000, "roles": ["operator"], "name": "Olive Park", "email": "olive.park@venue.example" }
{ "iss": "https://idp.example/realms/nodeasset", "aud": "nodeasset-engine", "sub": "7a90b3c4", "exp": 1790000000, "roles": ["investor"], "holder": "inv-001" }
{ "iss": "https://idp.example/realms/nodeasset", "aud": "nodeasset-engine", "sub": "svc-nav-feed", "exp": 1790000000, "roles": ["feed"], "azp": "nav-feed" }

Every caller presents a token the provider issued for the person or the system acting: a person at a desk, an integrating application, a statement connector, a monitoring system. Each operation records the subject and the role it ran under, and the name and email where the token carries them.

The engine’s own ledger identity

Signing in to the API and the engine’s access to the ledger are separate. The engine submits to your Canton node as its own Ledger API user, with a token it fetches from your provider by client credentials, or reads from a file. See Configuration reference. Related: Segregation of duties · Configuration reference · How the API works

Architecture

Who runs what

Deploy

Operate

What the engine checks

Names in the record

Set up the provider

Example tokens

The engine’s own ledger identity

​What the engine checks

​Names in the record

​Set up the provider

​Example tokens

​The engine’s own ledger identity

What the engine checks

Names in the record

Set up the provider

Example tokens

The engine’s own ledger identity