Merge pull request #10 from Basic-Data-Infrastructure/authz

Restructure authorization register documentation

association-register.md

@@ -4,24 +4,36 @@ category: 4. Components
 order: 2
 ---
 
-The Association Register, unlike the Authorization Register, is a register run by a central authority. It contains a list of authorized participants in an iSHARE Data Space. For each listed participant, it stores their current compliance status, the time frame during which that status applies, their endpoint, and a list of Authorization Registries that manage access to the participants. It also contains additional information, including legal details such as agreements.
+The Association Register, unlike the Authorization Register, is a register run by a central authority. It maintains the set of trusted participants in a Data Space. For each participant, it stores their current compliance status, the time frame during which that status applies, their endpoint, and a list of Authorization Registers that manage access to the participants. It also contains additional information, including legal details such as agreements.
 
 To interact with an Association Register, clients first need to obtain a token by sending a message containing their ID, among other details, and signing it with their private key. This message is called a Client Assertion. The Association Register will use the supplied ID to look up the client's public key. With the public key, it will verify the signature. If the signature is valid and the client's current status is active, the register will generate a token, store it internally along with an expiration date, and send it to the client.
 
 With this token, clients may use the API of the Association Register. Using the [single party API-call](https://dev.ishare.eu/ishare-satellite-role/single-party), clients may access data of a specific party, specified by their [EORI-id](glossary.md#EORI).
 
+Service providers will use this call to authenticate requests from Data Consumers and can use the party info to evaluate the trust status of the consumer.
+
+Note that Data Consumers in do not need to interact with the Assocation Register directly, though they need to make sure their record is up-to-date with the Assocation.
+
 ##### Core Functions of the Association Register
 
 ###### Compliance Status Management
 
-- Compliance Status: Tracks whether a participant meets the required standards and protocols set by iSHARE.
-- Validity Period: Indicates the time frame during which the compliance status is valid. This helps ensure that participants are regularly reviewed and re-validated.
+Compliance Status: Tracks whether a participant meets the required standards and protocols set by iSHARE.
+
+Validity Period: Indicates the time frame during which the compliance status is valid. This helps ensure that participants are regularly reviewed and re-validated.
 
 ###### Participant Endpoints
-- Stores the endpoint information of each participant, enabling other participants to discover and interact with them directly.
+
+Stores the endpoint information of each participant, enabling other participants to discover and interact with them directly.
 
 ###### Authorization Register References
-- Lists the Authorization Registries associated with each participant. These registries manage detailed access control policies and permissions for data sharing.
+
+Lists the Authorization Registries associated with each participant. These registries manage detailed access control policies and permissions for data sharing.
 
 ###### Legal and Contractual Information
-- Contains agreements and legal documents that outline the terms of participation and data sharing. This ensures transparency and legal compliance among participants.
+
+Contains agreements and legal documents that outline the terms of participation and data sharing. This ensures transparency and legal compliance among participants.
+
+###### Trust roots
+
+The BDI framework makes extensive use of public-key cryptography. The Assocation Register provides a "Trusted List" of Certificate Authorities (Root CAs) that are trusted to provide certificates for registered parties.

authorization-register.md

@@ -4,10 +4,11 @@ category: 4. Components
 order: 3
 ---
 
-Within a Data Space, The Authorization Register manages and enforces access control policies. Its core functions revolve around ensuring that data access is granted based on predefined rules and that only authorized participants can access specific data or services. Here are the core functions of the Authorization Register:
+Within a Data Space, The Authorization Register manages and enforces access control policies. Its core functions revolve around ensuring that data access is granted based on predefined rules and that only authorized participants can access specific data or services.
 
-#### Core Functions of the Authorization Register
+The Basic Data Infrastructure separates the roles of Service Provider and Authorization Register, but its possible to implement a service-specific Authorization Register or to integrate the authorization mechanisms in the service (especially when adding BDI functionality to existing services).
 
+#### Core Functions of the Authorization Register
 
 ##### Access Control Policy Management:
 
@@ -19,40 +20,20 @@ Within a Data Space, The Authorization Register manages and enforces access cont
 - Request Evaluation: Evaluates access requests against the stored policies to determine whether to grant or deny access.
 - Contextual Analysis: Takes into account contextual information such as the time of request, location, and other relevant factors to make nuanced authorization decisions.
 
-##### Authentication Integration:
-
-- Identity Verification: Works in conjunction with identity providers to verify the identities of participants making access requests.
-- Credential Management: Manages the credentials (e.g., tokens, certificates) used for authentication purposes.
-
 ##### Delegation of Rights:
 
 - Delegation Support: Allows data owners to delegate access rights to other participants. This delegation can be temporary or conditional, based on specific criteria.
 - Chaining of Permissions: Supports the chaining of permissions where rights can be delegated through multiple levels of participants.
 
-##### Audit and Compliance:
-
-- Logging: Maintains detailed logs of all access requests and authorization decisions. This includes who accessed what data, when, and under what policies.
-- Compliance Reporting: Provides reports and insights to ensure compliance with regulatory requirements and internal policies.
-
 ##### Interoperability and Standards:
 
 - Standard Protocols: Uses standard protocols (e.g., OAuth, XACML) for authorization to ensure interoperability between different systems and services within the Data Space.
 - Integration Support: Facilitates integration with other components such as Association Registries, identity providers, and data services.
 
-##### Scalability and Performance:
-
-- Efficient Processing: Ensures that authorization decisions are made quickly to support real-time data access needs.
-- Scalable Architecture: Designed to handle a large number of authorization requests and policies, ensuring performance even as the Data Space grows.
-
-##### User and Role Management:
-
-Role-Based Access Control (RBAC): Supports RBAC, allowing policies to be defined based on user roles rather than individual users.
-Dynamic Roles: Allows for dynamic assignment of roles based on context and changing conditions.
-
 #### Main API Call
 
-The main API-call of the Authorization Register is the `/delegation` call. It is used to pass a delegation mask, or delegation request, to the AR, and to receive a Delegation Evidence, a JWT, in response. A Delegation Mask contains an issuer and a target, and a set of policies. Each policy contains (desired) rules (e.g. "Effect: permit"), and a target. The target contains a resource, an environment, and a list of actions (e.g. create, read, update, delete). Together, the policies represent the right to take specified actions on a specified set of resources.
+The main API-call of the Authorization Register is [the `/delegation` call](https://dev.ishare.eu/authorisation-registry-role/delegation-endpoint). It is used to pass a delegation mask, or delegation request, to the AR, and to receive a Delegation Evidence, a JWT, in response. A Delegation Mask contains an issuer and a target, and a set of policies. Each policy contains (desired) rules (e.g. "Effect: permit"), and a target. The target contains a resource, an environment, and a list of actions (e.g. create, read, update, delete). Together, the policies represent the right to take specified actions on a specified set of resources.
 
-The Delegation Evidence is practically identical to the Delegation Mask. It also contains an issuer, a target, and a set of policies, and in addition it contains a time frame in which the Delegation Evidence is valid, and a few other values, such as the license for the target, and a maximum delegation depth.
+The Delegation Evidence is very similar to the Delegation Mask. It also contains an issuer, a target, and a set of policies, and in addition it contains a time frame in which the Delegation Evidence is valid, and a few other values, such as the license for the target, and a maximum delegation depth.
 
 Since the Delegation Evidence is a JWT, it is signed and can be used as a credential when accessing a resource. It is the responsibility of the resource to check whether the resource request is covered by the Delegation Evidence. This is not part of the specification, and can be implemented in an ad hoc way by each Service Provider.