# Authorization strategy

This authorization strategy extended the [authentication strategy](https://docs.dfc-standard.org/dfc-standard-documentation/~/revisions/DKAHkT2dyiZPnluC5xvV/technical-specifications/authentication-strategy) 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dfc-standard.org/dfc-standard-documentation/~/revisions/DKAHkT2dyiZPnluC5xvV/technical-specifications/authorization-strategy.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.