Tenants and Access
Create tenants, give applications least-privilege API clients, and let people
sign in. Every management endpoint (/api/...) needs an OAuth 2.0 bearer token;
the roles and tenant of its client or person decide what the caller may do. The
roles are listed in the roles reference.
Tenants
A tenant is one issuer and/or verifier: its credential, issuance and presentation
configurations, keys, trust lists, sessions and clients belong to it. All
records carry the tenant ID, and every request is scoped to the tenant in the
access token. Tenants have no lifecycle states besides active; to take a
tenant offline, delete it (below). Deleting its clients only ends their API
access (revoke access): people who sign in with Keycloak keep
theirs, and wallets can still finish the offers and requests already sent.
Create a tenant
With a token that has tenants:manage (for example the root client below):
curl -X POST https://eudiplo.example.com/api/tenant \
-H "Authorization: Bearer $ROOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "acme",
"name": "Acme GmbH",
"roles": ["issuance:manage", "presentation:manage", "tenant:admin"]
}'
POST /api/tenant accepts only IDs that use lowercase letters, digits, - and
_, start with a letter or digit and have at most 63 characters, since the ID
is also the name of the tenant's folder in CONFIG_FOLDER; other IDs answer
400. The startup import does not check folder names against this rule, so
name tenant folders by it as well.
If you pass roles, EUDIPLO also creates the client acme-admin with
clients:manage plus these roles, and returns its secret once in the response.
Use that client to set up the tenant and to create narrower clients. It can
hand out only clients:manage and these roles, unless they include
tenant:admin (granting roles), so
choose them with that in mind. The root client has no tenant and cannot change
a tenant's clients, but sending POST /api/tenant again for the existing
tenant, with its name and all roles the admin client needs, gives that client
clients:manage and these roles and removes its other EUDIPLO roles (with
Keycloak only those mapped directly to it, see
Keycloak SSO); with the built-in server it
also returns a new secret.
DELETE /api/tenant/:id removes the tenant with its data and files. Tenants can
also be created from a config folder with an info.json
(configuration as code).
API authentication
Built-in OAuth2 server
Without OIDC, EUDIPLO issues tokens itself with the client credentials grant:
curl -X POST https://eudiplo.example.com/api/oauth2/token \
-d grant_type=client_credentials \
-d client_id=acme-admin \
-d client_secret="$CLIENT_SECRET"
The client can also send its credentials with HTTP Basic authentication. Tokens
are signed with MASTER_SECRET and expire after 24 hours. The response has no
refresh token; request a new token with the client credentials. Use tokens as
Authorization: Bearer <token>. The Swagger UI of the
management API is at /api/docs (its Authorize button uses the same
endpoint); the wallet-facing protocol API is documented at /docs.
On the first start, EUDIPLO creates the root client from AUTH_CLIENT_ID and
AUTH_CLIENT_SECRET. It has tenants:manage and belongs to no tenant, so it
can create and manage tenants (each new tenant gets a <tenant>-admin client)
and rotate client secrets (except those of
file-managed clients), but cannot call tenant-scoped endpoints such as
clients, issuance or presentation configs. It can also see the cached status lists
and clear the trust list, federation and status list caches of all tenants
(roles). Changing the two variables later does not
change the stored client; rotate its secret with
POST /api/client/<client-id>/rotate-secret instead.
API clients with least privilege
Create one client per application, with only the roles it needs. A token with
clients:manage creates clients in its own tenant, with the roles it can hand
out, for example the acme-admin client above:
curl -X POST https://eudiplo.example.com/api/client \
-H "Authorization: Bearer $ADMIN_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"clientId": "shop-backend",
"description": "Issues membership cards and checks age",
"roles": ["issuance:offer", "presentation:request"],
"allowedIssuanceConfigs": ["membership"],
"allowedPresentationConfigs": ["age-check"]
}'
The response contains the generated secret once; it is stored as a bcrypt hash
and cannot be read again. Rotate it with POST /api/client/:id/rotate-secret;
with the built-in server, tokens issued with the old secret stop working at
once (revoke access).
Client IDs may contain letters, digits, ., _, : and -, and are unique
across all tenants: an ID that is already taken answers 409.
allowedIssuanceConfigs limits the credential configuration IDs the client may
put in offers, allowedPresentationConfigs the presentation configurations it
may request. Other IDs are rejected with 403; an empty or missing list allows
all. The web client's client form changes a list only when it can load the
configurations to choose from: listing credential configurations needs
issuance:manage, listing presentation configurations presentation:manage or
presentation:request. Without that role, or when the list fails to load, the
field is locked: editing a client keeps its stored list, and a new client is
created without that limit. Set the list through the API in that case.
The session endpoints (/api/session) need issuance:offer,
presentation:request or sessions:read. Without sessions:read, a client
sees only the sessions of its side: issuance sessions with issuance:offer or
issuance:manage, presentation sessions with presentation:request or
presentation:manage. Other sessions are left out of the list, answer 404
and are not deleted. sessions:read reads the sessions of both sides, with
their logs, events, counts and credential status, including issued claims and
presented credentials, but creates, cancels and deletes none; together with
issuance:offer or presentation:request, a client still cancels and deletes
only the sessions of that side. Of the session types a client with
sessions:read cannot cancel, which also holds for issuance:manage or
presentation:manage without issuance:offer or presentation:request, it
sees only the sessions a wallet can no longer use: redeemed, answered or in a
final status. The others are left out of the list and answer 404,
because the session ID of an ISO 18013-7 request, or of an offer created
before 10.0, alone lets a wallet answer or redeem it; the counts include them.
The sessions it sees come without the values
a wallet redeems or answers them with, such as the offer and request URIs and
the transaction code. Changing credential status
(POST /api/session/revoke) needs credentials:status or issuance:manage.
Typical role sets:
| Caller | Roles |
|---|---|
| Your application backend | issuance:offer, presentation:request; also credentials:status if it revokes or suspends credentials |
| Support staff who look up sessions and revoke credentials | sessions:read, credentials:status |
| Auditor | audit:read, sessions:read |
| Key custodian | keys:manage |
| CI pipeline that imports configuration | tenant:admin |
| Person who configures a tenant | issuance:manage, presentation:manage, clients:manage, users:manage, and the roles they hand out; tenant:admin instead also allows key export and KMS settings |
| Platform operator | tenants:manage, on a client without a tenant |
issuance:manage, presentation:manage and keys:manage create, import,
rotate and delete key chains, but exporting a key chain with its private key
(GET /api/key-chain/{id}/export or its configuration document) and the tenant KMS provider configuration
(/api/key-chain/providers/config), which contains provider credentials, need
tenant:admin or tenants:manage, like configuration bundles.
A caller hands out only roles it holds, or with tenant:admin every role
except tenants:manage and tenant:admin, and cannot change or take over a
client or user with more rights than its own
(granting roles).
Revoke access
With the built-in server, EUDIPLO reads the client on every request: a token is
accepted only while its client exists in the token's tenant, and with the roles,
allowedIssuanceConfigs and allowedPresentationConfigs the client has now.
Deleting a client (DELETE /api/client/:id) ends its access at once; changing
its roles or limits applies to the tokens it already has.
A token is accepted only for the client and secret it was issued for. A client
created again with the same ID, including <tenant>-admin when you create a
deleted tenant again, does not revive the old tokens. A new secret ends the
client's tokens at once, also a token requested while the secret changed:
POST /api/client/:id/rotate-secret;POST /api/tenantwithrolesfor an existing tenant, which gives<tenant>-admina new secret;- a configuration bundle import with another secret, or with
!generatefor an existing client; - a startup import with another secret. A client file without
secretgets a new random secret on every start inupsertorreplacemode, so set the secret in the file.
Importing the secret the client already has keeps its tokens, also when the
startup import in upsert or replace mode re-creates the client. To change a
secret without interrupting an integration, create a second client, switch the
integration to it, then delete the first one.
With Keycloak, EUDIPLO checks tokens without asking Keycloak. Deleting a client
also deletes it in Keycloak, which then issues no new tokens to it. Without
OIDC_AUDIENCE, the tokens it already has get 401 at once, as EUDIPLO
accepts only tokens of the clients it manages
(details); creating a client with the same
ID again makes those that have not expired valid again. Deleting a tenant
leaves its clients in Keycloak, but without OIDC_AUDIENCE their tokens get
401 too; delete them in Keycloak. With OIDC_AUDIENCE set, the tokens of a
deleted client stay valid until they expire (the realm's access token
lifespan, 5 minutes by default), without the client's config limits. After a new secret, the tokens
a client already has stay valid until they expire in both cases. Keep that
lifespan short. Changes to the limits apply at once, role changes in Keycloak
with the next token.
External OIDC provider and human users
To let people sign in with their own accounts, set OIDC to a Keycloak realm.
With OIDC_PROVIDER=keycloak, the default, EUDIPLO manages clients and people
through Keycloak's admin API. Then:
- EUDIPLO accepts Keycloak access tokens instead of issuing its own; the
built-in
POST /api/oauth2/tokenis disabled. - The web client signs people in with the authorization code flow and PKCE,
from the URLs in
OIDC_UI_URLor the redirect URIs set in Keycloak. - Clients created through
/api/clientare Keycloak clients, and people are managed through/api/user(roleusers:manage) or in the web client. WithoutOIDC,/api/useranswers501and the web client hides Users. - Access tokens must carry the tenant ID in the claim named by
OIDC_SUB(defaulttenant_id) and the roles inrolesorrealm_access.roles, or in the claim named byOIDC_ROLES_CLAIM. - Without
OIDC_AUDIENCE, only access tokens issued to the web client's client (OIDC_UI_CLIENT_ID), theAUTH_CLIENT_IDclient (withAUTH_CLIENT_SECRETset) or a client EUDIPLO manages are accepted; tokens of other clients in the realm get401(details).
Another OpenID Connect provider, such as Authentik, Zitadel, Auth0 or Entra ID,
works with OIDC_PROVIDER=generic for signing in only. EUDIPLO then loads the
provider's discovery document at startup, checks the issuer, the signing keys
and the required OIDC_AUDIENCE, and accepts only JWT access tokens; ID
tokens with that audience are refused when they carry at_hash, c_hash or
s_hash, and tokens of another typ are refused too
(details). With Authentik, an ID
token still works as an access token
(details). The
provider manages clients and people: /api/client, /api/user and creating a
tenant with roles answer 501 (the web client creates tenants without an
admin client), and the web client hides API Clients and Users. Config
folders and bundles carry no clients either
(details).
The setup, including single sign-on in the web client and machine clients, is
described in Other OIDC providers.
Tokens get no client limits (allowedIssuanceConfigs,
allowedPresentationConfigs), except where a client record is left from an
earlier mode: Keycloak clients, the built-in AUTH_CLIENT_ID root client and
<tenant>-admin clients alike. A token whose azp, client_id or, without
those, sub names such a record gets the record's limits; if the record
belongs to another tenant than the token's, the token gets 401.
The web client does not read roles or the tenant from the token itself. It asks
the backend (GET /api/auth/me), so its menus follow OIDC_ROLES_CLAIM and
OIDC_SUB and show what the API allows.
The variables and the setup are described in Keycloak SSO or, for
another provider, in Other OIDC providers.
MASTER_SECRET is optional in OIDC mode, but the default encryption key is
derived from it; set it, or use another
encryption key source. OpenID Provider clients with a
subject
need it too.