Auth scope changes

SUMMARY.md

@@ -13,6 +13,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)

technical-specifications/authentication-strategy.md

@@ -1,25 +1,71 @@
 # 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.
+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).
 
-It will allow us to separate the authentication layer from the business logic one by calling a third-party application.
+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.
 
-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 <token>` (*\<token\>* 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/).
+The DFC OIDC implementation currently identifies the user using its email address. 
 
-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).
+**TODO: put an example of a DFC token here**
 
-## 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
+
+This section has to be written.
+
+# 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/)

technical-specifications/authorization-strategy.md

@@ -0,0 +1,44 @@
+# 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 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.
+
+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, Transformation, ConsumptionFlow, ProductionFlow |
+| Price | Offer, Price |
+| Order | Order, OrderLine, SaleSession, FulfilmentStatus, PaymentStatus, OrderStatus, Coordination, ShippingOption, Place, PhysicalPlace |
+
+## Implementation of scopes by Relying Parties
+
+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 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.