Protocol

Overview

Identity & Trust (L3) provides functionality that identifies participating entities and establishes the trust foundation ensuring that data exchange occurs only between legitimate entities and with authorized access to legitimate resources.

This protocol covers the following domains:

• Authentication

  Identifies and authenticates both natural persons (Human) and systems (Machine) as subjects, and enables authentication appropriate to the operational context.

• Authorization

  Performs policy-based dynamic authorization on a per-request basis.

• Token and Credential Management

  Issues access tokens and refresh tokens, and attaches business-context claims such as operator identifiers (e.g., operator_id) as token claims.

• Federation & Trust

  Establishes mutual trust across different operating organizations and across different Open Dataspaces.

Abstract Normative Specification

Concepts and Roles

Concept	Description
Identity & Trust（L3）	A generic term for an entity that provides identity-related functions. It performs authentication of users and systems, manages authorization (delegation of authority), and provides identity information. Depending on the architecture, including federated configurations, these roles MAY be performed by separate entities.
Client	An entity that accesses APIs provided by a Resource Server under delegated authorization granted by a Resource Owner.
Resource Server	An entity that provides functions or data via APIs. It provides resources to a Client according to the scope of authority delegated by the Resource Owner.
Resource Owner	An entity that grants authorization to a Client to access a Resource Server (API Server) on its behalf.
Service Provider	The organization operating the Identity & Trust（L3）.
Operator	An organization that receives delegated authority from the Service Provider and operates systems within the dataspace.
PAP	Policy Administration Point responsible for defining and managing authorization policies.
PDP	Policy Decision Point that receives authorization requests from the PEP, evaluates policies defined by the PAP together with request context, and determines whether access shall be permitted or denied.
PEP	Policy Enforcement Point that receives requests from a Client and, where necessary, requests an authorization decision from the PDP.

Scope

This protocol defines requirements for the following functional areas:

• Authentication

• Authorization

• Token and credential management

• Federation (cross-Open Dataspaces trust establishment)

Normative Requirements

Authentication

• The Identity & Trust（L3）SHALL provide mechanisms capable of distinguishing and authenticating both natural persons and systems.

  • Rationale: ODS operational requirements involve both human interaction and system-to-system communication. These must be clearly distinguished to ensure proper security and accountability.

• Authentication and authorization mechanisms SHALL use OAuth 2.0 and OpenID Connect. Authentication of natural persons SHALL use OpenID Connect (Authorization Code Flow). Authentication of systems SHALL use OAuth 2.0 (Client Credentials Flow).

  • Rationale: OAuth 2.0 and OpenID Connect are internationally adopted standards that ensure interoperability across heterogeneous systems and dataspaces.

• User authentication SHOULD use Authorization Code Flow with PKCE.

  • Rationale: ODS environments commonly involve natural persons. PKCE improves resistance against authorization code interception attacks.

• Additional credentials (e.g., Verifiable Credentials) MAY be used.

  • Rationale: This enables extensibility and future interoperability with other Open Dataspace and trust frameworks.

• Phishing-resistant multi-factor authentication MAY be used.

  • Rationale: Multi-factor authentication reduces risks associated with credential theft and replay attacks.

  Note (Future revisions): MAY consider phishing-resistant authentication methods such as FIDO2-based passkeys.

Authorization

• Authorization decisions SHALL NOT depend solely on network boundaries (e.g., firewall or DMZ).

  • Rationale: This aligns with Zero Trust architecture principles and prevents implicit trust based on network location.

• The subject identifier used for authorization decisions SHALL be based on verified claims contained in the access token.

  • Rationale: This ensures logical linkage between authentication and authorization and prevents impersonation or identity inconsistencies.

• Authorization SHOULD adopt a two-layer structure consisting of coarse-grained access control at the API Gateway level and fine-grained access control at the application or resource level.

  • Rationale: Separation between infrastructure-level and business-level authorization preserves scalability and architectural flexibility.

• PAP, PDP, and PEP SHOULD be logically separated.

  • Rationale: Separation of policy administration, decision logic, and enforcement improves maintainability, security isolation, and performance optimization.

• Communication between PEP and PDP SHOULD align with the AuthZEN model or an equivalent standardized authorization interaction model.

  • Rationale: Alignment with standardized authorization interaction models improves consistency and supports interoperable policy evaluation mechanisms.

• PAP and PDP SHOULD, logically, be integrated with the Identity & Trust（L3）.

  • Rationale: To ensure consistency of the authorization model and evaluation logic and prevent complexity caused by distributed policy management.

• The authorization model SHOULD adopt Relationship-based Access Control (ReBAC). When ReBAC is adopted, the authorization model SHALL be capable of explicitly representing at least subject, object, and relation.

  • Rationale: It naturally represents delegation and sharing relationships as graphs and provides superior readability and extensibility.

Tokens and Credentials

• Access tokens SHOULD be signed JWTs.

  • Rationale: Signed JWTs provide interoperability, lightweight validation, and compatibility with existing ecosystem tooling.

• Access tokens SHOULD have short lifetimes limited to the minimum necessary duration.

  • Rationale: Short-lived tokens minimize impact in case of leakage or compromise.

• Business claims such as operator_id and system_id SHOULD be included where applicable.

  • Rationale: Identification of business entities within Open Dataspaces is essential.

• Refresh Tokens MAY be used.

  • Rationale: Refresh tokens enable session continuity while maintaining short-lived access tokens.

Federation and Trust

• Identity Federation across different Open Dataspaces operating organizations SHOULD be supported.

  • Rationale: Future interoperability is necessary.

• In a federated environment, the subject identifier SHOULD be in a format that enables identification of the issuing authority.

  • Rationale: To prevent subject collisions during inter-Open Dataspaces collaboration.

• Third-party trust mechanisms (e.g., PKI, DAPS, or equivalent trust infrastructures) MAY be used.

  • Rationale: This allows flexibility according to governance models and organizational trust policies.

Message Types

The following message types are handled by this protocol.

Type	Direction	Description
Request	Client ⇒ Identity & Trust（L3）	A message sent by the Client to request authentication or authorization. It includes authentication information and request parameters.
Response	Identity & Trust（L3） ⇒ Client	A message sent by the Identity & Trust（L3） in response to a request. It may include authentication results, tokens, or error information.
Callback	Identity & Trust（L3） ⇒ Client	A message issued by the Identity & Trust（L3） (IdP role) when returning an authorization code during an authorization flow.

Protocol Flow

The following sequence illustrates a representative authentication scenario using the Authorization Code Flow for a natural person.

1. Client requests authentication screen URL

   Client ⇒ Identity & Trust（L3）: Request authentication screen URL

   {
     "client_id": "abc123xyz",
     "redirect_uri": "https://example.com/home",
     "code_challenge": "IevIR0cQsAuNuPha71dAbjkT-sipaqXEquPhtCqKL80"
   }

   • client_id: ID issued per client

   • redirect_uri: URI to redirect after authentication

   • code_challenge: PKCE challenge string

2. Identity & Trust（L3） returns authentication screen URL

   Identity & Trust（L3） ⇒ Client: Return authentication screen URL

   {
     "type": "https://api.example.com/success",
     "title": "Request processed successfully",
     "status": 200,
     "detail": "time_stamp:2024-10-02T02:26:57.512Z, method:POST",
     "data": {
       "url": "https://ods.com/realms/myrealm/protocol/openid-connect/auth?client_id=myclient&response_type=code&scope=openid&redirect_uri=https%3A%2F%2Fmyapp.com%2Fhome"
     }
   }

   • url: Authentication screen URL

3. User enters credentials in browser

   User Browser ⇒ Identity & Trust（L3）: Authentication request

   "login_user_id": "login_user_id_12345",
   "password": "xx@&&1234Pass"

4. Identity & Trust（L3） returns authorization code

   Identity & Trust（L3） ⇒ User Browser: Authorization code response

   https://example.com/home?code=2c0d0237-9dc1-41da-86f3-d023ae599321.dc903c2f-9042-4940-869e-c0d753107b7f.0c395f1b-8931-467f-bf6a-db561be9742f&state=xyz123

5. Client exchanges authorization code for tokens

   Client ⇒ Identity & Trust（L3）: Token request

   {
     "code": "2c0d0237-9dc1-41da-86f3-d023ae599321.dc903c2f-9042-4940-869e-c0d753107b7f.0c395f1b-8931-467f-bf6a-db561be9742f",
     "client_id": "abc123xyz",
     "client_secret": "abc123xyz",
     "redirect_uri": "https://example.com/home",
     "code_verifier": "IevIR0cQsAuNuPha71dAbjkT-sipaqXEquPhtCqKL80"
   }

   • code: Authorization code issued when redirected to the redirect URI

   • client_id: ID issued for each client

   • client_secret: Secret issued for each client

   • redirect_uri: Redirect URI specified when obtaining the authorization code

   • code_verifier: PKCE code challenge string specified when obtaining the authorization code

6. Identity & Trust（L3） returns tokens

   Identity & Trust（L3） ⇒ Client: Authentication response

   {
     "type": "https://api.example.com/success",
     "title": "Request processed successfully",
     "status": 200,
     "detail": "time_stamp:2024-10-02T02:26:57.512Z, method:POST",
     "data": {
       "access_token": "eyJhbGciOiJSUzI1NiIsInR5cC...HiFZcDhzDEg",
       "expires_in": 300,
       "token_type": "Bearer",
       "not_before_policy": 0,
       "scope": "openid scope1 scope2",
       "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5...9w67QsdnDQ",
       "refresh_expires_in": 3600,
       "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...IiwibWFuYWdlL"
     }
   }

   • access_token: Access token

   • expires_in: Access token expiration time (seconds)

   • token_type: Access token type

   • not_before_policy: Access token validity start time

   • scope: Client scope

   • refresh_token: Refresh token obtained from the IDP

   • refresh_expires_in: Refresh token expiration time (seconds)

   • id_token: ID token

State Machine

States

This section describes the states handled by this protocol.

State	Description
UNAUTHENTICATED	No token exists. Before authentication.
AUTHENTICATING	Authentication is in progress at the IdP (authentication via the /auth/token and /auth/token/client endpoints).
AUTHENTICATED	The access token is valid. Normal API calls are possible.
TOKEN_EXPIRED	The access token has expired. Token refresh using a refresh token or re-authentication is required.
TERMINATED	The session or token has been invalidated (e.g., logout, revocation, or refresh failure) and re-authentication is required.

Error Handling

This section describes the error handling used in this protocol.

Error Type	Description	Handling
Invalid Request	Returned when parameters are invalid or required fields are missing.	Reconfirm the input content, set the correct values, and resend the request.
Token Configuration Error	Returned when the access token is not set or is invalid.	Reacquire and reset the access token (re-login or refresh the token as necessary), and resend the request.
Insufficient Permission Error	Returned when required permissions are insufficient.	Notify that the operation is not permitted. Since resending will not succeed, do not resend the request.
Resource Not Found Error	Returned when the target resource does not exist.	Notify that the resource does not exist. Since resending will not succeed, do not resend the request.
Data Inconsistency Error	Returned in cases such as duplicate data or concurrency control conflicts.	Retrieve the latest data, resolve the conflict, and resend the request.
Request Format Error	Returned when an unsupported request format is specified.	Set the correct Content-Type and resend the request.
System Error	Returned when an abnormality occurs inside the server.	If the error continues to occur, notify the system administrator. Whether to resend depends on the operation performed.
External System Error	Returned when an abnormality occurs outside the server.	Retry (resend) at fixed intervals. If the issue is not resolved, notify the user to retry after some time and notify the system administrator.