Skip to content

Commit 6593f96

Browse files
Martin187187Martin187187
authored
Merge pull request #70 from Martin187187/improve-spec
2 parents b46306f + 9fc6f43 commit 6593f96

5 files changed

Lines changed: 383 additions & 1 deletion

File tree

‎documentation/IDTA-01004/modules/ROOT/nav.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ SPDX-License-Identifier: CC-BY-4.0
3131

3232
** xref:./annex/json-access-rule-examples.adoc[Examples of Access Rules in JSON serialization]
3333

34+
** xref:./annex/route-examples.adoc[Examples of ROUTEs and HTTP requests]
35+
3436

3537
* xref:changelog.adoc[Change Log]
3638

‎documentation/IDTA-01004/modules/ROOT/pages/access-rule-model.adoc‎

Lines changed: 88 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,8 @@ The Security Model is explained step by step in the following Chapter <<explanat
6969

7070
Examples can be found in xref:annex/text-access-rule-examples.adoc[].
7171

72+
Further informative examples for RIGHTS, ROUTEs and HTTP requests can be found in xref:annex/route-examples.adoc[].
73+
7274
*The grammar has been tested with BNF playground (https://bnfplayground.pauliankline.com/*).
7375
BNF playground allows to check and test the grammar itself and if expressions are correct according to the grammar.*
7476

@@ -151,6 +153,77 @@ In addition, VIEW allows to see the existence of an element as Id or idShort, bu
151153

152154
ALL is an abbreviation to define all rights.
153155

156+
===== Rights and operation verbs
157+
158+
The RIGHTS values are technology-neutral permissions. For HTTP/REST APIs these permissions are typically enforced on interface operations and their mapped HTTP methods.
159+
The mapping in <<table-rights-to-verbs>> is intended to improve interoperability when ROUTE objects are used for authorization decisions.
160+
Concrete informative examples for RIGHTS, ROUTEs and HTTP requests are given in xref:annex/route-examples.adoc[].
161+
162+
[[table-rights-to-verbs]]
163+
.Indicative mapping of RIGHTS to AAS operation verbs and HTTP methods
164+
[cols="1,2,2,4",options="header"]
165+
|===
166+
|Right
167+
|Operation verb
168+
|HTTP method
169+
|Meaning
170+
171+
|CREATE
172+
|Post
173+
|POST
174+
|Permission to create a new resource at a collection or factory-style endpoint.
175+
176+
|CREATE
177+
|Put
178+
|PUT
179+
|Permission to create a new resource at a client-addressable resource endpoint if the addressed resource does not yet exist.
180+
181+
|READ
182+
|Get, GetAll
183+
|GET
184+
|Permission to read resource content.
185+
186+
|UPDATE
187+
|Patch
188+
|PATCH
189+
|Permission to partially update an existing resource.
190+
191+
|UPDATE
192+
|Put
193+
|PUT
194+
|Permission to replace an existing resource at a client-addressable resource endpoint.
195+
196+
|DELETE
197+
|Delete
198+
|DELETE
199+
|Permission to delete an existing resource.
200+
201+
|EXECUTE
202+
|Invoke
203+
|POST
204+
|Permission to invoke an operation.
205+
206+
|VIEW
207+
|GetAll
208+
|GET
209+
|Permission to see that a resource exists, typically as identifiers, references, idShort values, or descriptor entries without access to the full resource value.
210+
211+
|ALL
212+
|n/a
213+
|n/a
214+
|Abbreviation for all eligible rights.
215+
|===
216+
217+
The mapping is not intended to redefine AAS Part 2 operations.
218+
It clarifies how the abstract RIGHT values are typically applied when an authorization decision is made for a concrete HTTP route.
219+
The same HTTP method can therefore be used for different rights depending on the targeted interface operation and the representation that is returned.
220+
For example, GET may correspond to READ for full content access or VIEW for reference-only or existence-only access.
221+
Search-style read operations may also use POST in specific interfaces.
222+
For endpoints with create-or-replace or upsert semantics, the required right depends on whether the addressed resource already exists.
223+
For example, `PUT /api/v3/submodels/{submodelIdentifier}` requires CREATE if the addressed submodel does not yet exist and UPDATE if it already exists.
224+
The same principle applies to endpoint-specific POST operations such as `POST /api/v3/lookup/shells/{aasIdentifier}` if the endpoint creates the addressed resource when absent and updates it when present.
225+
226+
154227
==== Attributes
155228

156229
[source,bnf,linenums]
@@ -182,7 +255,21 @@ include::partial$bnf/objects.bnf[]
182255

183256
Objects to be protected are either API Routes, Identifiables (e.g. AAS or Submodel), Referables (e.g. SubmodelElements), Descriptors or Fragments of those (e.g. AssetId, SemanticId, SpecificAssetId).
184257

185-
Routes may use * or end with a *, which means that all routes with a given prefix are valid.
258+
ROUTE defines the endpoint address of an interface operation.
259+
This allows access control to be defined for single interface operations, groups of interface operations, or complete interfaces.
260+
261+
For AAS HTTP/REST APIs, a ROUTE literal shall use the URL path part only, i.e. the part of the endpoint address starting with "/".
262+
The scheme, authority, query part and fragment identifier are not part of ROUTE matching.
263+
The deployment-specific server base URL is therefore handled separately from the ROUTE literal.
264+
265+
ROUTE matching uses the following rules:
266+
267+
* A ROUTE literal starting with "/" and not ending with "*" matches one concrete path.
268+
* The literal "*" matches all routes.
269+
* A ROUTE literal ending with "*" matches all routes with the given prefix.
270+
271+
Examples are "/shells", "/shells/*" and "*".
272+
For HTTP/REST APIs the examples in xref:annex/route-examples.adoc[] show how ROUTE literals can be combined with RIGHTS and concrete request examples from AAS Part 2.
186273

187274
An Object Group defines a list of single objects and/or a list of names of other object groups.
188275

‎documentation/IDTA-01004/modules/ROOT/pages/annex/route-examples.adoc‎

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
////
2+
Copyright (c) 2025 Industrial Digital Twin Association
3+
4+
This work is licensed under a [Creative Commons Attribution 4.0 International License](
5+
https://creativecommons.org/licenses/by/4.0/).
6+
7+
SPDX-License-Identifier: CC-BY-4.0
8+
9+
////
10+
11+
= Examples of ROUTEs and HTTP requests
12+
13+
This annex is informative.
14+
It gives concrete examples for RIGHTS and ROUTE objects using AAS Part 2 HTTP/REST path templates.
15+
16+
Unless stated otherwise, the examples use the server base URL `https://admin-shell.io/api/v3/` as published in the AAS Part 2 OpenAPI descriptions.
17+
Only the URL path is relevant for ROUTE matching.
18+
19+
== Rights, operation verbs and HTTP methods
20+
21+
The following diagram illustrates one possible relation between abstract rights, operation verbs and HTTP methods.
22+
It is an example to support the interpretation of the normative mapping in xref:access-rule-model.adoc#table-rights-to-verbs[].
23+
24+
[plantuml,annex-rights-verbs-http-methods,svg]
25+
....
26+
include::partial$diagrams/rights-verbs-http-methods.puml[]
27+
....
28+
29+
== Example requests by right
30+
31+
The following requests use real path templates from the published AAS Part 2 OpenAPI descriptions.
32+
They are representative examples for access control decisions on ROUTE objects.
33+
For client-addressable routes with create-or-replace or upsert semantics, the required right depends on whether the addressed resource already exists.
34+
In the examples below, `PUT /api/v3/submodels/{id}` and `POST /api/v3/lookup/shells/{someencodedid}` therefore appear under both CREATE and UPDATE with different preconditions.
35+
36+
=== CREATE
37+
38+
Here are endpoints that can need CREATE rights to create new resources or entries in the repository or registry. PUT endpoints with create-or-replace semantics can require UPDATE instead of CREATE rights if the addressed resource already exists.
39+
40+
Example 1: create a new AAS in the repository by POST.
41+
42+
[source,http]
43+
----
44+
POST /api/v3/shells
45+
----
46+
47+
Example 2: create a new submodel at a route by PUT if the addressed submodel does not yet exist.
48+
49+
[source,http]
50+
----
51+
PUT /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU
52+
----
53+
54+
Example 3: create a new submodel element in a collection by POST.
55+
56+
[source,http]
57+
----
58+
POST /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU/submodel-elements
59+
----
60+
61+
Example 4: create a lookup entry by POST if the addressed entry does not yet exist.
62+
63+
[source,http]
64+
----
65+
POST /api/v3/lookup/shells/someencodedid
66+
----
67+
68+
=== READ
69+
70+
Here are endpoints that can need READ rights to access existing resources or entries in the repository or registry. VIEW right can be used as an alternative for GetAll endpointsif only existence information, references, identifiers, or descriptor entries shall be accessible.
71+
72+
Example 1: read all AAS objects.
73+
74+
[source,http]
75+
----
76+
GET /api/v3/shells?limit=50
77+
----
78+
79+
Example 2: read one submodel.
80+
81+
[source,http]
82+
----
83+
GET /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU
84+
----
85+
86+
Example 3: read one submodel element by path.
87+
88+
[source,http]
89+
----
90+
GET /api/v3/submodel/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-elements/Identification/ManufacturerName
91+
----
92+
93+
Example 4: read all shell descriptors from the registry.
94+
95+
[source,http]
96+
----
97+
GET /api/v3/shell-descriptors
98+
----
99+
100+
Example 5: resolve AAS IDs through discovery.
101+
102+
This is an example of a read-like search operation implemented as POST.
103+
104+
[source,http]
105+
----
106+
POST /api/v3/lookup/shellsByAssetLink
107+
----
108+
109+
=== UPDATE
110+
111+
Here are endpoints that can need UPDATE rights to modify existing resources or entries in the repository or registry. For client-addressable routes with create-or-replace semantics, CREATE rights can be sufficient if the addressed resource does not yet exist.
112+
113+
Example 1: replace an existing AAS resource by PUT.
114+
115+
[source,http]
116+
----
117+
PUT /api/v3/shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA
118+
----
119+
120+
Example 2: replace an existing submodel at a client-addressable route by PUT if the addressed submodel already exists.
121+
122+
[source,http]
123+
----
124+
PUT /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU
125+
----
126+
127+
Example 3: partially update a submodel by PATCH.
128+
129+
[source,http]
130+
----
131+
PATCH /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU
132+
----
133+
134+
Example 4: update the value-only representation of a submodel element.
135+
136+
[source,http]
137+
----
138+
PATCH /api/v3/submodel/submodel-elements/Identification/ManufacturerName/$value
139+
----
140+
141+
Example 5: update an AAS descriptor in the registry.
142+
143+
[source,http]
144+
----
145+
PUT /api/v3/shell-descriptors/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA
146+
----
147+
148+
Example 6: update a lookup entry by POST if the addressed entry already exists.
149+
150+
[source,http]
151+
----
152+
POST /api/v3/lookup/shells/someencodedid
153+
----
154+
155+
=== DELETE
156+
157+
Here are endpoints that can need DELETE rights to delete existing resources or entries in the repository or registry.
158+
159+
Example 1: delete a submodel from the repository.
160+
161+
[source,http]
162+
----
163+
DELETE /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA
164+
----
165+
166+
Example 2: delete a submodel element by path.
167+
168+
[source,http]
169+
----
170+
DELETE /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-elements/Identification/ManufacturerName
171+
----
172+
173+
Example 3: delete a shell descriptor from the registry.
174+
175+
[source,http]
176+
----
177+
DELETE /api/v3/shell-descriptors/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA
178+
----
179+
180+
=== EXECUTE
181+
182+
Here are endpoints that can need EXECUTE rights to invoke operations on the repository or registry.
183+
184+
Example 1: synchronously invoke an Operation.
185+
186+
[source,http]
187+
----
188+
POST /api/v3/submodel/submodel-elements/Reset/invoke
189+
----
190+
191+
Example 2: asynchronously invoke an Operation.
192+
193+
[source,http]
194+
----
195+
POST /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9tYWludGVuYW5jZQ/submodel-elements/Reset/invoke-async
196+
----
197+
198+
Example 3: retrieve the status of an asynchronous invocation.
199+
200+
[source,http]
201+
----
202+
GET /api/v3/submodel/submodel-elements/Reset/operation-status/4a2a7aaf-6f44-4f88-bba2-0b0d2d3e7a10
203+
----
204+
205+
=== VIEW
206+
207+
VIEW is not bound to a dedicated HTTP method.
208+
In HTTP/REST APIs it is usually enforced on GET operations that only expose existence information, references, identifiers, or descriptor entries.
209+
210+
Example 1: retrieve references instead of full resource content.
211+
212+
[source,http]
213+
----
214+
GET /api/v3/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9zbS9uYW1lcGxhdGU/$reference
215+
----
216+
217+
Example 2: retrieve submodel references of an AAS.
218+
219+
[source,http]
220+
----
221+
GET /api/v3/shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvMTIzNA/submodel-refs
222+
----
223+
224+
Example 3: retrieve descriptor entries without accessing the hosted AAS content itself.
225+
226+
[source,http]
227+
----
228+
GET /api/v3/shell-descriptors
229+
----
230+
231+
== Notes for access rule authors
232+
233+
* ROUTE literals should be defined against stable path families such as `/shells/*`, `/submodels/*`, `/shell-descriptors/*` or `/lookup/*` if authorization is intended for complete interfaces.
234+
* Exact ROUTE literals such as `/submodel/submodel-elements/Reset/invoke` are useful for single sensitive operations.

‎documentation/IDTA-01004/modules/ROOT/pages/changelog.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ Minor Changes:
2323

2424
* update: Revised description text to replace 'may include signing' / 'will be' with 'is signed' / 'be signed' for clarity and consistency.
2525
* added: Access control examples for REFERENCE & along with rules for creating only specific models, defined using BNF and JSON.
26+
* added: Clarified ROUTE semantics for AAS HTTP/REST path matching and added informative ROUTE and request examples [#58](https://github.com/admin-shell-io/aas-specs-security/issues/58)
27+
* added: Expanded the explanation of RIGHTS with a mapping to operation verbs and HTTP methods, including an illustrative table and diagram [#56](https://github.com/admin-shell-io/aas-specs-security/issues/56)
2628

2729
Bugfixes:
2830

0 commit comments

Comments
 (0)