From 67c957c74b76d66bd1f717c203dd06714faac5a7 Mon Sep 17 00:00:00 2001 From: Garethe Date: Thu, 2 Oct 2025 15:48:50 +0100 Subject: [PATCH 1/6] Added Authorization Strategy Entry --- SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/SUMMARY.md b/SUMMARY.md index d0d4edd..304278c 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -12,6 +12,7 @@ * [Decentralized identifier matching reference system](technical-specifications/decentralised-identifier-matching-reference-system.md) * [Specifics API](technical-specifications/non-ldp-api.md) * [Authentication strategy](technical-specifications/authentication-strategy.md) + * [Authorization strategy](technical-specifications/authorization-strategy.md) * [Architecture representations](technical-specifications/architecture-representations.md) * [Order states](technical-specifications/order-states.md) * [Prototype specifications](prototype-specifications.md) From 29fc8fc4359d4862a893fe6d9354f0a8686651d5 Mon Sep 17 00:00:00 2001 From: Garethe Date: Thu, 2 Oct 2025 15:49:29 +0100 Subject: [PATCH 2/6] Initial Authorization Strategy, covering scopes & linking out to Data Sharing Module. --- .../authorization-strategy.md | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 technical-specifications/authorization-strategy.md diff --git a/technical-specifications/authorization-strategy.md b/technical-specifications/authorization-strategy.md new file mode 100644 index 0000000..61027ad --- /dev/null +++ b/technical-specifications/authorization-strategy.md @@ -0,0 +1,36 @@ +# Authorization Strategy + +To manage authorization of requests across the DFC standard, it is necessary to apply authorization scopes to each request. These scopes determine whether an authenticated request can access certain data from DFC endpoints. + +## Scope based authorization + +We propose a scope-based approach to authorization. Based on OAuth2 authorization logic, these form part of the OpenID Connect protocol already adopted for Authentication. These scopes further restrict access to specific operations on certain endpoints within the DFC standard. + +Scopes are managed by the OpenID Provider (DFC implmentations often use Keycloak) as client scopes. + +Scopes are formed of an action & a subject: + +### Actions + +Actions define the permitted operations a request can perform, these are: +1. **Read** - authorised to HEAD + GET +2. **Write** - authorised to POST + PUT + PATCH (if supported) +3. **Delete** - authorised to DELETE + +### Subjects + +Subjects define which endpoints authorization is granted to. Subjects are: + +| **Subject** | **Endpoints accessible with subject** | +| --- | --- | +| Enterprise | Enterprise, Address, SocialMedia, PhoneNumber, CustomerCategory, Coordination, Place | +| Product | TechnicalProduct, LocalizedProduct, SuppliedProduct, Catalog, CatalogItem, Offer, Price, Transformation, ConsumptionFlow, ProductionFlow | +| Order | Order, OrderLine, SaleSession, FulfilmentStatus, PaymentStatus, OrderStatus, Coordination, ShippingOption, Place, PhysicalPlace | + +## Implmentation of scopes by Relying Parties + +Relying Parties (RP's), typically platforms implmenting the DFC standard, must implement security constraints on all DFC endpoints to ensure all requests have the appropriate scope for the action/subject combination. + +Furthermore it is recommended that RP's implment a data consent system, whereby data owners can grant (and revoke) access to these scopes for individual clients/users within the OIDC domain. For example a portal wishing to read data on a users Enterprise and Products, might request `ReadEnterprise` and `ReadProduct` access. The RP should record which Enterprises have authorized a specific client or user to which scopes. + +The DFC community provides a web component that can support RP's with this workflow: the [Data Sharing Module](https://github.com/startin-blox/data-sharing-module/) has full instructions on how to implment & manage scope permissions for users on your platform. From 24324b6c3d2896f88aec2a7fc97893150e8c7eee Mon Sep 17 00:00:00 2001 From: Garethe Date: Tue, 18 Nov 2025 14:54:26 +0000 Subject: [PATCH 3/6] Incorpated review feedback. --- .../authorization-strategy.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/technical-specifications/authorization-strategy.md b/technical-specifications/authorization-strategy.md index 61027ad..efcffe5 100644 --- a/technical-specifications/authorization-strategy.md +++ b/technical-specifications/authorization-strategy.md @@ -1,7 +1,10 @@ -# Authorization Strategy +# Authorization Strategy Recommendation To manage authorization of requests across the DFC standard, it is necessary to apply authorization scopes to each request. These scopes determine whether an authenticated request can access certain data from DFC endpoints. +**These authorization extensions to the [authentication strategy](./authentication-strategy.md) are transitional recommendations, and are intended to be superceded by a more granular permissioning protocol in a future version of the DFC standard.** + + ## Scope based authorization We propose a scope-based approach to authorization. Based on OAuth2 authorization logic, these form part of the OpenID Connect protocol already adopted for Authentication. These scopes further restrict access to specific operations on certain endpoints within the DFC standard. @@ -24,13 +27,14 @@ Subjects define which endpoints authorization is granted to. Subjects are: | **Subject** | **Endpoints accessible with subject** | | --- | --- | | Enterprise | Enterprise, Address, SocialMedia, PhoneNumber, CustomerCategory, Coordination, Place | -| Product | TechnicalProduct, LocalizedProduct, SuppliedProduct, Catalog, CatalogItem, Offer, Price, Transformation, ConsumptionFlow, ProductionFlow | +| Product | TechnicalProduct, LocalizedProduct, SuppliedProduct, Catalog, CatalogItem, Transformation, ConsumptionFlow, ProductionFlow | +| Price | Offer, Price | | Order | Order, OrderLine, SaleSession, FulfilmentStatus, PaymentStatus, OrderStatus, Coordination, ShippingOption, Place, PhysicalPlace | -## Implmentation of scopes by Relying Parties +## Implementation of scopes by Relying Parties -Relying Parties (RP's), typically platforms implmenting the DFC standard, must implement security constraints on all DFC endpoints to ensure all requests have the appropriate scope for the action/subject combination. +Relying Parties (RP's), typically platforms implementing the DFC standard, must implement security constraints on all DFC endpoints to ensure all requests have the appropriate scope for the action/subject combination. -Furthermore it is recommended that RP's implment a data consent system, whereby data owners can grant (and revoke) access to these scopes for individual clients/users within the OIDC domain. For example a portal wishing to read data on a users Enterprise and Products, might request `ReadEnterprise` and `ReadProduct` access. The RP should record which Enterprises have authorized a specific client or user to which scopes. +Furthermore it is recommended that RP's implement a data consent system, whereby data owners can grant (and revoke) access to these scopes for individual clients/users within the OIDC domain. For example a portal wishing to read data on a users Enterprise and Products, might request `ReadEnterprise` and `ReadProduct` access. The RP should record which Enterprises have authorized a specific client or user to which scopes. -The DFC community provides a web component that can support RP's with this workflow: the [Data Sharing Module](https://github.com/startin-blox/data-sharing-module/) has full instructions on how to implment & manage scope permissions for users on your platform. +Startin' Blox have supported members of the DFC community by providing a web component (funded by coopcircuits) that can support RP's with this workflow: the [Data Sharing Module](https://github.com/startin-blox/data-sharing-module/) has full instructions on how to implment & manage scope permissions for users on your platform. From e6e85629e1a0cb4b0573c9d661fbd0e09fe2e66e Mon Sep 17 00:00:00 2001 From: Garethe Date: Tue, 18 Nov 2025 15:01:18 +0000 Subject: [PATCH 4/6] Incorporated @simonLouvet 's requested changes. --- technical-specifications/authorization-strategy.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/technical-specifications/authorization-strategy.md b/technical-specifications/authorization-strategy.md index efcffe5..e3013b5 100644 --- a/technical-specifications/authorization-strategy.md +++ b/technical-specifications/authorization-strategy.md @@ -1,8 +1,10 @@ # Authorization Strategy Recommendation +This authorization strategy extended the [authentication strategy](./authentication-strategy.md) to allow platforms to grant permissions to individual endpoints and Organizations within the DFC Standard. + To manage authorization of requests across the DFC standard, it is necessary to apply authorization scopes to each request. These scopes determine whether an authenticated request can access certain data from DFC endpoints. -**These authorization extensions to the [authentication strategy](./authentication-strategy.md) are transitional recommendations, and are intended to be superceded by a more granular permissioning protocol in a future version of the DFC standard.** +**These are transitional recommendations, and are intended to be superceded by a more granular permissioning protocol in a future version of the DFC standard.** ## Scope based authorization @@ -35,6 +37,8 @@ Subjects define which endpoints authorization is granted to. Subjects are: Relying Parties (RP's), typically platforms implementing the DFC standard, must implement security constraints on all DFC endpoints to ensure all requests have the appropriate scope for the action/subject combination. -Furthermore it is recommended that RP's implement a data consent system, whereby data owners can grant (and revoke) access to these scopes for individual clients/users within the OIDC domain. For example a portal wishing to read data on a users Enterprise and Products, might request `ReadEnterprise` and `ReadProduct` access. The RP should record which Enterprises have authorized a specific client or user to which scopes. +Furthermore it is recommended that RP's implement a data consent system, whereby data owners can grant (and revoke) access to these scopes for individual clients/users within the OIDC domain. For example a portal wishing to read data on a users Organization and Products, might request `ReadEnterprise` and `ReadProduct` access. The RP should record which Organizations have authorized a specific client or user to which scopes. + +These authorizations can be communicated via properties within the dfc-t Technical Ontology. Specifically `dfc-t:assignedScope` gives details of which scopes have been granted to a client/user by an Organization, and `dfc-t:requiredScope` gives details of which scopes a client/user is requesting from an Organization. Startin' Blox have supported members of the DFC community by providing a web component (funded by coopcircuits) that can support RP's with this workflow: the [Data Sharing Module](https://github.com/startin-blox/data-sharing-module/) has full instructions on how to implment & manage scope permissions for users on your platform. From 4d8b5ebe40d90ba8d5727a954675799a6cd9345d Mon Sep 17 00:00:00 2001 From: Maxime Lecoq-Gaillard Date: Fri, 6 Mar 2026 17:51:06 +0100 Subject: [PATCH 5/6] Rewrite authentication strategy --- .../authentication-strategy.md | 68 +++++++++++++++---- 1 file changed, 56 insertions(+), 12 deletions(-) diff --git a/technical-specifications/authentication-strategy.md b/technical-specifications/authentication-strategy.md index d9791a5..b88cef3 100644 --- a/technical-specifications/authentication-strategy.md +++ b/technical-specifications/authentication-strategy.md @@ -1,25 +1,69 @@ # Authentication strategy -## OpenID protocol +The current consensus at DFC about authentication relies on the [OpenID Connect (OIDC)](#openid-connect-protocol-oidc) protocol. -In order to manage authentication, we decide to support the [OpenID protocol](https://openid.net/connect/) which is a layer on top of [OAuth2 protocol](https://oauth.net/2/). +Despites OIDC is centralized it stays relatively simple and has been proven reliable and robust since it is used by many actors of the Web for years. -This technology is active since years and heavily supported by many big actors of the Web. +The DFC OIDC implementation currently identifies the user with its email address. As we now support WebIDs it can make sense to move to Solid-OIDC to identify the user with its WebID. -It will allow us to separate the authentication layer from the business logic one by calling a third-party application. +Decentralized authentication mechanisms exist like the [Decentralized Identifiers W3C standard](#decentralized-identifiers) but it is more complicated to set up and quite new (2022). The DFC consensus might evolve to use this kind of authentication in the future. -Each platform wishing to join the project must create a client on the server of our partner lescommuns.org. Contact the DFC team for this. +## OpenID Connect (OIDC) -OIDC is federeted and centralized athentification protocol. Other decentralized protocol as WebID-OIDC or DID exists but are not mature. +The [OpenID Connect (OIDC)](https://openid.net/connect/) is an authentication layer on top of the [OAuth2](https://oauth.net/2/) authorization framework. Clients implementing OIDC do delegate the authentication to a third-party application that allows the user to authenticate. Once the user is logged in a token is returned to the client so it can perform authenticated requests to access to protected resources. -## JWT token +The OpenID authentication is based on the exchange of tokens following the [JSON Web Token standard](#rfc7519). Basically these tokens contains base64 encoded JSON data. A token is composed of 3 parts separated by dots: the *header*, the *payload* and the *signature*. These 3 parts are encoded using Base64url method. The algorithm used to sign DFC tokens is RS256 (RSA signature with SHA-256). DFC tokens are not encrypted. The header sent to your platform will look like `Authorization: JWT ` (*\* will be replaced by the actual token in clear, base64 encoded). You can use https://jwt.io/ to play with JWT tokens. Tools like Insomnia or Postman can help you during the token implementation process to send and debug HTTP requests. -The OpenID authentication is based on the exchange of token based on [JSON Web Token standard](https://jwt.io/). - -Basically, these token are based on encoding JSON data into base 64. The token is signed using a public key that you can find [here](https://simonlouvet.github.io/config-private/DFC-Proto/config.json). - -## Explanatory scheme +It is very important to verify the signature to be sure that the token is coming from the DFC server. To verify the signature, you can use the openSSL verify function or use a JWT library that will do the work you you. The signature can be controlled thanks to a public key that you can find [here](https://simonlouvet.github.io/config-private/DFC-Proto/config.json) (inside the public_key field). Doing so, you would probably have to surround the key manually with its type headers (-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----). Sometimes, depending of your library, you even need to respect the .pem format by adding break line mentions in the headers (-----BEGIN PUBLIC KEY-----\n and \n-----END PUBLIC KEY-----). Nowadays, OIDC libraries can handle this token verification automatically by checking the Public key directly on the OIDC server. This method often refers as JWKS one and you have the JWKS uri for LesCommuns OIDC server here: https://login.lescommuns.org/auth/realms/data-food-consortium/protocol/openid-connect/certs. And even for more automation, the Discovery url for the Data Food Consoritum Realm is: https://login.lescommuns.org/auth/realms/data-food-consortium/.well-known/openid-configuration. ![Platform Authentificaiton not OIDC driven](../.gitbook/assets/Sélection_622.png) ![Platform Authentificaiton OIDC driven](../.gitbook/assets/Sélection_624.png) + +**Each platform wishing to join the DFC project MUST have a client configured on our Single-Sign-On server (SSO) provided by our partner lescommuns.org.** Please contact the DFC team to do so. + +To learn more about the OpenID Connect protocol you can browse the official [OpenId Connect specification](#openid-connect). To learn more about OAuth2 you can read *The OAuth 2.0 Authorization Framework* ([RFC 6749](#rfc6749)) and *The OAuth 2.0 Authorization Framework: Bearer Token Usage* ([RFC 6750](#rfc6750)). + + + +## Solid-OIDC + +TBD + +# References + +## Normative references + +### [OpenID Connect] + +OpenID Connect Core 1.0 incorporating errata set 2. URL: https://openid.net/specs/openid-connect-core-1_0-final.html. + +### [RFC6749] + +The OAuth 2.0 Authorization Framework. URL: https://datatracker.ietf.org/doc/html/rfc6749. + +### [RFC6750] + +The OAuth 2.0 Authorization Framework: Bearer Token Usage. URL: https://datatracker.ietf.org/doc/html/rfc6750. + +### [RFC7519] + +JSON Web Token (JWT). Internet Engineering Task Force (IETF). URL: https://datatracker.ietf.org/doc/html/rfc7519. + +## Informative references + +### [Decentralized Identifiers] + +Decentralized Identifiers (DIDs) v1.0 Core architecture, data model, and representations. URL: https://www.w3.org/TR/did-1.0/. + +### [Solid OIDC] + +(https://solidproject.org/TR/oidc) + +### [Solid-OIDC Primer] + +(https://solidproject.org/TR/oidc-primer) + +### [did:solid Method Specification] + +(https://solid.github.io/did-method-solid/) \ No newline at end of file From b3087f0b050a1508d8e119efd8e712489dac5c0b Mon Sep 17 00:00:00 2001 From: Maxime Lecoq-Gaillard Date: Tue, 31 Mar 2026 11:07:43 +0200 Subject: [PATCH 6/6] Mention decentralized authn systems, add details --- technical-specifications/authentication-strategy.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/technical-specifications/authentication-strategy.md b/technical-specifications/authentication-strategy.md index b88cef3..50eb8b1 100644 --- a/technical-specifications/authentication-strategy.md +++ b/technical-specifications/authentication-strategy.md @@ -4,9 +4,9 @@ The current consensus at DFC about authentication relies on the [OpenID Connect Despites OIDC is centralized it stays relatively simple and has been proven reliable and robust since it is used by many actors of the Web for years. -The DFC OIDC implementation currently identifies the user with its email address. As we now support WebIDs it can make sense to move to Solid-OIDC to identify the user with its WebID. +Decentralized authentication mechanisms exist like [Solid-OIDC](#solid-oidc). It's built on top of OIDC. As we now support [user WebIDs](data-storage-and-discovery#dfc-user-webids) it can make sense to move to Solid-OIDC to identify the user using its WebID. This document presents such an option in the Solid-OIDC [dedicated section](#solid-oidc). -Decentralized authentication mechanisms exist like the [Decentralized Identifiers W3C standard](#decentralized-identifiers) but it is more complicated to set up and quite new (2022). The DFC consensus might evolve to use this kind of authentication in the future. +Another decentralized authentication mechanisms exist like the [Decentralized Identifiers W3C standard](#decentralized-identifiers) but it is more complicated to set up. The DFC consensus might evolve to use this kind of authentication in the future. ## OpenID Connect (OIDC) @@ -14,6 +14,10 @@ The [OpenID Connect (OIDC)](https://openid.net/connect/) is an authentication la The OpenID authentication is based on the exchange of tokens following the [JSON Web Token standard](#rfc7519). Basically these tokens contains base64 encoded JSON data. A token is composed of 3 parts separated by dots: the *header*, the *payload* and the *signature*. These 3 parts are encoded using Base64url method. The algorithm used to sign DFC tokens is RS256 (RSA signature with SHA-256). DFC tokens are not encrypted. The header sent to your platform will look like `Authorization: JWT ` (*\* will be replaced by the actual token in clear, base64 encoded). You can use https://jwt.io/ to play with JWT tokens. Tools like Insomnia or Postman can help you during the token implementation process to send and debug HTTP requests. +The DFC OIDC implementation currently identifies the user using its email address. + +**TODO: put an example of a DFC token here** + It is very important to verify the signature to be sure that the token is coming from the DFC server. To verify the signature, you can use the openSSL verify function or use a JWT library that will do the work you you. The signature can be controlled thanks to a public key that you can find [here](https://simonlouvet.github.io/config-private/DFC-Proto/config.json) (inside the public_key field). Doing so, you would probably have to surround the key manually with its type headers (-----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY-----). Sometimes, depending of your library, you even need to respect the .pem format by adding break line mentions in the headers (-----BEGIN PUBLIC KEY-----\n and \n-----END PUBLIC KEY-----). Nowadays, OIDC libraries can handle this token verification automatically by checking the Public key directly on the OIDC server. This method often refers as JWKS one and you have the JWKS uri for LesCommuns OIDC server here: https://login.lescommuns.org/auth/realms/data-food-consortium/protocol/openid-connect/certs. And even for more automation, the Discovery url for the Data Food Consoritum Realm is: https://login.lescommuns.org/auth/realms/data-food-consortium/.well-known/openid-configuration. ![Platform Authentificaiton not OIDC driven](../.gitbook/assets/Sélection_622.png) @@ -24,11 +28,9 @@ It is very important to verify the signature to be sure that the token is coming To learn more about the OpenID Connect protocol you can browse the official [OpenId Connect specification](#openid-connect). To learn more about OAuth2 you can read *The OAuth 2.0 Authorization Framework* ([RFC 6749](#rfc6749)) and *The OAuth 2.0 Authorization Framework: Bearer Token Usage* ([RFC 6750](#rfc6750)). - - ## Solid-OIDC -TBD +This section has to be written. # References