Runtime Security#
BaSyx validates signed JWT bearer access tokens against configured OpenID Connect (OIDC) providers, checks required scopes, and normalizes the resulting claims. Attribute-based access control (ABAC) then determines which API operations and resources the caller may use. Experimental ReBAC can additionally grant access on supported services and routes. Requests without credentials can continue as anonymous. ABAC still decides whether they are allowed. This is separate from Supply Chain Security, which covers container images, signatures, provenance, and SBOMs.
Note
To try BaSyx authentication and access control, choose an example setup:
Example |
Identity provider and setup |
|---|---|
Local Keycloak with separate BaSyx components, ABAC rules, and admin, read-only, and anonymous access scenarios. |
|
Local Hydra and Kratos with the combined AAS Environment, JWT access tokens, and provider claim mappings. |
|
An external Microsoft Entra ID tenant with app registrations, API audiences, and delegated or app-only permissions. |
Security Model#
With abac.enabled=true, OIDC validates a supplied bearer token, checks its
required scopes, and normalizes its claims. A request without credentials
continues as anonymous; a supplied token that cannot be accepted is rejected
before authorization. ABAC then evaluates the authenticated claims or
anonymous subject against the requested operation, resource, and active
policy. An ABAC allow can include resource, fragment, or update restrictions
that the protected API enforces.
---
config:
theme: base
themeVariables:
actorBkg: '#ffffff'
actorBorder: '#cccccc'
actorLineColor: '#666666'
actorTextColor: '#000000'
background: '#ffffff'
clusterBkg: '#f9f9f9'
clusterBorder: '#dddddd'
edgeLabelBackground: '#ffffff'
labelBoxBkgColor: '#ffffff'
labelBoxBorderColor: '#cccccc'
labelTextColor: '#000000'
lineColor: '#666666'
loopTextColor: '#000000'
mainBkg: '#ffffff'
nodeBkg: '#ffffff'
nodeBorder: '#cccccc'
noteBkgColor: '#ffffcc'
noteBorderColor: '#cccccc'
noteTextColor: '#000000'
primaryBorderColor: '#444444'
primaryColor: '#ffffff'
primaryTextColor: '#000000'
secondBkg: '#f5f5f5'
secondaryColor: '#f0f0f0'
signalColor: '#333333'
signalTextColor: '#333333'
tertiaryBkg: '#eeeeee'
tertiaryColor: '#e8e8e8'
---
flowchart TD
REQUEST[API request] --> TOKEN{Bearer token supplied?}
TOKEN -- No --> ANONYMOUS[Anonymous caller]
TOKEN -- Yes --> OIDC[OIDC validates the token and scopes<br/>and normalizes claims]
OIDC -- Rejected --> REJECTED[Reject request]
OIDC -- Accepted --> AUTHENTICATED[Authenticated caller and claims]
ANONYMOUS --> ABAC[ABAC evaluates the active policy]
AUTHENTICATED --> ABAC
MANAGEMENT[Optional ABAC Policy Management] -. activates .-> POLICY[Active ABAC policy]
POLICY --> ABAC
ABAC --> UNCONDITIONAL{Does ABAC grant the required<br/>right unconditionally?}
UNCONDITIONAL -- Yes --> RESULT[Use the ABAC result]
UNCONDITIONAL -- No --> ELIGIBLE{Authenticated caller on a<br/>ReBAC-covered route?}
ELIGIBLE -- No --> RESULT
ELIGIBLE -- Yes --> REBAC[ReBAC evaluates relationships]
REBAC -- Grant --> GRANT[Allow the granted resource]
REBAC -- No grant --> NO_GRANT[Keep ABAC restrictions<br/>or return no visible list entries]
REBAC -- Unavailable --> UNAVAILABLE[503 Service Unavailable]
ReBAC is therefore an additional way to grant access, not a second gate that every request must pass. ABAC can allow a request without ReBAC, while a ReBAC grant can widen access for its covered resource. Without such a grant, ABAC restrictions remain; a covered list that neither mechanism grants returns no visible entries. Anonymous requests and routes outside ReBAC coverage remain ABAC-only. See Relationship-Based Access Control for the covered services, resources, and sharing semantics.
ABAC Policy Management is not another request-time authorization mechanism. Where supported, it stages, validates, and activates policy versions; the active version supplies the policy evaluated by ABAC.
What Runtime Security Does#
abac.enabled is the switch for the shared security stack. When it is true,
the service reads the configured trustlist and installs OIDC before ABAC on its
API routes. ABAC evaluates the request method, route, required right, claims,
target objects, and policy formula.
When abac.enabled is false (the default), the service does not read the
trustlist or install the shared OIDC and ABAC middleware. The API routes then
have no protection from this stack. Use a trusted network boundary or external
gateway if access control is still required.
Supported Components and Default Posture#
The following entry points install the shared OIDC and ABAC stack:
AAS Environment
AAS Repository and Submodel Repository
Concept Description Repository
AAS Registry and Submodel Registry
Basic Discovery
AASX File Server
Digital Twin Registry
DPP API
The Company Lookup service does not install this stack. Sharing the common configuration structure does not by itself make a service secured.
In the standard entry points, health and Swagger/OpenAPI endpoints are registered outside the protected API router. Do not rely on an ABAC rule to restrict those endpoints.
Enabling Runtime Security#
A typical file-based startup configuration is:
oidc:
trustlistPath: /security/trustlist.json
abac:
enabled: true
modelPath: /security/access-rules.json
The equivalent enable switch is ABAC_ENABLED=true. The trustlist must be
readable, and modelPath must be readable when the component loads or imports
the file. See
General Configuration for all keys, defaults,
environment-variable names, startup import modes, and file-mount guidance.
For components with PostgreSQL-backed ABAC policy storage, authorization uses
the active database policy. abac.policyFileImport controls whether
abac.modelPath is imported and activated at startup. When the setting is
omitted, the default is if_missing for these components except the Digital
Twin Registry, whose default is always. The DPP API instead loads the file
directly and does not use this database-backed import lifecycle. See
ABAC Policy Management for policy scopes, versioning,
staged changes, activation, and multi-replica operation.
OIDC Authentication#
Send an access token as:
Authorization: Bearer <token>
BaSyx accepts compact signed JWT bearer tokens. It does not support opaque
tokens or token introspection. Provider-specific token-type indicators are
ordinary claims. Map and require them in the ABAC policy if they must be
enforced. The token’s iss value must identify a configured trustlist entry.
For that issuer, BaSyx obtains OpenID Provider metadata and keys, then verifies
the signature, issuer, expiration, and the configured audience. A malformed or
unverifiable token sent using the header above is rejected before ABAC.
Audience validation is optional. If a trustlist entry has an empty or omitted
audience, BaSyx skips the audience check and logs a startup warning for that
issuer. Configure an audience when the identity provider supplies one for the
BaSyx API.
The trustlist entry’s scopes list names the scopes that the token must grant.
Every configured scope is required. BaSyx reads granted scopes from the JSON
claim paths in scopeClaims, which default to /scope and /scp. At those
paths, a JWT claim may be a whitespace-separated string or a string array.
BaSyx splits and deduplicates these values before checking the required scopes.
A missing required scope produces 403 Forbidden before ABAC authorization.
Trustlist Format#
The trustlist is a JSON array with one entry per accepted issuer. This example is based on the released Ory Hydra example and maps a provider-specific role into a canonical BaSyx claim:
[
{
"issuer": "https://idp.example.com",
"audience": "basyx-api",
"scopes": ["openid"],
"claimMappings": [
{
"target": "role",
"mode": "scalar",
"sources": ["/ext/role"]
}
]
}
]
Field |
Behavior |
|---|---|
|
Required. Duplicate or empty issuers make startup fail. |
|
Optional. An empty value disables audience validation for this issuer. |
|
Optional list of scopes that must all be present. |
|
Optional non-standard discovery-document URL. If omitted, standard discovery is used. A custom document must report the configured issuer and a JWKS URL. |
|
Optional JSON pointers to scope claims. The default is |
|
Optional mappings from provider claims to canonical |
Mapping target: role creates basyx.role. The access policy can use that
claim while the provider’s original claims remain available. list mode
collects and deduplicates strings from all present sources. scalar mode uses
the first present source and accepts a primitive value or a single-item
primitive array. Invalid mapped value shapes reject the token.
Each mapping needs a target, a list or scalar mode, and at least one source.
The sources values are JSON pointers. Targets must be unique, must not use the
reserved basyx. prefix, and must not be scopes. BaSyx also adds the
normalized basyx.scopes claim. A token that already contains any basyx.*
claim is rejected so that the identity provider cannot bypass canonical
mapping.
Anonymous Requests#
The OIDC layer allows a request with no bearer token to continue with an empty,
unauthenticated claim set. A missing token therefore does not automatically
produce 401 Unauthorized. ABAC still evaluates the request and denies it
unless the active policy contains a rule that allows the operation without
token claims.
To make an operation public, an ACL can declare the subject attribute:
{ "GLOBAL": "ANONYMOUS" }
Its rights, objects, and formula must also match. ANONYMOUS marks a public
rule and also matches authenticated callers. If the ACL additionally declares
a CLAIM or CLAIMPATH, that claim must still be present. A malformed or
otherwise invalid token sent using the documented header is rejected with
401 rather than treated as anonymous.
Component-Specific Behavior#
The Digital Twin Registry and standalone Submodel Repository can optionally
copy the caller-supplied Edc-Bpn header into the claims evaluated by ABAC when
general.enableCustomMiddlewareHeaderInjection is enabled.
For Catena-X deployments that supply the caller’s Business Partner Number (BPN)
through the Edc-Bpn HTTP header, set
general.enableCustomMiddlewareHeaderInjection: true so ABAC can evaluate that
value. If the BPN is instead supplied as a signed token claim named Edc-Bpn,
header injection can remain disabled.
The header is not authenticated by BaSyx. A non-empty header value replaces a token claim with the same name. Keep this option behind a trusted intermediary that strips or overwrites client input. See the Digital Twin Registry’s Security and Visibility Semantics for the DTR-specific behavior.
Registry, Repository, Discovery, and aggregate-service APIs also have resource-specific authorization and filtering semantics. Their component pages remain the source for those differences.
Relationship to ReBAC#
Experimental ReBAC is an optional authorization extension. It does not replace
OIDC or ABAC and requires abac.enabled=true plus a readable trustlist. For an
authenticated caller on a covered route, BaSyx consults ReBAC for relevant
rights that ABAC has not granted unconditionally. A matching ReBAC grant can
therefore widen access beyond ABAC alone. For the resource covered by the
grant, ABAC policy fragment filters and update conditions do not restrict that
grant; caller-supplied query and fragment filters still apply.
If a required ReBAC decision cannot be obtained, the request fails closed with
503 Service Unavailable instead of falling back to ABAC-only behavior.
Anonymous requests and routes or services outside ReBAC coverage remain
ABAC-only. The Digital Twin Registry does not enable ReBAC. See
Relationship-Based Access Control for supported components, roles,
sharing, inheritance, and administration.
See Also#
General Configuration for all OIDC, ABAC, and security-file settings
Shared Runtime Features for the wider shared runtime feature set
Supply Chain Security for image integrity, provenance, and SBOMs
MCP Endpoint for MCP client sign-in and identity provider requirements