FSC - External Contract Reference 1.0.0

In delegation as defined by FSC Core, the delegator organization MUST use a FSC Manager to create and sign Contracts. This extension addresses scenarios where the delegator lacks the technical capability to operate FSC infrastructure, allowing a delegatee (API provider or consumer) to act based on an external contract.

An API provider creates a Contract using a ServicePublicationGrant. In this Contract the API provider adds a reference to an existing (paper) contract using Properties. The Contract is received by the Peer acting as Directory. The Peer validates the reference manually or automatically, outside FSC with a custom component. The validation itself is out of scope for this extension. The Contract is accepted and the Service is published on behalf of the organization specified in the reference.

An API consumer creates a Contract with a ServiceConnectionGrant. In this Contract the API consumer adds a reference to an existing (paper) contract using Properties. The Contract is received by the API provider. The API provider validates the reference manually or automatically, outside FSC with a custom component. After validation the Contract is accepted and the API consumer can consume the Service on behalf of the organization specified in the reference.

This extension is developed as a temporary solution because external contracts defined in this extension cannot be validated by FSC components. This breaks the trust. In the future, this extension will be replaced by an extension that allows Delegators to sign contracts in a cryptographically secure manner without having to use an FSC Manager.

This section lists terms (#header) and abbreviations that are used in this document. This document assumes that the reader is familiar with the Terminology of FSC Core.

contract:

contract without a capital C is a contract that is not defined by FSC.

The key architectural principle is trust transfer: the delegatee asserts authority to act on behalf of the delegator, backed by an external contract reference. The receiving party (Directory or API provider) performs validation of this assertion before accepting the Contract.

API providers can use the delegation.connection.external_contract_reference added in the prp of the access token to:

• perform additional authorization
• offer functionality based on the identity of the delegator

The architectural flow of external contract reference properties through the system:

1. Creation: Properties defined in ServicePublicationGrant or ServiceConnectionGrant
2. Contract Storage: Properties stored with the Contract in the Manager
3. Access Token Generation (for service connections only): Properties included in prp claim when API consumer requests access
4. Service Request: Access token with properties sent to Inway of the API provider
5. Transaction Logging: Properties extracted and logged in transaction log as additional_data

This end-to-end propagation ensures complete traceability and auditability of delegated service access.

This extension integrates with FSC Core as follows:

• Section 3.2 (Contract Management): Adds optional properties to ServicePublicationGrant and ServiceConnectionGrant
• Section 3.6 (Delegation): Provides an alternative delegation mechanism for organizations that cannot operate FSC Managers
• Section 3.8 (Authorization): External Contract Reference properties in access tokens enable fine-grained authorization decisions
• Transaction Log Extension: Defines how External Contract References are logged for auditability

The External Contract Reference can be added to the ServiceConnectionGrant and ServicePublicationGrant using Properties. The Grants and Properties are both defined in FSC Core.

{
    "delegation.connection.external_contract_reference": {
        "reference": "https://linktocontract.nl/1",
        "delegator_id": "12345678901234567890",
        "delegator_name": "Example organisation"
    }
}

{
    "delegation.publication.external_contract_reference": {
        "reference": "https://linktocontract.com/1",
        "delegator_id": "12345678901234567890",
        "delegator_name": "Example organisation"
    }
}

In Groups that use the Transaction log extension the External Contract Reference properties MUST be stored as additional_data in the transaction log.

Example Transaction Log record:

{
    "transaction_id": "019a7dea-9048-7c4d-9e66-4d3f75a18f58",
    "direction": "DIRECTION_INCOMING",
    "grant_hash": "$1$4$+PQI7we01qIfEwq4O5UioLKzjGBgRva6F5+bUfDlKxUjcY5yX1MRsn6NKquDbL8VcklhYO9sk18rHD6La3w/mg",
    "source": {
        "type": "SOURCE_TYPE_SOURCE",
        "outway_peer_id": "12345678901234567891"
    },
    "destination": {
        "type": "DESTINATION_TYPE_DESTINATION",
        "service_peer_id": "12345678901234567891"
    },
    "service_name": "random_service_name",
    "additional_data": {
        "delegation.connection.external_contract_reference": {
            "reference": "https://linktocontract.com/1",
            "delegator_id": "12345678901234567890",
            "delegator_name": "Example organization"
        } 
    }
    "created_at": 1672527600
}

The External Contract Reference properties are added to the Access Token. FSC Core defines that properties added to a Grant MUST be added the access token as the prp claim.

Example access token bases on a ServiceConnectionGrant with an External Contract Reference.

{
    "gid": "fsc.group.example.id",
    "gth": "$1$3$n4kellB6p2-VjrriscICkH3P5flgMmG6rX7MFIF3cU2Y2OVysoU6W903TkGCH3u_bB1XhOgdOVFhLCVj1iFnNg",
    "sub": "12345678901234567890",
    "iss": "12345678901234567891",
    "svc": "test",
    "aud": "https://inway.organization-b.open-fsc.localhost:443",
    "exp": 1493726400,
    "nbf": 1493722800,
    "cnf": {
        "x5t#S256": "06QekfpQ2IkYWhXyZqz3T1llvPEqDYYO0UyETSr7QdU"
    },
    "prp": {
        "delegation.connection.external_contract_reference": {
            "reference": "https://linktocontract.com/1",
            "delegator_id": "12345678901234567893",
            "delegator_name": "Example organization"
        }
    }
}

The Inway MUST include External Contract Reference properties in the Transaction Log records as additional_data when the Logging extension is used.

The Outway MUST include External Contract Reference properties in the Transaction Log records as additional_data when the Logging extension is used.