Authentication Authorization

Overview

AAS.TwinEngine is a framework and aims to integrate into every system landscape. Instead of introducing a new and complicated security concept we decided to use the existing resources. To achieve this there are three different components in the security concept: API Gateway (general security measures), Template services (AAS related security measures) and plugin/ data sources (data related security measures) that will be explained in the following in more detail.

Security Architecture

The diagram below shows the complete security flow: authentication, header forwarding with mapping rules, and downstream token validation.

sequenceDiagram
    actor Client as Client / Admin
    participant IdP as Identity Provider
    participant APIGW as API Gateway
    participant DE as DataEngine
    participant TR as Template Repository
    participant REG as Registry
    participant PLG as Plugin
    participant DS as Business Data Source

    Client->>IdP: Authenticate (login)
    IdP-->>Client: Token (e.g., JWT)

    Client->>APIGW: API request + token
    APIGW->>DE: Forward request + token

    DE->>DE: Apply Header Mapping Rules per destination
    Note over DE: Map source header → target header<br/>Reject if required header missing<br/>No token validation - forward only

    DE->>TR: Request + mapped auth header
    TR->>TR: Validate token & enforce policy
    TR-->>DE: Response

    DE->>REG: Request + mapped auth header
    REG->>REG: Validate token & enforce policy
    REG-->>DE: Response

    DE->>PLG: Request + mapped auth header
    PLG->>PLG: Validate token & authorize access
    PLG->>DS: Authorized data access
    DS-->>PLG: Data
    PLG-->>DE: Response

    DE-->>APIGW: Aggregated response
    APIGW-->>Client: Response

Loading

How to Read This Flow

1. Users or clients authenticate and obtain tokens through the Identity Provider.
2. API traffic enters through the API Gateway as the first control point.
3. DataEngine applies header mapping rules before forwarding each request to a downstream service. Header mapping means: the operator configures, per destination (e.g. Template Repository, Plugin), which HTTP header from the incoming request should be forwarded, and under what name it should arrive at the destination. For example, a token arriving in Authorization can be forwarded as X-Auth-Token to a specific plugin. If a header marked as required in the mapping is absent from the incoming request, DataEngine rejects the request immediately. DataEngine reads only the header name. it never inspects, decodes, or validates the token value itself.
4. Repository and Registry components validate the token and enforce their own endpoint authorization policies.
5. Plugins are the final enforcement point - they validate the token and make the authorization decision before accessing business data.

Key idea:

• Security is layered, and each layer adds protection.
• DataEngine is a pass-through for authentication - it forwards, not validates.
• The operator configures the header name responsible for auth in DataEngine's configuration.
• Plugins are the final enforcement point for real data access.
• Correct configuration is essential; weak configuration can bypass intended controls.

Security Layers (High Level)

• API Gateway layer: traffic filtering, TLS termination, and basic request protection.
• DataEngine layer: controlled auth header forwarding (configurable header name - no token validation).
• Registry/Repository layer: token validation and endpoint-level policy enforcement.
• Plugin layer: token validation and final authorization decision before accessing business data.

How DataEngine Handles Header Forwarding

DataEngine forwards selected headers from incoming requests to downstream services based on explicitly configured mapping rules.

The operator configures:

• which incoming header should be read
• how it should be renamed (if needed)
• whether it must be present for each destination

Key behavior:

• Header forwarding is fully driven by configuration and defined per destination (e.g., Template Repository, Registry, Plugins).
• Each mapping specifies:
  • Source header – the header name expected in the incoming request
  • Target header – the header name used when forwarding to the downstream service
  • Required flag – whether the header must be present
• DataEngine reads only the header name defined in source and forwards its value unchanged.
• DataEngine may rename the header (source → target), but it does not modify the value.
• If a header marked as required: true is missing in the incoming request, DataEngine rejects the request immediately.
• DataEngine never inspects, decodes, or validates the token value — it is treated as opaque data.

Key Principle

DataEngine acts purely as a controlled header forwarding component:

• It reads → optionally renames → forwards
• It does not interpret or validate any authentication data

Minimal Mapping Example

header-mappings:
  template-repository:
    - source: Authorization
      target: Authorization
      required: true
  plugins:
    plugin1:
      - source: Authorization
        target: X-Auth-Token
        required: false

Public guidance:

• Keep mappings explicit and destination-specific.
• Review required headers carefully to avoid accidental request rejection.