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

BaSyx Secured Example

Local Keycloak with separate BaSyx components, ABAC rules, and admin, read-only, and anonymous access scenarios.

BaSyx Ory Hydra Example

Local Hydra and Kratos with the combined AAS Environment, JWT access tokens, and provider claim mappings.

BaSyx Entra ID Example

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

issuer

Required. Duplicate or empty issuers make startup fail.

audience

Optional. An empty value disables audience validation for this issuer.

scopes

Optional list of scopes that must all be present.

discoveryUrl

Optional non-standard discovery-document URL. If omitted, standard discovery is used. A custom document must report the configured issuer and a JWKS URL.

scopeClaims

Optional JSON pointers to scope claims. The default is /scope and /scp.

claimMappings

Optional mappings from provider claims to canonical basyx.<target> claims.

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.

ABAC Authorization#

BaSyx access-rules files use one top-level AllAccessPermissionRules object. It contains reusable definitions and the rules that combine them:

Element

Purpose

DEFATTRIBUTES

Names reusable subject attributes such as required token claims or the ANONYMOUS global.

DEFOBJECTS

Names reusable route, identifiable-resource, descriptor, or referable targets.

DEFACLS

Names reusable ACLs that combine subject attributes, rights, and ALLOW or DISABLED.

DEFFORMULAS

Names reusable logical conditions over claims, time globals, constants, and resource fields.

rules

Combines an ACL, objects, a formula, and optional fragment filters, either inline or through the definitions above.

For detailed syntax and constraints, see the IDTA-01004 v3.1 Access Rule Model and the AAS Query Language grammar. The example below shows a complete JSON policy.

Rules grant access. A disabled rule is skipped, and no matching allow rule means denial. When several rules match, their grants are alternatives.

Rights and Request Matching#

BaSyx maps each registered HTTP method and route to required rights:

Right

Typical use

CREATE

Create a resource or child resource.

READ

Retrieve, list, query, or read service information.

UPDATE

Replace or modify an existing resource.

DELETE

Delete a resource.

EXECUTE

Invoke Operations and use their status/results, or call /verify.

ALL

ACL wildcard that satisfies any mapped right.

The policy grammar also accepts VIEW, but no shared runtime route is mapped to that right. Do not use it as a substitute for READ.

When a route is mapped to more than one right, those rights are alternatives, not cumulative requirements. Effect-specific checks for create-or-replace operations are endpoint-specific. See the relevant component page.

A rule is eligible only when its right, declared subject attributes, target objects, and formula match. Route objects match the API path. Resource objects and formulas can further restrict identifiable resources, descriptors, referables, or their fields.

Attribute Evaluation#

Every declared CLAIM or CLAIMPATH attribute must exist. A missing claim or claim path makes that rule ineligible. Formula values with an unsupported type or a condition that cannot be evaluated fail closed for that rule.

Formulas can use server-provided UTCNOW and LOCALNOW globals. CLIENTNOW is taken from the validated token claim of that name when present. Time globals can participate in formulas, but they do not by themselves identify an eligible subject. The ACL also needs a claim attribute or ANONYMOUS.

Claim Array Membership#

In ABAC formulas, $contains can check membership in an array of claim values. Use a direct $attribute with CLAIMPATH as the first operand and a scalar string expression ($strVal or $strCast) as the second. CLAIMPATH uses a JSON Pointer into the token claims. For example, this formula checks for the role admin in the nested realm_access.roles array:

{
  "$contains": [
    { "$attribute": { "CLAIMPATH": "/realm_access/roles" } },
    { "$strVal": "admin" }
  ]
}

The array must contain only strings. Membership uses exact, case-sensitive equality: ["viewer", "admin"] matches, while ["administrator"] does not. An empty array returns false. A missing claim, a scalar or object value, or an array containing any non-string entry makes the condition indeterminate, so it does not grant access. This membership form requires CLAIMPATH. Ordinary $contains comparisons between strings use substring matching.

Authorization Outcomes and Resource Filtering#

ABAC evaluation has three user-visible outcomes:

  • no allow rule matches, so the request is denied;

  • an allow rule matches without residual resource conditions, so access is unrestricted for that operation;

  • an allow rule matches but leaves resource or fragment conditions that the participating API and persistence layer enforce as a query filter.

The third outcome lets a collection request return only authorized resources and can hide restricted fragments of otherwise visible resources. Caller filters are combined with the authorization conditions using logical AND. A client-supplied query cannot broaden the ABAC result.

Minimal Access Policy#

On a component that exposes /description, this policy uses the basyx.role produced by the trustlist example and permits callers with role viewer to read the service description:

{
  "AllAccessPermissionRules": {
    "DEFATTRIBUTES": [
      {
        "name": "role_attr",
        "attributes": [{ "CLAIM": "basyx.role" }]
      }
    ],
    "DEFOBJECTS": [
      {
        "name": "description_api",
        "objects": [{ "ROUTE": "/description" }]
      }
    ],
    "DEFACLS": [
      {
        "name": "viewer_read",
        "acl": {
          "USEATTRIBUTES": "role_attr",
          "RIGHTS": ["READ"],
          "ACCESS": "ALLOW"
        }
      }
    ],
    "DEFFORMULAS": [
      {
        "name": "is_viewer",
        "formula": {
          "$eq": [
            { "$attribute": { "CLAIM": "basyx.role" } },
            { "$strVal": "viewer" }
          ]
        }
      }
    ],
    "rules": [
      {
        "USEACL": "viewer_read",
        "USEOBJECTS": ["description_api"],
        "USEFORMULA": "is_viewer"
      }
    ]
  }
}

This policy does not grant access to any other route or right.

Fragment Filter Targets#

FILTER and FILTERLIST entries use the same fragment paths and target restrictions as query $filters; see Fragment Paths. A filter cannot target the mandatory $sm#id or the idShort of a named Submodel Element. A policy containing such a filter is rejected on import, validation, and activation, and an active database policy that still contains one cannot be loaded. Before upgrading from an earlier release, remove or change these filters in the policy file and in the active database policy.

Submodel fragment filters apply to direct Submodel and $metadata reads in the same way as to list and query responses.

Submodel Superpaths#

The AAS Repository and AAS Environment serve Submodels below /shells/{aasIdentifier}/submodels/{submodelIdentifier}. Such a superpath request needs a rule for the requested Submodel or element and, in addition, access to the enclosing shell. The shell is checked with the $aas and ROUTE rules of /shells/{aasIdentifier}, including their formulas:

Superpath request

Right required on the shell

PUT or DELETE /shells/{aasIdentifier}/submodels/{submodelIdentifier}, which add or remove the shell’s Submodel reference

UPDATE

Every other superpath request

READ

Without a matching shell rule, the request returns 403 Forbidden. A shell excluded by a formula returns 404 Not Found, as for a direct shell request. A policy that grants superpaths only through $sm or $sme objects or /shells/*/submodels/* routes therefore also needs a rule for the shell. The formulas of the Submodel rules apply to the Submodel and its elements, not to the shell. ReBAC grants on the shell also satisfy the shell check.

Submodel Element Reads#

A $sme REFERABLE object covers the named element and its descendants. When READ access is granted through such objects, the element collection read GET /submodels/{submodelIdentifier}/submodel-elements and its $value, $metadata, $reference, and $path variants return only the covered elements, like the single-element reads.

The $reference of a single Submodel Element is authorized like a read of the element: the formula applies to the element itself, and its parent elements must be visible to the caller but need not match the formula. The returned reference contains the model types of the parent elements.

Historical Reads#

Stored history versions cannot be filtered. With ABAC enabled, $history returns 404 Not Found when the caller’s matching rules restrict the resource with a formula or a FILTER/FILTERLIST fragment filter. Only callers allowed to read the complete resource receive historical versions. See Read a Historical State.

Environment Import and Export#

The AAS Environment accepts type-scoped IDENTIFIABLE grants on /upload, /upload-async, and /serialization. For example, add this rule to AllAccessPermissionRules.rules to let the authenticated subject reader-subject export one Submodel:

{
  "ACL": {
    "ATTRIBUTES": [{ "CLAIM": "sub" }],
    "RIGHTS": ["READ"],
    "ACCESS": "ALLOW"
  },
  "OBJECTS": [{ "IDENTIFIABLE": "$sm(\"urn:example:submodel:1\")" }],
  "FORMULA": {
    "$eq": [{ "$attribute": { "CLAIM": "sub" } }, { "$strVal": "reader-subject" }]
  }
}

No additional ROUTE grant is required. $sm("*") covers only Submodels; $aas and $cd grants cover AASs and Concept Descriptions separately. Standalone REFERABLE, FRAGMENT, and DESCRIPTOR grants do not grant Environment import/export access. Existing route grants and per-resource ReBAC grants remain alternatives.

Exports apply READ formulas and field/element filters in JSON, XML, and AASX. Attachments and thumbnails also require authorization and visible model references. Missing or inaccessible explicitly selected AASs or Submodels abort the export with 404. Unreadable referenced Concept Descriptions are omitted. A caller without permission to use the endpoint receives 403.

Imports require CREATE for new objects and UPDATE for existing ones. New attachment or thumbnail content requires CREATE even when its AAS or Submodel already exists. Replacing stored content requires UPDATE. A denial returns 403, and nothing from the upload is stored. POST /upload-async is authorized like /upload, and only the uploader can read its status and result. See Re-import and Failure Behavior.

Common Authorization Responses#

Situation

Response

A token sent as Authorization: Bearer <token> is malformed, has an untrusted issuer, fails token validation, or contains claims that BaSyx cannot normalize

401 Unauthorized

An authenticated token does not contain every scope required by its trustlist entry

403 Forbidden

ABAC denies an otherwise valid request on an ABAC-only route outside /security/abac, whether authenticated or anonymous

403 Forbidden

After OIDC processing, ABAC denies access below /security/abac; policy-management resources are deliberately hidden

404 Not Found

An authenticated request on a covered route needs a ReBAC decision, but that decision cannot be obtained

503 Service Unavailable

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#