|
| 1 | +# EDC-V Administration APIs |
| 2 | + |
| 3 | +EDC-V is not a monolith. It consists of multiple services and subsystems. Each of these subsystems typically comes with |
| 4 | +a set of APIs, some of which are intended to be internet-facing, others are for internal use only. In this document we |
| 5 | +will focus on the earlier class of APIs, which are typically for _internal use only_. |
| 6 | + |
| 7 | +Each component of EDC-V offers ways to manipulate its data and configuration via REST APIs. For example, when a new |
| 8 | +dataspace participant onboards into a dataspace, a few things need to happen: an (asymmetric) keypair needs to be |
| 9 | +generated, a DID document needs to be created, and a VerifiableCredential needs to be requested from the IssuerService. |
| 10 | +These steps are typically performed by an automated system, a so-called _provisioning system_. This may be a shell |
| 11 | +script, a CI/CD pipeline, or a dedicated management plane. |
| 12 | + |
| 13 | +To do that, the provisioning system must communicate with several APIs, creating resources. |
| 14 | + |
| 15 | +In addition to those steps, the newly onboarded participant may want to manage some data of their own, such as data |
| 16 | +sharing or request more Verifiable Credentials or initiate the download of another data offering. Naturally, isolation |
| 17 | +boundaries must be strictly enforced between participants to avoid data leakage or other security issues. |
| 18 | + |
| 19 | +From that we can see that some API endpoints are intended for _participants_ ; others are intended for automated systems |
| 20 | +with elevated access rights, such as provisioners. From that it follows that two types of authorization privileges/roles |
| 21 | +are required: that of a participant and that of a provisioner. Roles are explained in detail [in this |
| 22 | +chapter](#roles-in-edc-v) |
| 23 | + |
| 24 | +It is important to note that all Administration APIs are intended for machine clients rather than human actors. Hence, |
| 25 | +only authentication flows are supported that don't require human interaction. All Administration API endpoints assume |
| 26 | +some machine client, like a client application or a script. |
| 27 | + |
| 28 | +Please also note that all protocol APIs ([Decentralized Claims |
| 29 | +Protocol](https://eclipse-dataspace-dcp.github.io/decentralized-claims-protocol/), [Dataspace |
| 30 | +Protocol](https://eclipse-dataspace-protocol-base.github.io/DataspaceProtocol/2025-1/) and [Dataplane |
| 31 | +Signaling](https://github.com/eclipse-dataplane-signaling)) are out-of-scope for this document. |
| 32 | + |
| 33 | +## EDC-V Component Overview |
| 34 | + |
| 35 | +The following diagram shows an overview of the main EDC-V components relevant to the Administration APIs. It does _not_ |
| 36 | +show optional components, such as the Federated Catalog or external Identity Providers. It also does not show |
| 37 | +infrastructure components, such as databases, message brokers, secret vaults, or monitoring systems. |
| 38 | + |
| 39 | + |
| 40 | + |
| 41 | +## Administration API overview |
| 42 | + |
| 43 | +The following table summarizes the Administration APIs offered by EDC-V. |
| 44 | + |
| 45 | +| Name | exposed by | purpose | content type | authentication | intended client | |
| 46 | +|-----------------------|-----------------|----------------------------------------------------------------------------------------|--------------|----------------|---------------------| |
| 47 | +| Management API | ControlPlane | manage assets, policies, contracts etc. | JSON-LD | OAuth2 | tenant, provisioner | |
| 48 | +| Identity API | IdentityHub | manage VerifiableCredentials, key pairs, DID documents, participants | JSON | OAuth2 | tenant, provisioner | |
| 49 | +| Issuer Admin API | IssuerService | manage holders, attestations, credential definitions. Manage individual issuer tenants | JSON-LD | OAuth2 | provisioner | |
| 50 | +| Observability API | every component | observe system readiness and health | JSON | none | monitoring systems | |
| 51 | +| Federated Catalog API | ControlPlane\* | query and inspect the consolidated catalog of all data offerings in the system. | JSON | OAuth2 | tenant | |
| 52 | + |
| 53 | +\*) This API is optional and may not be present in all deployments. |
| 54 | + |
| 55 | +## Roles in EDC-V |
| 56 | + |
| 57 | +A deployment of EDC-V typically involves multiple roles. These are logical roles, and are not necessarily tied to a |
| 58 | +single user, or an individual person. However, some roles may be reflected in the identity provider used for |
| 59 | +[authentcation and authorization](#authentication-and-authorization). |
| 60 | + |
| 61 | +### Operator |
| 62 | + |
| 63 | +The Operator role is intended for setting up and configuring infrastructure, such as the initial deployment of EDC-V |
| 64 | +components. In practice, this role could be represented as ClusterRole in the RBAC Authorization scheme of a Kubernetes |
| 65 | +cluster. The operator would then configure the cluster, deploy a ControlPlane, IdentityHub, etc., and configure |
| 66 | +networking (DNS), storage, and other infrastructure components. Over the lifetime of an EDC-V deployment, the Operator |
| 67 | +might adjust and reconfigure some parameters, set scaling options etc. Operators might even have access to third-party |
| 68 | +systems such as DNS providers. |
| 69 | + |
| 70 | +_For Administration APIs the `operator` role is not relevant and is not represented._ |
| 71 | + |
| 72 | +### Admin |
| 73 | + |
| 74 | +The Admin role is similar to a `root` user in Linux. This user has full access to all APIs and all data of all |
| 75 | +participants in the system, it may even have access to infrastructure such as Kubernetes or cloud provider consoles. It |
| 76 | +should be noted that using this role for day-to-day operations is discouraged, as it increases the risk of accidental |
| 77 | +misconfiguration or data leakage or loss! |
| 78 | + |
| 79 | +The `admin` role is intended for initial setup and emergency use only. |
| 80 | + |
| 81 | +_For Administration APIs the `admin` role is identified by having the `role=admin` claim in the OAuth2 token._ |
| 82 | + |
| 83 | +### Provisioning System (or _provisioner_) |
| 84 | + |
| 85 | +The Provisioning System is tasked with creating and managing dataspace participants. This includes creating an entry in |
| 86 | +the identity provider's user database, creating participant context entries in the IdentityHub and the ControlPlane as |
| 87 | +well as creating a Holder entry in the IssuerService. |
| 88 | + |
| 89 | +Provisioning Systems may **not** manipulate data owned by a participant, such as assets, policies, or credentials. |
| 90 | + |
| 91 | +Note that some EDC-V deployments may require additional setup, such as entries in the IssuerService database to feed the |
| 92 | +attestation source. This is highly use-case specific and may even require custom APIs that are not shipped with EDC-V, |
| 93 | +but those should be used under the Provisioning System role. For more information about that, please refer to the |
| 94 | +[documentation of the credential issuance |
| 95 | +process](https://github.com/eclipse-edc/IdentityHub/blob/main/docs/developer/architecture/issuer/issuance/issuance.process.md). |
| 96 | + |
| 97 | +_For Administration APIs the Provisioning System role is identified by having the `role=provisioner` claim in the OAuth2 |
| 98 | +token. In addition, the provisioning system role requires write access in the identity provider to create new clients._ |
| 99 | + |
| 100 | +### Participant |
| 101 | + |
| 102 | +The Participant role represents a single dataspace participant. Each participant is able to manage their own data, such |
| 103 | +as assets, policies, contracts, and Verifiable Credentials. Each Administration API that relates to a single participant |
| 104 | +is available under hosted under the `.../participants/{participantId}/...` path. |
| 105 | + |
| 106 | +Participants have access to _all_ Administration APIs that relate to their tenant, but may **not** access any APIs |
| 107 | +relating to other participants or generic Administration APIs, e.g., to create other participants. |
| 108 | + |
| 109 | +A company that has onboarded onto a dataspace would typically be represented by a single participant. Naturally, such a |
| 110 | +company might mave more than one employee that needs to access the Administration APIs. In most cases, this would have |
| 111 | +to be handled by the user interface (the "End-User UI") and its identity provider, by creating user identities for each |
| 112 | +employee and mapping those onto the service identity. When an employee needs to access the Administration APIs, they |
| 113 | +would request an access token for the service identity, for example using the Authorization Code flow of OAuth2 / OpenID |
| 114 | +Connect. More about this can be found in the [chapter about end-user UI](#end-user-ui). |
| 115 | + |
| 116 | +_For Administration APIs the `participant` role is identified by having the `role=participant` claim in the OAuth2 |
| 117 | +token._ |
| 118 | + |
| 119 | +## Authentication and Authorization |
| 120 | + |
| 121 | +The Administration APIs of EDC-V are intended as _single pane of glass_ for both dataspace participants and |
| 122 | +provisioners. That means the same access token can be used to interact with several APIs (provided it carries the |
| 123 | +correct [scopes](#scopes)). To achieve that, all EDC-V components use the same OAuth2-based authentication and |
| 124 | +authorization scheme. |
| 125 | + |
| 126 | +### Centralized access control |
| 127 | + |
| 128 | +The single pane of glass approach requires a shared access control scheme between all EDC-V components. On first glance, |
| 129 | +this may seem contradictory to EDC's claimed "Decentralized Claims Protocol" and overall "decentralized" nature, but |
| 130 | +this decentralization applies to data exchange between dataspace participants, not to the internal operation of the |
| 131 | +EDC-V deployment itself. |
| 132 | + |
| 133 | +EDC-V does not mandate the use of one specific identity provider and does not distribute one. Rather, it requires the |
| 134 | +identity provider to support a [set of requirements](./access_control.md). |
| 135 | + |
| 136 | +Client applications that interact with the Administration APIs must use the _OAuth 2 Client Credentials_ grant to obtain |
| 137 | +an access token. Identity providers are **not** part of EDC-V and must be provided by the deployment operator and they |
| 138 | +must support OAuth2 Client Credentials grant, and must be able to issue tokens with custom claims. They may also support |
| 139 | +the use of refresh tokens, but this is not required as access tokens are typically short-lived. |
| 140 | + |
| 141 | +### Scopes |
| 142 | + |
| 143 | +Access tokens may contain a `scope` claim (as defined by [RFC |
| 144 | +9068](https://datatracker.ietf.org/doc/html/rfc9068#section-2.2.3)) that indicates which APIs the token bearer is |
| 145 | +allowed to use, and which operations are permitted. |
| 146 | + |
| 147 | +Access tokens that have the `role=admin` claim need not carry the `scope` claim, as this role has implicit access to all |
| 148 | +APIs and operations. Tokens with the `role=participant` claim _MUST_ carry the scope claim. |
| 149 | + |
| 150 | +See the [Access Control documentation](./access_control.md#scopes) for details. |
| 151 | + |
| 152 | +### Custom OAuth2 token claims |
| 153 | + |
| 154 | +To avoid having to maintain a client database with associated roles in every EDC-V component (and keep them in sync), |
| 155 | +EDC-V relies on the Identity Provider to issue OAuth2 access tokens with custom claims that contain the client's role. |
| 156 | + |
| 157 | +In addition, the `participant_context_id` claim is used to identify the participant on whose behalf the client is |
| 158 | +acting. This is needed to cross-reference the participant with the requested resource, typically identified by a URL |
| 159 | +path like `/participants/{participantContextId}/some-resource`. |
| 160 | + |
| 161 | +This is described in detail in the [Access Control documentation](./access_control.md#custom-token-claims). |
| 162 | + |
| 163 | +## Administration API usage overview |
| 164 | + |
| 165 | +The following diagram shows an overview of all involved components, their roles, and which APIs they access. |
| 166 | + |
| 167 | + |
| 168 | + |
| 169 | +## End-User UI |
| 170 | + |
| 171 | +The End-User UI is used by employees of a company that is a participant in a dataspace. The End-User UI communicates |
| 172 | +only with a UI Backend application. This is a common pattern in modern web development. The only component exposed to |
| 173 | +the public internet is the UI Backend, and it is subject to scalability and security requirements of the user base. |
| 174 | + |
| 175 | +The End-User UI implements use cases that revolve around a single participant. For example, it would display a list of a |
| 176 | +participant's assets, their ongoing transfers, their contracts, policies, etc. It may also implement features to |
| 177 | +update DID Documents, request credentials, etc. |
| 178 | + |
| 179 | +The End-User UI and the UI Backend are **not** included in an EDC-V deployment and must be developed by each |
| 180 | +organization that wants to run a dataspace individually. This UI and the use cases it models are likely very specific to |
| 181 | +each dataspace, therefore, the authentication mechanisms used between End-User UI ↔ UI Backend are out-of-scope for this |
| 182 | +document. However, each physical user must be mapped onto a client with `role=participant` in EDC-V's identity provider. |
| 183 | + |
| 184 | +### Communication paths and roles |
| 185 | + |
| 186 | +When it needs to manipulate tenant/participant data, the UI Backend communicates with the provisioning system (a |
| 187 | +software component to create/delete participant contexts), using its API. |
| 188 | + |
| 189 | +In addition, when a user wants to make changes to their data (assets, policies, etc.) the UI Backend communicates with |
| 190 | +Administration APIs of EDC-V, using the `participant` role, again, acting on behalf of the logged-in user. |
| 191 | + |
| 192 | +## Provisioning System |
| 193 | + |
| 194 | +As part of the onboarding process of a tenant/participant, the Provisioning System communicates with the Administration |
| 195 | +APIs of EDC-V using the `provisioner` role. It **never** communicates directly with participant-context-specific |
| 196 | +resource APIs (recognizable by their URL path `/participants/{participantContextId}/some-resource`). |
| 197 | + |
| 198 | +The Provisioning System does not interact on behalf of a participant-context; instead it always acts as |
| 199 | +`role=provisioner`, interacting with those parts of the Administration API, that are not participant-context-specific. |
| 200 | + |
| 201 | +## Operations UI |
| 202 | + |
| 203 | +The Operations UI (or ops UI) is intended for dataspace operators, who need to manage the infrastructure where EDC-V is |
| 204 | +deployed. In many cases this will mean deploying, linking and managing multiple Kubernetes clusters ("cells"), |
| 205 | +dynamically scaling individual component workloads, provision additional compute resources, etc. |
| 206 | + |
| 207 | +The Operations UI has no contact points with the Administration APIs of EDC-V. The authentication scheme between the |
| 208 | +Operations UI and its backend is out-of-scope for this document. |
0 commit comments