FSC - Delegation

Vereniging van Nederlandse Gemeenten Standard
Proposed recommendation

This version:
https://commonground.gitlab.io/standards/fsc/
Latest published version:
https://commonground.gitlab.io/standards/fsc/
Previous version:
https://commonground.gitlab.io/standards/fsc/
Editor:
VNG Realisatie (VNG)
Authors:
Eelco Hotting (Hotting IT), Email
Ronald Koster (PhillyShell), Email
Henk van Maanen (AceWorks), Email
Niels Dequeker (ND Software), Email
Edward van Gelderen (vanG IT), Email
Pim Gaemers (Apily), Email

Abstract

The Delegation is an extension on the Federated Connectivity (FSC) Standard FSC Core. It can only be used in addition to the FSC Core specification. It extends the FSC standard by providing additional capabilities for delegating actions within a FSC Group. FSC Core's primarily concerns are Service Publication and Service Connections. This Delegation extension extends this core functionality by describing Peers to publish a service on behalf of another Peer and secondly to connect to a service on behalf of another Peer.

These Delegation privileges are described in the contracts negotiated between Peers. All three Peers in a delegation based contract need to agree and sign the contract before it becomes active and can be used.

The delegated service connections and service publication leverage the cryptographic practices established in FSC Core specification. Ensuring the delegation standard offers the same level of integrity and confidentiality as the FSC Core specification.

Status of This Document

This is the definitive concept of this document. Edits resulting from consultations have been applied.

1. Introduction

This RFC is an extension of the Federated Service Connectivity (FSC) Core specification. This extension describes how two types of rights can be delegated between Peers of a Group;

  1. The right to connect to a Service on behalf of a Peer.
  2. The right to offer a Service to the Group on behalf of a Peer.

1.1 Purpose

Organizations hire subcontractors to manage their software solutions. Which means, in an API driven landscape, that subcontractors will use and offer APIs on behalf of an organization. This delegation layer is seldom represented in the technical implementation which makes control, (e.g. GDPR compliancy) quite difficult. Additionally, unsafe practices are being adopted to act on behalf of other organizations. E.g. sharing X.509 certificates with their corresponding Private Keys.

The Delegation specification aims to make the delegation of rights transparent, manageable and secure. Actions preformed between organizations who adhere to the FSC standard must be auditable.

1.2 Overall Operation of Delegation

This extension contains two different types of delegation which can be delegated between Peers of a Group:

  1. A Peer is allowed to connect to a Service on behalf of another Peer.
  2. A Peer is allowed to publish a Service to the Group on behalf of another Peer.

Peers create Contracts with Grants containing the specifics of a delegation. Peers operate using their own identity(i.e. X.509 Certificate) and use Contracts to prove that a delegation is allowed.

1.3 Terminology

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.

Delegator:

A Peer who delegates a connection authorization to a Service or the right to publish a Service to another Peer.

Delegatee:

A Peer who acts on behalf of another Peer.

DelegatedServiceConnectionGrant:

A Grant which specifies the authorization of one Peer to connect to a Service on behalf of another Peer.

DelegatedServicePublicationGrant:

A Grant which specifies the authorization of one peer to publish a Service to the Group on behalf of another Peer.

1.4 Architecture

1.4.1 Delegate the right to connect to a Service

The Peer who acts as the Delegator creates a new Contract between the Delegator, the Delegatee and the Peer who provides the Service. This Contract contains a DelegatedServiceConnectionGrant.

The DelegatedConnectionGrant defines the Delegatee who can connect to the Service on behalf of the Delegator.

The Contract is distributed among the three Peers. Once the Contract is signed by all the Peers, the Delegatee can connect to the Service on behalf the Delegator.

Delegate connection
Figure 1 Delegate a connection

1.4.2 Delegate the right to publish a Service

The Peer who acts as the Delegator creates a new Contract between the Delegator, the Delegatee and Directory Peers. This Contract contains a DelegatedServicePublicationGrant

The DelegatedServicePublicationGrant defines the Delegatee who can publish the Service on behalf of the Delegator.

The Contract is distributed among the three Peers. Once the Contract is signed by all the Peers, the Service is published in the Directory.

Delegate Service publication
Figure 2 Delegate Service publication

1.4.3 Creating a connection to a Service that is offered on behalf of another Peer

The Delegatee is responsible for managing Contracts containing ServiceConnectionGrants which specify the right to connect to the Service. More information is available in the Creating a Connection to a Service section of Core.

2. Architecture

2.1 Delegate the right to connect to a Service

The Peer who acts as the Delegator creates a new Contract between the Delegator, the Delegatee and the Peer who provides the Service. This Contract contains a DelegatedServiceConnectionGrant.

The DelegatedConnectionGrant defines the Delegatee who can connect to the Service on behalf of the Delegator.

The Contract is distributed among the three Peers. Once the Contract is signed by all the Peers, the Delegatee can connect to the Service on behalf the Delegator.

Delegate connection
Figure 3 Delegate a connection

  1. The Delegator creates a Contract with a Delegated Service Connection Grant which contains the details of the Service and the Peer who will be acting as Delegatee (who will consume the Service).
  2. The Delegator adds its own accept signature to the Contract.
  3. The Delegator sends the Contract and accept signature to the Delegatee.
  4. The Delegatee adds its own accept signature.
  5. The Delegatee sends the accept signature to the Delegator.
  6. The Delegatee sends the accept signature to the Service Provider.
  7. The Delegator sends the Contract and accept signature to the Service Provider.
  8. The Service Provider adds its own accept signature.
  9. The Service Provider sends the accept signature to the Delegatee.
  10. The Service Provider sends the accept signature to the Delegator.

2.2 Delegate the right to publish a Service

The Peer who acts as the Delegator creates a new Contract between the Delegator, the Delegatee and Directory Peers. This Contract contains a DelegatedServicePublicationGrant

The DelegatedServicePublicationGrant defines the Delegatee who can publish the Service on behalf of the Delegator.

The Contract is distributed among the three Peers. Once the Contract is signed by all the Peers, the Service is published in the Directory.

Delegate Service publication
Figure 4 Delegate Service publication

  1. The Delegator creates a Contract with a Delegated Service Publication Grant which contains the details of the Service and the Peer who will be acting as Delegatee (who will publish the Service).
  2. The Delegator adds its own accept signature to the Contract.
  3. The Delegator sends the Contract and accept signature to the Delegatee.
  4. The Delegatee adds its own accept signature.
  5. The Delegatee sends the accept signature to the Directory.
  6. The Delegatee sends the accept signature to the Delegator.
  7. The Delegator sends the Contract and accept signature to the Directory.
  8. The Directory adds its own accept signature.
  9. The Directory sends the accept signature to the Delegator.
  10. The Directory sends the accept signature to the Delegatee.

2.3 Creating a connection to a Service that is offered on behalf of another Peer

The Delegatee is responsible for managing Contracts containing ServiceConnectionGrants which specify the right to connect to the Service. More information is available in the Creating a Connection to a Service section of Core.

3. Specification

3.1 Grants

3.1.1 DelegatedServiceConnectionGrant

The Delegatee is the Peer specified in grant.data.outway.peer_id The Delegator is the Peer specified in grant.data.delegator.peer_id

Validation rules:

  • The Peer ID provided by the X.509 certificate used by the Manager of the Peer creating the delegation matches the value of the field grant.delegator.peer_id
  • The Peer ID provided by the X.509 certificate used by the Manager consuming the DelegatedServiceConnectionGrant matches with the value of the field grant.outway.peer_id
  • The Peer ID provided by the X.509 certificate used by the Manager of the Peer providing the Service matches with the value of the field grant.data.service.peer_id
  • The validation rules of the fields Outway and Service of the ServiceConnectionGrant described in Core must be applied to corresponding fields grant.data.outway and grant.data.service of the DelegatedServiceConnectionGrant

Signature requirements:

  • A signature is present with the subject serial number of the Peer defined the field grant.data.outway.peer_id
  • A signature is present with the subject serial number of the Peer defined the field grant.data.delegator.peer_id
  • A signature is present with the subject serial number of the Peer defined the field grant.data.service.peer_id

3.1.2 DelegatedServicePublicationGrant

The Delegatee is the Peer specified in grant.data.service.peer_id The Delegator is the Peer specified in grant.data.delegator.peer_id

Validation rules:

  • The Peer ID provided by the X.509 certificate used by the Manager creating the delegation matches the value of the field grant.data.delegator.peer_id
  • The Peer ID provided by the X.509 certificate used by the Manager of the Directory Peer matches the value of the field grant.data.directory.peer_id
  • The Peer ID provided by the X.509 certificate used by the Manager providing the Service matches the value of the field grant.data.service.peer_id
  • The validation rules of the field Service of the ServicePublicationGrant described in Core must be applied to the field grant.data.service of the DelegatedServicePublicationGrant

Signature requirements:

  • A signature is present with the subject serial number of the Peer defined the field grant.data.service.peer_id
  • A signature is present with the subject serial number of the Peer defined the field grant.data.directory.peer_id
  • A signature is present with the subject serial number of the Peer defined the field grant.data.delegator.peer_id

3.2 Access token JWT Payload

The JWT payload for the access token described in Core MUST be extended with the pdi(publication Delegator ID) and act(actor) claims section 4.1 of [RFC8693], which can be optionally set in case of Delegation.

example delegatedServiceConnection grant: PeerID: 00000000000000000003 is connecting to a service on behalf of PeerID: 00000000000000000002 (00000000000000000002 delegates the serviceconnection to 00000000000000000003)

{
  "sub": "00000000000000000002",
  "act": {
    "sub": "00000000000000000003"
  }
}

Other claims are not shown for brevity.

example delegatedServicePublication grant: PeerID:00000000000000000001 is offering a service on behalf of PeerID: 00000000000000000002 (00000000000000000002 delegates the servicepublication to 00000000000000000001)

{
  "iss": "00000000000000000001",
  "pdi": "00000000000000000002"
}

Other claims are not shown for brevity.

3.3 Manager

The FSC delegation specification requires the Manager described in Core to be implemented.

3.3.1 Behavior

3.3.1.1 Contracts

The Manager MUST be able to validate and sign Contracts containing DelegatedServiceConnectionGrants and DelegatedServicePublicationGrants.

The Manager MUST validate DelegatedServiceConnectionGrants using the rules described in the DelegatedServiceConnectionGrant.

The Manager MUST validate DelegatedServicePublicationGrants using the rules described in the DelegatedServicePublicationGrant.

3.3.1.2 Tokens

The Manager MUST be able to provide an access token to Peers that have a valid Contract containing a DelegatedServiceConnectionGrant.

Before issuing an access token the Manager MUST validate that:

  1. A valid Contract exists with a DelegatedServiceConnectionGrant matching the Grant hash in the access token request.
  2. The Manager is provided by a Peer with the same PeerID as specified in grant.data.service.peer_id.
  3. The Manager is provided by a Peer who has an Inway which is offering the Service specified in grant.data.service.name.
  4. The Peer ID provided by the X.509 certificate used by the Outway requesting the access token matches the value of the field grant.data.outway.peer_id.
  5. The thumbprint of the X.509 certificate used by the Outway requesting the access token matches the value of the field grant.data.outway.certificate_thumbprint.

The act claim MUST be set when an access token is generated for a Peer who is connecting to the Service on behalf of another Peer. I.e. the authorization to connect has been granted using a DelegatedServiceConnectionGrant.

The pdi claim MUST be set when an access token is generated for a Service which is being offered on behalf of another Peer. I.e. The Service is published using a DelegatedServicePublicationGrant.

3.3.2 Interfaces

3.3.2.1 GrantTypes

In addition to the Grants defined in Core, the FSC Delegation extension requires that the Manager implements two additional Grant Types defined in the OpenAPI Specification as grantDelegatedServiceConnection and grantDelegatedServicePublication.

3.4 Directory

The FSC delegation specification requires the Directory described in Core to be implemented.

3.4.1 Behavior

3.4.1.1 Accepting a delegated Service publication

The Directory MUST be able to sign and validate Contracts containing a DelegatedServicePublicationGrant.

The Directory MUST validate the DelegatedServicePublicationGrant in the Contract using the rules described in the GrantDelegatedServicePublication.

The Directory MUST publish the Service when the signatures of the involved Peers are present and the Contract containing the DelegatedServicePublicationGrant is valid.

The Directory MUST stop publishing the Service when a revoke signature is received for the Contract containing the DelegatedServicePublicationGrant.

3.4.1.2 Listing delegated Services

The Directory MUST list a Service that is offered on behalf of another Peer as a delegatedServiceListing as specified in the OpenAPI Specification.

The delegatedServiceListing.delegator.peer_id field MUST contain the ID of the Peer that acts as the Delegator. I.e. the value of grant.data.delegator.peer_id

The delegatedServiceListing.delegator.name field MUST contain the name of the Peer that acts as the Delegator.

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key word MUST in this document is to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

5. List of Figures

A. References

A.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[RFC8693]
OAuth 2.0 Token Exchange. M. Jones; A. Nadalin; B. Campbell, Ed.; J. Bradley; C. Mortimore. IETF. January 2020. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8693
Vereniging van Nederlandse Gemeenten Standard - Proposed recommendation