From ba51f9214364ca946ed4f9f2440b3449425a4096 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 8 Jan 2024 10:26:36 +0100 Subject: [PATCH 01/23] Create eu.arrowhead.authorization-http-json.yml Creation of a IDD folder for V5.0 documentation. Initial authorization IDD draft. --- .../eu.arrowhead.authorization-http-json.yml | 378 ++++++++++++++++++ 1 file changed, 378 insertions(+) create mode 100644 5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml diff --git a/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml new file mode 100644 index 0000000..135a102 --- /dev/null +++ b/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml @@ -0,0 +1,378 @@ +openapi: 3.0.3 + +info: + title: Authorization HTTP(S)-JSON + description: | + This specification outlines how to realize the _Arrowhead Core Authorization_ service on top of + either of the HTTP or HTTPS protocols with payloads encoded in JSON. The service allows for + service providers to check if their own _consumers_ are authorized to perform certain + _operations_ on certain _objects_, without having to know any details about how the + authorization decision is reached. + + In the context of this document, we understand an _operation_ to be a string identifier that + names something a consumer can request that a certain type of service performs on its behalf. We + also understand an _object_ to be any kind resource that is acted upon while an operation is + performed. If, for example, a file storage service is provided, then possible _operations_ could + be `"upload"` and `"download"` while the _objects_ of the service are the files it stores. + + No requirements are imposed on an implementation of this service with regards to how it + determines if certain consumers are allowed to perform certain operations on certain objects. + It may implement something akin to the INCITS 565-2020 standard, also known as _Next Generation_ + _Access Control_ (NGAC), or something much less sophisticated. It is also assumed that the + service provider is informed about what authorization requests to approve via some other service + than this one. + + ## Caching and Performance + + Implementations of this service _may_ allow for its consumers to cache its authorization + decisions for brief periods of time when relevant to improve performance. When it is enabled, it + is communicated via the `Cache-Control` header of its responses. + + An individual implementation of this service with sufficiently sophisticated software and + hardware should be able to handle up to and beyond hundreds of thousands of authorization + triplets per second. That being said, there could be cases where no available hardware is + performant enough, or where individual consumers are disconnected from this service for + significant periods of time. These use cases are outside the scope of this service. + + ## Compression and Language + + An implementation of this service interface _should_ be designed to support compression and + _may_ provide human-readable error texts in different languages than English, as described in + [RFC 9110, Section 12](https://www.rfc-editor.org/rfc/rfc9110#name-content-negotiation). Not + using compression _must_ be supported and _should_ be the default. Also, the default language + for error messages _must_ be American English (`en-US`). + + ## Size Limits + + As a mitigation against denial-of-service attacks, all implementations of this service + interface _should_ reject incoming requests that are larger than a predefined limit. That limit + _must not_ be smaller than 8192 bytes for each received request. An implementation _may_ also + limit the sizes of individual parts within each request. It _must_, however, receive request + payloads up to 4096 bytes in size. If payload compression is supported, then this limit applies + after decompression. + version: 5.0.0-rc.1 + +paths: + + /authorize: + + post: + operationId: authorize + description: | + Queries the authorization system for authorization decision for each specified action over the + specified requestor and consumer pair. + + As a reponse, for each action in the request body, an authorization decision will be returned. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + requestor: + type: string + description: The identifier of the entity making the request. The format of the string is + dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) + actions: + type: array + items: + type: string + description: An array of actions to be authorized. These actions (or access rights) must be + pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) + resource: + type: string + description: The identifier of the resource being accessed. The format of the string is + dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) + required: + - requestor + - actions + - resource + examples: + example1: + summary: Example 1 + value: + requestor: user123 + actions: ["read"] + resource: document1 + example2: + summary: Example 2 + value: + requestor: admin456 + actions: ["write"] + resource: document2 + responses: + '200': + description: Successful authorization + content: + application/json: + schema: + type: array + items: + type: string + description: Authorization decisions for each action in the request. + examples: + example1: + summary: Example 1 + value: ["allowed"] + example2: + summary: Example 2 + value: ["denied"] + headers: + Cache-Control: + $ref: '#/components/headers/Cache-Control' + Limit: + $ref: '#/components/headers/Limit' + '400': { $ref: '#/components/responses/400-BadRequest' } + '401': { $ref: '#/components/responses/401-Unauthorized' } + '403': { $ref: '#/components/responses/403-Forbidden' } + '406': { $ref: '#/components/responses/406-NotAcceptable' } + '408': { $ref: '#/components/responses/408-RequestTimeout' } + '411': { $ref: '#/components/responses/411-LengthRequired' } + '413': { $ref: '#/components/responses/413-PayloadTooLarge' } + '414': { $ref: '#/components/responses/414-URITooLarge' } + '415': { $ref: '#/components/responses/415-UnsupportedMediaType' } + '429': { $ref: '#/components/responses/429-TooManyRequests' } + '431': { $ref: '#/components/responses/431-RequestHeaderFieldsTooLarge' } + '500': { $ref: '#/components/responses/500-InternalServerError' } + '503': { $ref: '#/components/responses/503-ServiceUnavailable' } + + /bulkAuthorize: + post: + summary: Bulk Authorize Actions for Resources + description: | + Allows for bulk authorization requests to be sent to the authorization system in a single API request + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + type: object + properties: + requestor: + type: string + description: The identifier of the entity making the request. The format of the string is + dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) + actions: + type: array + items: + type: string + description: An array of actions to be authorized. These actions (or access rights) must be + pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) + resource: + type: string + description: The identifier of the resource being accessed. The format of the string is + dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) + required: + - requestor + - actions + - resource + example: + - requestor: "user123" + actions: ["read", "write"] + resource: "document1" + - requestor: "admin456" + actions: ["read", "delete"] + resource: "document2" + - requestor: "user789" + actions: ["read"] + resource: "document3" + responses: + '200': + description: Successful bulk authorization + content: + application/json: + schema: + type: array + items: + type: array + items: + type: string + description: An array of decisions for each action, for each request. + example: + - ["allowed", "allowed"] + - ["allowed", "denied"] + - ["allowed"] +components: + + headers: + + Cache-Control: + description: | + If present, the value of this header may only include the `max-age`, `must-revalidate` and + `no-store` response directives, all of which are defined in + [RFC 9111 Section 5.2.2](https://datatracker.ietf.org/doc/html/rfc9111#name-response-directives). + + The `max-age` directive indicates for how many seconds the decision in the response may be + cached before being requested again by the consumer. The `must-revalidate` directive is used + to forbid the consumer from using the decision after the `max-age` has expired and the + attempt to request it again failed. The `no-store` directive instructs the consumer not to + cache the decision at all. + schema: + type: string + example: max-age=10, must-revalidate + required: false + + Limit: + description: | + An indication of the maximum number of triplets the consuming system is allowed to include + in its request. + schema: + type: number + format: int32 + minimum: 0 + required: true + + Retry-After: + description: | + An indication, in seconds, of how long a consumer is to wait before attempting the failed + request again. + schema: + type: number + format: int32 + minimum: 1 + required: true + + responses: + + 400-BadRequest: + description: | + Invalid authorization basis submitted in request for an authorization decision. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 401-Unauthorized: + description: | + Consumer not yet authorized. + + The kind of authorization required _may_ be named in the error response. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 403-Forbidden: + description: | + Consumer is authorized, but lacks permission. + + If a particular parameter is the cause of this error, it will be named in the payload of the + error response. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 406-NotAcceptable: + description: | + A request contains either of the `Accept`, `Accept-Encoding` or `Accept-Language` headers, + and they do not allow for the service provider to respond using `application/json` as + `Content-Type` or with an encoding or language that the service provider supports. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 408-RequestTimeout: + description: | + A request did not arrive in full within an arbitrary timeout decided by the provider of this + service interface. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 411-LengthRequired: + description: | + The `Content-Length` header is missing in the request. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 413-PayloadTooLarge: + description: | + The payload in the request exceeds the size limit imposed by the service provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 414-URITooLarge: + description: | + The size of the request line in the request, which includes the HTTP version, method and + URI, exceeds the limit imposed by the service provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 415-UnsupportedMediaType: + description: | + The request includes a payload encoded using a `Content-Type` unsupported by the service + provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 429-TooManyRequests: + description: | + The consumer has sent too many request in a too short time span. The consumer is expected to + wait the amount of time indicated in the `Retry-After` header before trying again. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + headers: + Retry-After: + $ref: '#/components/headers/Retry-After' + + 431-RequestHeaderFieldsTooLarge: + description: | + The headers section in the request exceeds the limit imposed by the service provider. This + response code may indicate that + + 1. either the name or value of a field is too large, + 2. the combination of name and value in a field is too large, or + 3. the complete header section is too large. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 500-InternalServerError: + description: | + The server encountered an unexpected condition that prevented it from fulfilling the + request. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 503-ServiceUnavailable: + description: | + The service provider is currently near its operating capacity or is undergoing maintenance. + The consumer is expected to wait before trying again, as indicated by the `Retry-After` + header in the response. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + headers: + Cache-Control: + $ref: '#/components/headers/Retry-After' + + schemas: + + Error: + description: | + An indication of why a received request was rejected. It is formulated with the assumption + that the consumer knows of and can interpret the status code in the response. + type: object + properties: + message: + description: A human-readable explanation of why the request was rejected. + type: string + + Triplet: + description: | + Three strings identifying a _consumer_, an _operation_ and an _object_, in that order. + Together they describe how a certain consumer wishes do perform a certain operation on a + certain object. + type: array + items: + type: string + minItems: 3 + maxItems: 3 + example: ["yBXJ2b+1XtvKJCRYJgHdcA==", "read", "se.company.heat-sensor-b5421.temperature"] From f03416e9e79d025684d6ec4edd1752076764a919 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 8 Jan 2024 10:32:31 +0100 Subject: [PATCH 02/23] Update eu.arrowhead.authorization-http-json.yml Changed requestor for consumer --- .../eu.arrowhead.authorization-http-json.yml | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml index 135a102..5043cca 100644 --- a/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml @@ -60,7 +60,7 @@ paths: operationId: authorize description: | Queries the authorization system for authorization decision for each specified action over the - specified requestor and consumer pair. + specified consumer and resource pair. As a reponse, for each action in the request body, an authorization decision will be returned. requestBody: @@ -70,7 +70,7 @@ paths: schema: type: object properties: - requestor: + consumer: type: string description: The identifier of the entity making the request. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) @@ -85,20 +85,20 @@ paths: description: The identifier of the resource being accessed. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) required: - - requestor + - consumer - actions - resource examples: example1: summary: Example 1 value: - requestor: user123 + consumer: user123 actions: ["read"] resource: document1 example2: summary: Example 2 value: - requestor: admin456 + consumer: admin456 actions: ["write"] resource: document2 responses: @@ -151,7 +151,7 @@ paths: items: type: object properties: - requestor: + consumer: type: string description: The identifier of the entity making the request. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) @@ -166,17 +166,17 @@ paths: description: The identifier of the resource being accessed. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) required: - - requestor + - consumer - actions - resource example: - - requestor: "user123" + - consumer: "user123" actions: ["read", "write"] resource: "document1" - - requestor: "admin456" + - consumer: "admin456" actions: ["read", "delete"] resource: "document2" - - requestor: "user789" + - consumer: "user789" actions: ["read"] resource: "document3" responses: From 161c5277d0943f1df2166178a111d428815f1a09 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 8 Jan 2024 16:34:42 +0100 Subject: [PATCH 03/23] single authorization endpoint (bulk) Left only bulk authorization, made it so that the name now follows RESTful conventions. Changed actions for access rights --- .../eu.arrowhead.authorization-http-json.yml | 142 ++++++------------ 1 file changed, 46 insertions(+), 96 deletions(-) rename 5.0 Draft/IDD/{ => IDD Authorization Service}/eu.arrowhead.authorization-http-json.yml (77%) diff --git a/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml similarity index 77% rename from 5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml rename to 5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml index 5043cca..1bc685d 100644 --- a/5.0 Draft/IDD/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml @@ -54,53 +54,60 @@ info: paths: - /authorize: + /authorizations: + post: + summary: Bulk Authorize access rights for Resources + description: | + Allows for bulk authorization requests to be sent to the authorization system in a single API request - post: - operationId: authorize - description: | - Queries the authorization system for authorization decision for each specified action over the - specified consumer and resource pair. - - As a reponse, for each action in the request body, an authorization decision will be returned. - requestBody: - required: true - content: - application/json: - schema: + Queries the authorization system for authorization decision for each specified access right over the + specified consumer and resource pair. + + As a reponse, for each request in the request body, an authorization decision will be returned. + requestBody: + required: true + content: + application/json: + schema: + type: array + items: type: object properties: consumer: type: string description: The identifier of the entity making the request. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) - actions: - type: array - items: - type: string - description: An array of actions to be authorized. These actions (or access rights) must be - pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) + access-right: + type: string + description: String identifier for the access right needed to be authorized. These access rights + must be pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) resource: type: string description: The identifier of the resource being accessed. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) required: - consumer - - actions + - access-right - resource examples: example1: - summary: Example 1 + summary: Three authorization requests from different users to different resources. value: - consumer: user123 - actions: ["read"] - resource: document1 + - consumer: "user123" + access-right: "write" + resource: "document1" + - consumer: "admin456" + access-right: "read" + resource: "document2" + - consumer: "user789" + access-right: "read" + resource: "document3" example2: - summary: Example 2 + summary: a single authorization request. value: - consumer: admin456 - actions: ["write"] - resource: document2 + consumer: "user234" + access-right: "read" + resource: "document4" responses: '200': description: Successful authorization @@ -109,16 +116,17 @@ paths: schema: type: array items: - type: string - description: Authorization decisions for each action in the request. - examples: - example1: - summary: Example 1 - value: ["allowed"] - example2: - summary: Example 2 - value: ["denied"] - headers: + type: string + description: An array of decisions for each requested triple. + examples: + example1: + - "allowed" + - "denied" + - "allowed" + example2: + - "allowed" + + headers: Cache-Control: $ref: '#/components/headers/Cache-Control' Limit: @@ -137,64 +145,6 @@ paths: '500': { $ref: '#/components/responses/500-InternalServerError' } '503': { $ref: '#/components/responses/503-ServiceUnavailable' } - /bulkAuthorize: - post: - summary: Bulk Authorize Actions for Resources - description: | - Allows for bulk authorization requests to be sent to the authorization system in a single API request - requestBody: - required: true - content: - application/json: - schema: - type: array - items: - type: object - properties: - consumer: - type: string - description: The identifier of the entity making the request. The format of the string is - dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) - actions: - type: array - items: - type: string - description: An array of actions to be authorized. These actions (or access rights) must be - pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) - resource: - type: string - description: The identifier of the resource being accessed. The format of the string is - dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) - required: - - consumer - - actions - - resource - example: - - consumer: "user123" - actions: ["read", "write"] - resource: "document1" - - consumer: "admin456" - actions: ["read", "delete"] - resource: "document2" - - consumer: "user789" - actions: ["read"] - resource: "document3" - responses: - '200': - description: Successful bulk authorization - content: - application/json: - schema: - type: array - items: - type: array - items: - type: string - description: An array of decisions for each action, for each request. - example: - - ["allowed", "allowed"] - - ["allowed", "denied"] - - ["allowed"] components: headers: From 98ca2ce798885821bdfa38e5f4702f8f0fceadd7 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Tue, 9 Jan 2024 14:24:39 +0100 Subject: [PATCH 04/23] Create eu.arrowhead.authorization-management-http-json.yml Added openAPI specification for authorization policy management API. --- ...ead.authorization-management-http-json.yml | 340 ++++++++++++++++++ 1 file changed, 340 insertions(+) create mode 100644 5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml new file mode 100644 index 0000000..5c5ab89 --- /dev/null +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml @@ -0,0 +1,340 @@ +openapi: 3.0.3 +info: + title: Authorization Policy Management API + version: 1.0.0 +paths: + /policies: + get: + summary: List Policies + description: Retrieve a list of all policies. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Policy' + /policies/{policyId}: + get: + summary: Get Policy by ID + description: Retrieve details of a specific policy by its identifier. + parameters: + - name: policyId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Policy' + put: + summary: Update Policy + description: Update an existing policy by its identifier. + parameters: + - name: policyId + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Policy' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Policy' + delete: + summary: Delete Policy + description: Delete a policy by its identifier. + parameters: + - name: policyId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + /subjects: + get: + summary: List subjects + description: Retrieve a list of all subjects. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Subject' + /subjects/{subjectId}: + get: + summary: Get Subject by ID + description: Retrieve details of a specific subject by its identifier. + parameters: + - name: subjectId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Subject' + delete: + summary: Delete subject + description: Delete a subject by its identifier. + parameters: + - name: subjectId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + /resources: + get: + summary: List resources + description: Retrieve a list of all resources. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Resource' + /resources/{resourceId}: + get: + summary: Get resources by ID + description: Retrieve details of a specific resource by its identifier. + parameters: + - name: resourceId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Resource' + delete: + summary: Delete resource. + description: Delete a resource by its identifier. + parameters: + - name: resourceId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + + /user-attributes: + get: + summary: List user attributes + description: Retrieve a list of all user attributes. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Attribute' + /user-attributes/{uaId}: + get: + summary: Get user attribute by ID + description: Retrieve details of a specific user attribute by its identifier. + parameters: + - name: uaId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Attribute' + delete: + summary: Delete user attribute. + description: Delete an user attribute by its identifier. + parameters: + - name: uaId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + /object-attributes: + get: + summary: List object attributes + description: Retrieve a list of all object attributes. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Attribute' + /object-attributes/{oaId}: + get: + summary: Get user object by ID + description: Retrieve details of a specific object attribute by its identifier. + parameters: + - name: oaId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Attribute' + delete: + summary: Delete object attribute. + description: Delete an object attribute by its identifier. + parameters: + - name: oaId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + + +components: + schemas: + Policy: + type: object + required: + - name + - effect + properties: + id: + type: string + description: The unique identifier of the policy. + name: + type: string + description: The human-readable name of the policy. + description: + type: string + description: A detailed description of the policy. + access-rights: + type: array + items: + type: string + description: List of access rights that the policy controls. + subjects: + type: array + items: + type: string + description: List of entities subject to the policy. + resources: + type: array + items: + type: string + description: List of resources to which the policy applies. + effect: + type: string + enum: ['allow', 'deny', 'associate'] + description: The desired effect of the policy in the policy engine, this may allow the usage of ABAC, RBAC or rule-based + policy engine. For example, a policy containg only subjects, resources, and access-rights with the effect 'allow' would + create a rule-based policy (subject, ar, resource). A policy containing only subjects/resources and user-attributes/object-attributes + and with the effect 'associate' would create an attribute-based or role-based association between the specified user or object and + the respective attributes. The 'deny' effect can be used to create explicit access prohibitions. + user-attributes: + type: array + items: + type: string + description: List of user-attributes (ua) that the policy controls. + object-attributes: + type: array + items: + type: string + description: List of object-attributes (oa) that the policy controls. + + Attribute: + type: object + required: + - id + - name + - Attribute-type + properties: + id: + type: string + description: The unique identifier of the attribute + name: + type: string + description: The human-readable name of the attribute + Attribute-type: + type: string + enum: ['user', 'object'] + description: Type of the Attribute, 'user' for subject attributes (or roles), 'object' for resource attributes. + + Subject: + type: object + required: + - id + - name + properties: + id: + type: string + description: The unique identifier of the subject + name: + type: string + description: The human-readable name of the subject + auth-info: + type: string + description: Authentication information in case needed. E.g., certificate information of consuming systems. + + Resource: + required: + type: object + - id + - name + properties: + id: + type: string + description: the unique identifier of the resource + name: + type: string + description: the human-readable name of the resource + auth-info: + type: string + description: Authentication information in case needed. E.g., certificate information of providing systems. \ No newline at end of file From 28f7669358cc39c17007ba8a7038225f646f70f8 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 15 Jan 2024 08:50:20 +0100 Subject: [PATCH 05/23] Draft versions of IDDs Draft for the authorization and service registry IDDs --- .../eu.arrowhead.authorization-http-json.yml | 49 ++ ...ead.authorization-management-http-json.yml | 187 +++++- ....arrowhead.service-discovery-http-json.yml | 612 ++++++++++++++++++ ...vice-registry-administration-http-json.yml | 108 ++++ 4 files changed, 948 insertions(+), 8 deletions(-) create mode 100644 5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml create mode 100644 5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml index 1bc685d..fc38822 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml @@ -54,6 +54,14 @@ info: paths: + /echo: + get: + summary: Endpoint to check the core system availability. + description: Returns an OK to indicate that the core system is available. + responses: + '200': + description: OK + /authorizations: post: summary: Bulk Authorize access rights for Resources @@ -83,8 +91,12 @@ paths: must be pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) resource: type: string +<<<<<<< Updated upstream description: The identifier of the resource being accessed. The format of the string is dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) +======= + description: The identifier of the resource being accessed, e.g., service instance identifier. +>>>>>>> Stashed changes required: - consumer - access-right @@ -95,6 +107,7 @@ paths: value: - consumer: "user123" access-right: "write" +<<<<<<< Updated upstream resource: "document1" - consumer: "admin456" access-right: "read" @@ -102,6 +115,15 @@ paths: - consumer: "user789" access-right: "read" resource: "document3" +======= + resource: "eu.arrowhead.tempreadings-http-json@MWtzOXIpaUEsOyEhc1NsTwo" + - consumer: "MWtzOXIpaUEsOyEhc1NsTwo=" + access-right: "consume" + resource: "/OutsideTemp" + - consumer: "user789" + access-right: "read" + resource: "91" +>>>>>>> Stashed changes example2: summary: a single authorization request. value: @@ -305,6 +327,29 @@ components: schemas: + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + Error: description: | An indication of why a received request was rejected. It is formulated with the assumption @@ -326,3 +371,7 @@ components: minItems: 3 maxItems: 3 example: ["yBXJ2b+1XtvKJCRYJgHdcA==", "read", "se.company.heat-sensor-b5421.temperature"] +<<<<<<< Updated upstream +======= + +>>>>>>> Stashed changes diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml index 5c5ab89..9c92a92 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml @@ -3,7 +3,45 @@ info: title: Authorization Policy Management API version: 1.0.0 paths: +<<<<<<< Updated upstream /policies: +======= + /management/associations: + post: + summary: Create a New association + description: Create a new association relating resources to resource-attributes, subjects (consumers) to + subject attributes, or attribute-attribute associations. + The resource or subject must be an existing object. The specified attribute can be one existing from the + attributes collection, or if a non-existant attribute is specified, the new attribute will be created in + the collection. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Association' + examples: + example1: + summary: A call to associate a Temperature sensor service to the existing "OutsideTemp" resource attribute. + value: + id: "123123" + association-type: "resource" + target: + id: "existing-resource123" + name: "eu.arrowhead.tempreadings-http-json" + attribute: + id: "existing-attribute1233" + name: "OutsideTemp" + attribute-type: "resource" + responses: + '201': + description: Association created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Association' + +>>>>>>> Stashed changes get: summary: List Policies description: Retrieve a list of all policies. @@ -15,8 +53,13 @@ paths: schema: type: array items: +<<<<<<< Updated upstream $ref: '#/components/schemas/Policy' /policies/{policyId}: +======= + $ref: '#/components/schemas/Association' + /management/associations/{associationId}: +>>>>>>> Stashed changes get: summary: Get Policy by ID description: Retrieve details of a specific policy by its identifier. @@ -67,7 +110,111 @@ paths: responses: '204': description: No content +<<<<<<< Updated upstream /subjects: +======= + + /management/permissions: + post: + summary: Grant a new set of permissions. + description: Create a new set of permissions between a resource-attributes and a subject-attribute specified in the + request body. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Permission' + examples: + example1: + summary: A call to derive "consume" privileges for the subject attribute "TempController" to the + resource attribute "OutsideTemp". + value: + id: "321654" + subject-attribute: + id: "someid123" + name: "TempController" + attribute-type: "subject" + access-rights: + - "consume" + resource-attribute: + id: "existing-attribute1233" + name: "OutsideTemp" + attribute-type: "resource" + responses: + '201': + description: Permission created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/Permission' + + get: + summary: List Permission + description: Retrieve a list of all Permissions. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Permission' + /management/permissions/{permissionId}: + get: + summary: Get permission by ID + description: Retrieve details of a specific permission by its identifier. + parameters: + - name: permissionId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Permission' + put: + summary: Update Permission + description: Update an existing permission by its identifier. + parameters: + - name: permissionId + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Permission' + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Permission' + delete: + summary: Delete Permission + description: Delete a permission by its identifier. + parameters: + - name: permissionId + in: path + required: true + schema: + type: string + responses: + '204': + description: No content + + /management/subjects: +>>>>>>> Stashed changes get: summary: List subjects description: Retrieve a list of all subjects. @@ -80,7 +227,7 @@ paths: type: array items: $ref: '#/components/schemas/Subject' - /subjects/{subjectId}: + /management/subjects/{subjectId}: get: summary: Get Subject by ID description: Retrieve details of a specific subject by its identifier. @@ -109,7 +256,7 @@ paths: responses: '204': description: No content - /resources: + /management/resources: get: summary: List resources description: Retrieve a list of all resources. @@ -122,7 +269,20 @@ paths: type: array items: $ref: '#/components/schemas/Resource' - /resources/{resourceId}: + post: + summary: Create a new resource + description: Create a new resource to be the target of authorization rules. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Resource' + responses: + '201': + description: Resource created successfully + + /management/resources/{resourceId}: get: summary: Get resources by ID description: Retrieve details of a specific resource by its identifier. @@ -152,7 +312,7 @@ paths: '204': description: No content - /user-attributes: + /management/user-attributes: get: summary: List user attributes description: Retrieve a list of all user attributes. @@ -165,7 +325,7 @@ paths: type: array items: $ref: '#/components/schemas/Attribute' - /user-attributes/{uaId}: + /management/user-attributes/{uaId}: get: summary: Get user attribute by ID description: Retrieve details of a specific user attribute by its identifier. @@ -194,7 +354,7 @@ paths: responses: '204': description: No content - /object-attributes: + /management/object-attributes: get: summary: List object attributes description: Retrieve a list of all object attributes. @@ -207,7 +367,7 @@ paths: type: array items: $ref: '#/components/schemas/Attribute' - /object-attributes/{oaId}: + /management/object-attributes/{oaId}: get: summary: Get user object by ID description: Retrieve details of a specific object attribute by its identifier. @@ -306,7 +466,16 @@ components: type: string enum: ['user', 'object'] description: Type of the Attribute, 'user' for subject attributes (or roles), 'object' for resource attributes. + metadata: { $ref: '#/components/schemas/Metadata' } + Metadata: + description: | + Additional details of when creating a policy element. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + Subject: type: object required: @@ -322,6 +491,7 @@ components: auth-info: type: string description: Authentication information in case needed. E.g., certificate information of consuming systems. + metadata: { $ref: '#/components/schemas/Metadata' } Resource: required: @@ -337,4 +507,5 @@ components: description: the human-readable name of the resource auth-info: type: string - description: Authentication information in case needed. E.g., certificate information of providing systems. \ No newline at end of file + description: Authentication information in case needed. E.g., certificate information of providing systems. + metadata: { $ref: '#/components/schemas/Metadata' } diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml new file mode 100644 index 0000000..9278951 --- /dev/null +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -0,0 +1,612 @@ +openapi: 3.0.3 + +info: + title: Service Discovery HTTP(S)-JSON + description: | + This specification outlines how to realize the _Arrowhead Core Service Discovery_ service on + top of either of the HTTP or HTTPS protocols with payloads encoded in JSON. The service allows + for consumers to register, deregister and search for _service records_, provided by themselves + or by other service providers. + + Each service record represents a currently provided service and contains all details necessary + to _contact_ that service. Such details will always include network addresses and a _service_ + _type identifier_, apart from other optional information. The service type identifier is a + reference to the particular message protocol implemented by the provided service. Such a + protocol typically builds upon a base protocol, such as HTTP or MQTT, and includes endpoints, + topics or other operators, as well as message types specific to the provided service. For the + consumption of the service referred to by a service record to be possible, the consumer in + question must already implement the protocol referred to by its service type identifier. + + ## Authorization + + Implementing this service interface specification will entail supporting certain + authorization mechanisms and access control models. What mechanisms and models will be outlined + in a later version of this document. TODO + + Whenever a consumer request the list of services that match a given query, the service registry + should be capable of filtering those services to which the requesting consumer does not have + access to. Attribute-based access control set in the authorization system requires the + _type_ of a given service (known as resources for the authorization system). A bulk request + from the service registry can be sent to the authorization service to validate that the + requesting consumer has access to all the service definitions that may match a given query. + + Such authorization would look like the following example: + - consumer: "MWtzOXIpaUEsOyEhc1NsTwo" + access-right: "consume" + resource: "eu.arrowhead.tempreadings-http-json" + - consumer: "MWtzOXIpaUEsOyEhc1NsTwo=" + access-right: "consume" + resource: "eu.arrowhead.humidityreadings-http-json" + - consumer: "MWtzOXIpaUEsOyEhc1NsTwo" + access-right: "consume" + resource: "eu.arrowhead.rpmcontroller-http-json + + Note that the authorization of services by _type_ does not take into consideration the providing + system of each individual service instance. + + ## Compression and Language + + An implementation of this service interface _may_ be designed to support compression and/or + human-readable error texts in different languages than English, as described in + [RFC 9110, Section 12](https://www.rfc-editor.org/rfc/rfc9110#name-content-negotiation). Not + using compression _must_ be supported and be the default. Also, the default language for error + messages _must_ be American English (`en-US`). + + ## Managing Record Life-Cycles + + In a typical use case, this service interface is meant to hold records for all service providers + currently part of its context. When a service provider joins or leaves a context, it is expected + to register and deregister its services, respectively. However, service providers can fail or be + detached from the context before they get a chance to deregister their services. This can make + it relevant to monitor service providers and temporarily suppress or permanently prune records + associated with unhealthy or inaccessible providers. Implementations of this service interface + are free to suppress and/or prune records in whatever way best supports the use cases they are + designed for. + + ## Record Ownership + + It is the provider indicated inside each record that is the owner of the record, and not the + consumer registering it. This means that a consumer may be forbidden from registering or + deregistering a record for certain or all other service providers, even if it may register + and/or deregister records with itself as provider. + + ## Provider Identifiers + + Every service instance registered via this service interface _must_ be associated with a unique + identifier. In contexts where authentication is not used, providers _must_ chose their own + identifiers. Those identifiers _should_ remain consistent between restarts of those providers. + In contexts where authentication is used, the identifier _must_ be derived as follows: TODO. + + ## Size Limits + + As a mitigation against denial-of-service attacks, all implementations of this service + interface _should_ reject incoming requests that are larger than a predefined limit. That limit + _must not_ be smaller than 8192 bytes for each received request. An implementation _may_ also + limit the sizes of individual parts within each request. It _must_, however, receive request + URI:s up to 2816 bytes in size, as well as request payloads up to 4096 bytes in size. + version: 5.0.0-rc.1 + +paths: + + /echo: + get: + summary: Endpoint to check the core system availability. + description: Returns an OK to indicate that the core system is available. + responses: + '200': + description: OK + + /services: + + get: + operationId: query + description: | + Searches for records matching any query parameters. If no query parameters are specified, + any records the consuming system are permitted to access may be provided in the response. + + If the `limit` query parameter is used and given a value larger than 16, or if the `offset` + query parameter is used with any value, the operation is escalated from type `query` to type + `scan`. Permission to use the latter operation is intended only for consumers that need to + interact with larger number of service providers, that analyze larger numbers of records, + that list them for administrators or operators, or that have other special needs. + + As long as the operation remains a plain `query`, it will always limit its response to 16 + records, unless a smaller `limit` is specified. If escalated to type `scan`, default and + maximum limits depend on how the service is configured. The limits may vary depending on the + attributes of the consumer, such as by allowing for a higher limit if the consumer is an + administrator. + + Any matching records a consumer are not allowed to access will be silently discarded before + the record limit is imposed. + parameters: + - $ref: '#/components/parameters/query-limit' + - $ref: '#/components/parameters/query-offset' + - $ref: '#/components/parameters/query-q' + responses: + '200': + description: Matching service records. + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/Record' } + headers: + Cache-Control: + $ref: '#/components/headers/Cache-Control' + Limit: + $ref: '#/components/headers/Limit' + '400': { $ref: '#/components/responses/400-BadRequest-ExpressionIsInvalid' } + '401': { $ref: '#/components/responses/401-Unauthorized' } + '403': { $ref: '#/components/responses/403-Forbidden' } + '408': { $ref: '#/components/responses/408-RequestTimeout' } + '414': { $ref: '#/components/responses/414-URITooLarge' } + '415': { $ref: '#/components/responses/415-UnsupportedMediaType' } + '429': { $ref: '#/components/responses/429-TooManyRequests' } + '431': { $ref: '#/components/responses/431-RequestHeaderFieldsTooLarge' } + '500': { $ref: '#/components/responses/500-InternalServerError' } + '503': { $ref: '#/components/responses/503-ServiceUnavailable' } + + patch: + operationId: register + description: | + Registers or updates one or more records. + + The combination of the provider and type identifiers inside each record must be unique. + Providing a record when a corresponding combination of identifiers are already registered + will be interpreted as an attempt to replace the existing record. If more than one record + with corresponding identifiers are in the request, the last one in its payload will replace + all others. + requestBody: + content: + application/json: + schema: + type: array + items: { $ref: '#/components/schemas/Record' } + responses: + '204': + description: Confirms that the records in question have been registered or updated. + '400': { $ref: '#/components/responses/400-BadRequest-RecordIsInvalid' } + '401': { $ref: '#/components/responses/401-Unauthorized' } + '403': { $ref: '#/components/responses/403-Forbidden' } + '406': { $ref: '#/components/responses/406-NotAcceptable' } + '408': { $ref: '#/components/responses/408-RequestTimeout' } + '411': { $ref: '#/components/responses/411-LengthRequired' } + '413': { $ref: '#/components/responses/413-PayloadTooLarge' } + '431': { $ref: '#/components/responses/431-RequestHeaderFieldsTooLarge' } + '500': { $ref: '#/components/responses/500-InternalServerError' } + '503': { $ref: '#/components/responses/503-ServiceUnavailable' } + + delete: + operationId: deregister + description: | + Deregisters all records matching any query parameters. If no query parameters are specified, + all records are deregistered the consuming system are permitted to deregister. + + A provider wishing to deregister all of its own service records _should_ avoid sending plain + `DELETE /services` requests. If it has more access rights than it is aware of, it may + deregister more services than it intended. To ensure only its own services are deregistered, + it _should_ add its own provider identifier as part of the query parameter, as in + `DELETE /services?q=@MWtzOXIpaUEsOyEhc1NsTwo=`. + parameters: + - $ref: '#/components/parameters/deregister-q' + responses: + '204': + description: Confirms that the records in question have been deregistered. + '400': { $ref: '#/components/responses/400-BadRequest-ExpressionIsInvalid' } + '401': { $ref: '#/components/responses/401-Unauthorized' } + '403': { $ref: '#/components/responses/403-Forbidden' } + '408': { $ref: '#/components/responses/408-RequestTimeout' } + '414': { $ref: '#/components/responses/414-URITooLarge' } + '429': { $ref: '#/components/responses/429-TooManyRequests' } + '431': { $ref: '#/components/responses/431-RequestHeaderFieldsTooLarge' } + '500': { $ref: '#/components/responses/500-InternalServerError' } + '503': { $ref: '#/components/responses/503-ServiceUnavailable' } + +components: + + headers: + + Cache-Control: + description: | + If present, the value of this header may only include the `max-age`, `must-revalidate` and + `no-store` response directives, all of which are defined in + [RFC 9111 Section 5.2.2](https://datatracker.ietf.org/doc/html/rfc9111#name-response-directives). + + The `max-age` directive indicates for how many seconds the records in the response should be + cached before being queried again by the consumer. The `must-revalidate` directive is used + to forbid the consumer from using the records after the `max-age` has expired and the + attempt to fetch them again failed. The `no-store` directive instructs the consumer not to + cache the records at all. + schema: + type: string + example: max-age=1800, must-revalidate + required: false + + Limit: + description: | + An indication of the maximum number of records the consuming system is allowed to have + included in the response to its query. + schema: + type: number + format: int32 + minimum: 0 + required: true + + Retry-After: + description: | + An indication, in seconds, of how long a consumer is to wait before attempting the failed + request again. + schema: + type: number + format: int32 + minimum: 1 + required: true + + parameters: + + deregister-q: + name: q + in: query + description: | + Deregistration query, consisting of an array of comma-separated deregistration expressions. + Every record matching any of the individual expressions will be deregistered, if the + consumer has the appropriate permissions. + example: eu.arrowhead.service-discovery-http-json,eu.arrowhead.authorization-http-json@MWtzOXIpaUEsOyEhc1NsTwo= + schema: + type: array + items: { $ref: '#/components/schemas/DeregisterExpression' } + explode: false + allowReserved: true + + query-limit: + name: limit + in: query + description: | + An indication of the maximum number of records a consuming system wants to have included in + the response to its query. + example: 24 + schema: + description: | + Indicates a maximum number of records a consuming service wishes to have included in the + response to some query. + type: number + format: int32 + minimum: 1 + + query-offset: + name: offset + in: query + description: | + An indication of the number of records to skip, in order from the first matched, in the + response to a query. + example: 128 + schema: + description: | + Indicates a number of records to skip before collecting records into the response to some + query. + type: number + format: int32 + minimum: 0 + + query-q: + name: q + in: query + description: | + Query, consisting of an array of comma-separated query expressions. Every record matching + any of the individual expressions will be included in the response, unless the number of + matching records exceeds any limit imposed by the providing system. + example: eu.arrowhead.service-discovery-http-json~1.7*4,eu.arrowhead.authorization-http-json*12 + schema: + type: array + items: { $ref: '#/components/schemas/QueryExpression' } + explode: false + allowReserved: true + + responses: + + 400-BadRequest-ExpressionIsInvalid: + description: | + Invalid query parameter or parameters. + + The offending parameters is identified in the payload of the error response. + content: + application/json: + schema: { $ref: '#/components/schemas/ErrorExpressionIsInvalid' } + + 400-BadRequest-RecordIsInvalid: + description: | + A submitted record is invalid. + + The offending field is identified in the payload of the error response. + content: + application/json: + schema: { $ref: '#/components/schemas/ErrorRecordIsInvalid' } + + 401-Unauthorized: + description: | + Consumer not yet authorized. + + The kind of authorization required _may_ be named in the error reponse. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 403-Forbidden: + description: | + Consumer is authorized, but lacks permission. + + If a particular parameter is the cause of this error, it will be named in the payload of the + error response. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 406-NotAcceptable: + description: | + A request contains either of the `Accept`, `Accept-Encoding` or `Accept-Language` headers, + and they do not allow for the service provider to respond using `application/json` as + `Content-Type` or with an encoding or language that the service provider supports. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 408-RequestTimeout: + description: | + A request did not arrive in full within an arbitrary timeout decided by the provider of this + service interface. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 411-LengthRequired: + description: | + The `Content-Length` header is missing in the request. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 413-PayloadTooLarge: + description: | + The payload in the request exceeds the limit imposed by the service provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 414-URITooLarge: + description: | + The size of the request line in the request, which includes the HTTP version, method and + URI, exceeds the limit imposed by the service provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 415-UnsupportedMediaType: + description: | + The request includes a payload encoded using a `Content-Type` unsupported by the service + provider. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 429-TooManyRequests: + description: | + The consumer has sent too many request in a too short time span. The consumer is expected to + wait the amount of time indicated in the `Retry-After` header before trying again. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + headers: + Cache-Control: + $ref: '#/components/headers/Retry-After' + + 431-RequestHeaderFieldsTooLarge: + description: | + The headers section in the request exceeds the limit imposed by the service provider. This + response code may indicate that + + 1. either the name or value of a field is too large, + 2. the combination of name and value in a field is too large, or + 3. the complete header section is too large. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 500-InternalServerError: + description: | + The server encountered an unexpected condition that prevented it from fulfilling the + request. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + + 503-ServiceUnavailable: + description: | + The service provider is currently near its operating capacity or is undergoing maintenance. + The consumer is expected to wait before trying again, as indicated by the `Retry-After` + header in the response. + content: + application/json: + schema: { $ref: '#/components/schemas/Error' } + headers: + Cache-Control: + $ref: '#/components/headers/Retry-After' + + schemas: + + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + + DeregisterExpression: + description: | + An expression of facts about a set of service records to deregister. A deregister expression + consists of two parts, a _service part_ and a _provider part_. At least one of the two must + be part of the query, or it will always match zero records. + + The parts are identical to those with the same names part of the `QueryExpression`. Please + refer to its documentation for more details about their structure. + type: string + pattern: ^(?:(?[^!*,:@^~]+)(?:~(?\d+(?:\.\d+(?:\.\d+)?)?))?)?(?:@(?[A-Za-z0-9-_]*={0,2}))?$ + example: se.arrowhead.service-discovery-http-json@MWtzOXIpaUEsOyEhc1NsTwo= + + Error: + description: | + An indication of why a received request was rejected. It is formulated with the assumption + that the consumer knows of and can interpret the status code in the response. + type: object + properties: + message: + description: A human-readable explanation of why the request was rejected. + type: string + + ErrorExpressionIsInvalid: + description: | + Indicates how a search expression, part of a query or deregistration attempt, is invalid. + allOf: + - $ref: '#/components/schemas/Error' + - type: object + properties: + expression: + description: | + Identifies the first invalid expression in the original request, as well as + providing an explanation for why it is invalid. + type: object + properties: + offset: + description: | + The position of the offending expression, from the first given in the URI of the + rejected request. + type: number + format: int32 + minimum: 0 + example: 2 + message: + description: A human-readable explanation of why this record is invalid. + type: string + example: "Unexpected character '=' at position 20 of 'eu.arrowhead.service=registry'." + + ErrorRecordIsInvalid: + description: | + Indicates how a record, provided as part of a registration attempt, is invalid. + allOf: + - $ref: '#/components/schemas/Error' + - type: object + properties: + record: + description: | + Identifies the first invalid record in the original request, as well as providing + an explanation for why it is invalid. + type: object + properties: + offset: + description: | + The position of the offending record, from the first given in the rejected + request. + type: number + format: int32 + minimum: 0 + example: 4 + message: + description: A human-readable explanation of why this record is invalid. + type: string + example: "Required property missing: 'interfaces'." + + Metadata: + description: | + Additional details of relevance when consuming a service. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + + ProviderIdentifier: + description: | + An array of bytes identifying a particular service provider. The bytes are expressed using + the [URL safe Base 64 encoding](https://datatracker.ietf.org/doc/html/rfc4648#section-5). + type: string + pattern: ^[A-Za-z0-9-_]*={0,2}$ + example: MWtzOXIpaUEsOyEhc1NsTwo= + + QueryExpression: + description: | + An expression of facts about a desired set of service records. A query expression consists + of three parts, a _service part_, a _provider part_ and a _limit part_. At least one of the + two former parts must be part of the query, or it will always match zero records. + + The __service part__ must at least name a specific service type, but may also include a + version specifier. If given, the version specifier will match records with any other version + that is _compatible_ with it. A version specifier consist of a MAJOR, MINOR and a PATCH + number, separated by dots. If both or the latter of the MINOR and PATCH numbers are omitted + from a given version, the ones omitted are assumed to be zero. A given version is compatible + with a _candidate_ version if their MAJOR numbers are equal and the MINOR number of the + candidate version is greater than that of the given version. They are also compatible if + their MAJOR and MINOR numbers are equal and the PATCH number of the candidate version is + equal to or greater than that of the given version. For example, the query expression + `my-service~1.4` matches `my-service~1.4.1` and `my-service~1.6.5`. But it does not match + `my-service~1.3.9` or `my-service~2.0.4`. + + The __provider part__ limits matches to records that refer to the identified service + provider. + + The __limit part__ sets a limit on how many matching records to include in the response. It + consists of an asterisk followed by a positive integer, as in `a-service~1.0*4`. + type: string + pattern: ^(?:(?[^!*,:@^~]+)(?:~(?\d+(?:\.\d+(?:\.\d+)?)?))?)?(?:@(?[A-Za-z0-9-_]*={0,2}))?(?:\*(?\d+))?$ + example: se.arrowhead.service-discovery-http-json~1.6@MWtzOXIpaUEsOyEhc1NsTwo= + + Record: + description: | + Identifies the provider of a service and the type of the service, apart from listing the + addresses through which the service is provided and stating any additional metadata. + + Every service record is uniquely identified through the combination of its `provider`, + `type` and `version`. + type: object + properties: + provider: { $ref: '#/components/schemas/ProviderIdentifier' } + type: { $ref: '#/components/schemas/TypeIdentifier' } + version: { $ref: '#/components/schemas/Version' } + addresses: + description: + A collection of addresses, each with a unique tag name. The tag names _may_ be used to + help a service consumer chose the most appropriate address. The service consumer may, + however, simply try all of them in any order until it finds one that works. + type: object + patternProperties: + .*: { $ref: '#/components/schemas/Address' } + metadata: { $ref: '#/components/schemas/Metadata' } + + TypeIdentifier: + description: | + Identifies a particular type of service, such as `eu.arrowhead.service-discovery-coap-cbor` + or `eu.arrowhead.orchestration-http-json`. + type: string + pattern: ^[^!*,:@^~]+$ + example: eu.arrowhead.authorization-http-json + + Version: + description: | + A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and + PATCH numbers are omitted, the ones omitted are assumed to be zero. + type: string + pattern: ^\d+(?:\.\d+(?:\.\d+)?)?$ + example: 1.4 diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml new file mode 100644 index 0000000..ce9fce7 --- /dev/null +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -0,0 +1,108 @@ +openapi: 3.0.0 +info: + title: Service Registry Management API + version: 1.0.0 +paths: + /service-registry/list: + get: + summary: List all service entries + description: Retrieve a list of all service entries in the service registry. + responses: + '200': + description: Successful operation + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/ServiceEntry' + /service-registry/modify: + put: + summary: Modify a service entry + description: Modify an existing service entry in the service registry. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceEntry' + responses: + '200': + description: Service entry modified successfully + '404': + description: Service entry not found + /service-registry/add: + post: + summary: Add a new service entry + description: Add a new service entry to the service registry. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceEntry' + responses: + '201': + description: Service entry added successfully + /service-registry/delete: + delete: + summary: Delete a service entry + description: Delete an existing service entry from the service registry. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceEntry' + responses: + '200': + description: Service entry deleted successfully + '404': + description: Service entry not found + +components: + schemas: + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + + Service: + type: object + properties: + + + ServiceEntry: + type: object + properties: + serviceID: + type: string + description: The unique identifier of the service entry. + producerID: + type: string + description: The ID of the system which produces the registered service. + address: + $ref: '#/components/schemas/Address' + + + required: + - serviceName + - serviceURL From d4972870938d5f01d88638722e0c4ab3367cbdd3 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 15 Jan 2024 08:53:39 +0100 Subject: [PATCH 06/23] Draft versions of IDDs Fixed conflicts --- .../eu.arrowhead.authorization-http-json.yml | 19 ------------------- ...ead.authorization-management-http-json.yml | 13 ------------- 2 files changed, 32 deletions(-) diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml index fc38822..96e3cba 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml @@ -91,12 +91,7 @@ paths: must be pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) resource: type: string -<<<<<<< Updated upstream - description: The identifier of the resource being accessed. The format of the string is - dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) -======= description: The identifier of the resource being accessed, e.g., service instance identifier. ->>>>>>> Stashed changes required: - consumer - access-right @@ -107,15 +102,6 @@ paths: value: - consumer: "user123" access-right: "write" -<<<<<<< Updated upstream - resource: "document1" - - consumer: "admin456" - access-right: "read" - resource: "document2" - - consumer: "user789" - access-right: "read" - resource: "document3" -======= resource: "eu.arrowhead.tempreadings-http-json@MWtzOXIpaUEsOyEhc1NsTwo" - consumer: "MWtzOXIpaUEsOyEhc1NsTwo=" access-right: "consume" @@ -123,7 +109,6 @@ paths: - consumer: "user789" access-right: "read" resource: "91" ->>>>>>> Stashed changes example2: summary: a single authorization request. value: @@ -371,7 +356,3 @@ components: minItems: 3 maxItems: 3 example: ["yBXJ2b+1XtvKJCRYJgHdcA==", "read", "se.company.heat-sensor-b5421.temperature"] -<<<<<<< Updated upstream -======= - ->>>>>>> Stashed changes diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml index 9c92a92..45477d6 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml @@ -3,9 +3,6 @@ info: title: Authorization Policy Management API version: 1.0.0 paths: -<<<<<<< Updated upstream - /policies: -======= /management/associations: post: summary: Create a New association @@ -41,7 +38,6 @@ paths: schema: $ref: '#/components/schemas/Association' ->>>>>>> Stashed changes get: summary: List Policies description: Retrieve a list of all policies. @@ -53,13 +49,8 @@ paths: schema: type: array items: -<<<<<<< Updated upstream - $ref: '#/components/schemas/Policy' - /policies/{policyId}: -======= $ref: '#/components/schemas/Association' /management/associations/{associationId}: ->>>>>>> Stashed changes get: summary: Get Policy by ID description: Retrieve details of a specific policy by its identifier. @@ -110,9 +101,6 @@ paths: responses: '204': description: No content -<<<<<<< Updated upstream - /subjects: -======= /management/permissions: post: @@ -214,7 +202,6 @@ paths: description: No content /management/subjects: ->>>>>>> Stashed changes get: summary: List subjects description: Retrieve a list of all subjects. From 6a5f54d0566ce6c6e44a4e2250122e316ab75872 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 15 Jan 2024 15:23:58 +0100 Subject: [PATCH 07/23] draft version for service-registry administration Complete draft for the service-registry administration and changes in the service discovery interface to make them follow the same principles. Removed authorization information from the service discovery description in an effort of isolating core services as much as possible from one another --- ....arrowhead.service-discovery-http-json.yml | 75 +++++++++---------- ...vice-registry-administration-http-json.yml | 75 ++++++++++++++++--- 2 files changed, 103 insertions(+), 47 deletions(-) diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml index 9278951..1a362c3 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -17,33 +17,7 @@ info: consumption of the service referred to by a service record to be possible, the consumer in question must already implement the protocol referred to by its service type identifier. - ## Authorization - - Implementing this service interface specification will entail supporting certain - authorization mechanisms and access control models. What mechanisms and models will be outlined - in a later version of this document. TODO - - Whenever a consumer request the list of services that match a given query, the service registry - should be capable of filtering those services to which the requesting consumer does not have - access to. Attribute-based access control set in the authorization system requires the - _type_ of a given service (known as resources for the authorization system). A bulk request - from the service registry can be sent to the authorization service to validate that the - requesting consumer has access to all the service definitions that may match a given query. - - Such authorization would look like the following example: - - consumer: "MWtzOXIpaUEsOyEhc1NsTwo" - access-right: "consume" - resource: "eu.arrowhead.tempreadings-http-json" - - consumer: "MWtzOXIpaUEsOyEhc1NsTwo=" - access-right: "consume" - resource: "eu.arrowhead.humidityreadings-http-json" - - consumer: "MWtzOXIpaUEsOyEhc1NsTwo" - access-right: "consume" - resource: "eu.arrowhead.rpmcontroller-http-json - - Note that the authorization of services by _type_ does not take into consideration the providing - system of each individual service instance. - + ## Compression and Language An implementation of this service interface _may_ be designed to support compression and/or @@ -573,18 +547,16 @@ components: pattern: ^(?:(?[^!*,:@^~]+)(?:~(?\d+(?:\.\d+(?:\.\d+)?)?))?)?(?:@(?[A-Za-z0-9-_]*={0,2}))?(?:\*(?\d+))?$ example: se.arrowhead.service-discovery-http-json~1.6@MWtzOXIpaUEsOyEhc1NsTwo= - Record: - description: | - Identifies the provider of a service and the type of the service, apart from listing the - addresses through which the service is provided and stating any additional metadata. - - Every service record is uniquely identified through the combination of its `provider`, - `type` and `version`. + Service: type: object properties: - provider: { $ref: '#/components/schemas/ProviderIdentifier' } - type: { $ref: '#/components/schemas/TypeIdentifier' } - version: { $ref: '#/components/schemas/Version' } + name: + type: string + description: Service instance human-readable name + service-type: + $ref: '#/components/schemas/TypeIdentifier' + version: + $ref: '#/components/schemas/Version' addresses: description: A collection of addresses, each with a unique tag name. The tag names _may_ be used to @@ -593,7 +565,34 @@ components: type: object patternProperties: .*: { $ref: '#/components/schemas/Address' } - metadata: { $ref: '#/components/schemas/Metadata' } + metadata: + $ref: '#/components/schemas/Metadata' + + Record: + type: object + properties: + serviceID: + type: string + description: The unique identifier of the service entry. + providerID: + $ref: '#/components/schemas/ProviderIdentifier' + description: The ID of the system which produces the registered service. + service: + $ref: '#/components/schemas/Service' + time-to-live: + $ref: '#/components/schemas/TimeToLive' + required: + - serviceID + - providerID + - service + + + TimeToLive: + description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or + expiration. + type: string + pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ + example: 2d12h TypeIdentifier: description: | diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index ce9fce7..f8c61c2 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -85,10 +85,51 @@ components: pattern: ^(?[^:]+):\w*(?.*)$ example: tcp4:192.168.0.7:45326 + Metadata: + description: | + Additional details of relevance when consuming a service. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + + ProviderIdentifier: + description: | + An array of bytes identifying a particular service provider. The bytes are expressed using + the [URL safe Base 64 encoding](https://datatracker.ietf.org/doc/html/rfc4648#section-5). + type: string + pattern: ^[A-Za-z0-9-_]*={0,2}$ + example: MWtzOXIpaUEsOyEhc1NsTwo= + + TypeIdentifier: + description: | + Identifies a particular type of service, such as `eu.arrowhead.service-discovery-coap-cbor` + or `eu.arrowhead.orchestration-http-json`. + type: string + pattern: ^[^!*,:@^~]+$ + example: eu.arrowhead.authorization-http-json + + Service: type: object properties: - + name: + type: string + description: Service instance human-readable name + service-type: + $ref: '#/components/schemas/TypeIdentifier' + version: + $ref: '#/components/schemas/Version' + addresses: + description: + A collection of addresses, each with a unique tag name. The tag names _may_ be used to + help a service consumer chose the most appropriate address. The service consumer may, + however, simply try all of them in any order until it finds one that works. + type: object + patternProperties: + .*: { $ref: '#/components/schemas/Address' } + metadata: + $ref: '#/components/schemas/Metadata' ServiceEntry: type: object @@ -96,13 +137,29 @@ components: serviceID: type: string description: The unique identifier of the service entry. - producerID: - type: string + providerID: + $ref: '#/components/schemas/ProviderIdentifier' description: The ID of the system which produces the registered service. - address: - $ref: '#/components/schemas/Address' - - + service: + $ref: '#/components/schemas/Service' + time-to-live: + $ref: '#/components/schemas/TimeToLive' required: - - serviceName - - serviceURL + - serviceID + - providerID + - service + + TimeToLive: + description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or + expiration. + type: string + pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ + example: 2d12h + + Version: + description: | + A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and + PATCH numbers are omitted, the ones omitted are assumed to be zero. + type: string + pattern: ^\d+(?:\.\d+(?:\.\d+)?)?$ + example: 1.4 \ No newline at end of file From 1ad55599bf74cb09ef03f9321a5457ba5b079a4e Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 15 Jan 2024 16:39:14 +0100 Subject: [PATCH 08/23] Added overview section from IDD pdf template Added overview section from IDD pdf template --- .../eu.arrowhead.authorization-http-json.yml | 8 ++++++++ .../eu.arrowhead.authorization-management-http-json.yml | 8 ++++++++ .../eu.arrowhead.service-discovery-http-json.yml | 7 +++++++ ...rowhead.service-registry-administration-http-json.yml | 9 +++++++++ 4 files changed, 32 insertions(+) diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml index 96e3cba..91f4be3 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml @@ -51,6 +51,14 @@ info: payloads up to 4096 bytes in size. If payload compression is supported, then this limit applies after decompression. version: 5.0.0-rc.1 + + # Additional information present in the IDD template + x-transfer-protocol: [HTTP, HTTPS] + x-encryption-method: to-add + x-encoding: JSON + x-compression: to-add + x-semantics: to-add + x-Ontology: to-add paths: diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml index 45477d6..b60b9d9 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml @@ -2,6 +2,14 @@ openapi: 3.0.3 info: title: Authorization Policy Management API version: 1.0.0 + # Additional information present in the IDD template + x-transfer-protocol: [HTTP, HTTPS] + x-encryption-method: to-add + x-encoding: JSON + x-compression: to-add + x-semantics: to-add + x-Ontology: to-add + paths: /management/associations: post: diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml index 1a362c3..3fd02f8 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -59,6 +59,13 @@ info: limit the sizes of individual parts within each request. It _must_, however, receive request URI:s up to 2816 bytes in size, as well as request payloads up to 4096 bytes in size. version: 5.0.0-rc.1 + # Additional information present in the IDD template + x-transfer-protocol: [HTTP, HTTPS] + x-encryption-method: to-add + x-encoding: JSON + x-compression: to-add + x-semantics: to-add + x-Ontology: to-add paths: diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index f8c61c2..ff5eb04 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -2,6 +2,15 @@ openapi: 3.0.0 info: title: Service Registry Management API version: 1.0.0 + # Additional information present in the IDD template + x-transfer-protocol: [HTTP, HTTPS] + x-encryption-method: to-add + x-encoding: JSON + x-compression: to-add + x-semantics: to-add + x-Ontology: to-add + + paths: /service-registry/list: get: From 27a37f8d185d36c0c41c23eb05d87b1ba98ea299 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 18 Jan 2024 09:03:16 +0100 Subject: [PATCH 09/23] Cleaning and standarization Added auth info to service registration form. Started adding documentation to authorization management service. --- .../eu.arrowhead.authorization-http-json.yml | 10 +++++----- ....arrowhead.authorization-management-http-json.yml | 12 ++++++++++++ .../eu.arrowhead.service-discovery-http-json.yml | 3 +++ ...ead.service-registry-administration-http-json.yml | 12 +++++++++++- 4 files changed, 31 insertions(+), 6 deletions(-) diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml index 91f4be3..2d42466 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml @@ -6,17 +6,17 @@ info: This specification outlines how to realize the _Arrowhead Core Authorization_ service on top of either of the HTTP or HTTPS protocols with payloads encoded in JSON. The service allows for service providers to check if their own _consumers_ are authorized to perform certain - _operations_ on certain _objects_, without having to know any details about how the + _access-rights_ on certain _resource_, without having to know any details about how the authorization decision is reached. - In the context of this document, we understand an _operation_ to be a string identifier that + In the context of this document, we understand an _access-right_ to be a string identifier that names something a consumer can request that a certain type of service performs on its behalf. We also understand an _object_ to be any kind resource that is acted upon while an operation is - performed. If, for example, a file storage service is provided, then possible _operations_ could - be `"upload"` and `"download"` while the _objects_ of the service are the files it stores. + performed. If, for example, a file storage service is provided, then possible _access-right_ could + be `"upload"` and `"download"` while the _resource_ of the service are the files it stores. No requirements are imposed on an implementation of this service with regards to how it - determines if certain consumers are allowed to perform certain operations on certain objects. + determines if certain consumers are allowed to perform certain access rights on certain resources. It may implement something akin to the INCITS 565-2020 standard, also known as _Next Generation_ _Access Control_ (NGAC), or something much less sophisticated. It is also assumed that the service provider is informed about what authorization requests to approve via some other service diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml index b60b9d9..b6d4cf8 100644 --- a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml @@ -1,6 +1,18 @@ openapi: 3.0.3 info: title: Authorization Policy Management API + description: | + This specification outlines how to realize the _Arrowhead Authorization Management_ service on top of either of the HTTP or HTTPS + protocols with payload encoded in JSON. The service allows for resources, data owners, service providers, or system administrators + to manage and express authorization rules to resources. + + To express authorization policies over resources needing protection, a _resource_ object must be created in the policy engine. This + newly created resource can be _associated_ to existing attributes using the _/management/associations_ endpoint. The same applies + whenever a new _subject_ wanting to consume a _resource_ enters to the environment. A _subject_ object must be created in the policy + engine, and it needs to be connected to an attribute using the _/management/associations_ endpoint. This association will connect + the newly created _resource_ or _subject_ to existing authorization policies. + + version: 1.0.0 # Additional information present in the IDD template x-transfer-protocol: [HTTP, HTTPS] diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml index 3fd02f8..dc52a83 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -572,6 +572,9 @@ components: type: object patternProperties: .*: { $ref: '#/components/schemas/Address' } + auth-info: + type: string + description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. metadata: $ref: '#/components/schemas/Metadata' diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index ff5eb04..49ddca5 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -1,6 +1,13 @@ openapi: 3.0.0 info: title: Service Registry Management API + description: | + This specification outlines how to use the _Arrowhead Service Registry Administration_ service + on top of either of the HTTP or HTTPS protocols with payloads encoded in JASON. The service allows for + service providers or cloud administrators to list, register, or unregister services from the service + registry catalog. To register a service, the service provider, a system administrator, or a supporting system + must fill a _ServiceEntry_ object with the details of the service and the service provider. Additional + inforation can be especified in the _metadata_ parameter. version: 1.0.0 # Additional information present in the IDD template x-transfer-protocol: [HTTP, HTTPS] @@ -10,7 +17,7 @@ info: x-semantics: to-add x-Ontology: to-add - + paths: /service-registry/list: get: @@ -137,6 +144,9 @@ components: type: object patternProperties: .*: { $ref: '#/components/schemas/Address' } + auth-info: + type: string + description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. metadata: $ref: '#/components/schemas/Metadata' From 19f437646ce5bbe4adc55040f3cc36b1d9c83882 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 18 Jan 2024 15:45:47 +0100 Subject: [PATCH 10/23] Added orchestration-pull IDD Creation of Orchestration-pull IDD. Fixed details in other IDDs --- ...arrowhead.orchestration-pull-http-json.yml | 275 ++++++++++++++++++ ....arrowhead.service-discovery-http-json.yml | 10 + ...vice-registry-administration-http-json.yml | 11 + 3 files changed, 296 insertions(+) create mode 100644 5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml diff --git a/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml new file mode 100644 index 0000000..beb37d4 --- /dev/null +++ b/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml @@ -0,0 +1,275 @@ +openapi: 3.0.0 +info: + title: Orchestration-pull service API description + version: 1.0.0 +description: An API for using the orchestration-pull service of the Orchestration core system. This service + uses the orchestration store policies to recommend service providers to the requesting consumer to fulfil + its task. + +paths: + /orchestration/echo: + get: + summary: Endpoint to check the core system availability. + description: Returns an OK to indicate that the core system is available. + responses: + '200': + description: OK + + + /orchestration/orchestration-pull: + post: + summary: Submit a service request and get orchestration response. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ServiceRequestForm' + responses: + '200': + description: Successful orchestration response. + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/OrchestrationResponse' + + /orchestration/orchestration-pull/{id}: + get: + summary: Get Orchestration by system id + parameters: + - name: id + in: path + required: true + description: ID of requesting system + schema: + type: string + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/OrchestrationResponse' + '404': + description: System id not found + content: + application/json: + example: + error: Orchestration failed, system id not found. + + +components: + schemas: + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + + Auth-tokens: + description: | + An (k,v) object containing authorization tokens for each interface contained in the response + type: object + example: {"interfaceName1":"token1"} + + interface: + description: A string that describes the interface in Protocol-SecurityType-MimeType format. SecurityType can be either SECURE or + INSECURE. + type: string + pattern: ^([a-zA-Z0-9_-]+)-(SECURE|INSECURE)-([a-zA-Z0-9_-]+)$ + example: HTTP-SECURE-JSON + + Metadata: + description: | + Additional details of relevance when consuming a service. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + + PreferredProvider: + type: object + description: information of a preferred provider to consume services from. + properties: + provider-cloud: + $ref: '#/components/schemas/ProviderCloud' + provider: + $ref: '#/components/schemas/ProviderSystem' + + ProviderSystem: + type: object + description: information describing a provider system within a local cloud. + properties: + system-name: + type: string + address: + $ref: '#/components/schemas/Address' + + ProviderCloud: + type: object + description: an object describing the cloud in which a provider is located + properties: + operator: + type: string + description: Name of the operator company + name: + type: string + description: name of the cloud + + RequesterSystem: + type: object + description: Information of the system requesting orchestration information. + properties: + systemName: + type: string + description: Short human readable system name. + systemID: + type: string + description: unique identifier of requester system + address: + $ref: '#/components/schemas/Address' + auth-info: + type: string + description: Authentication info, i.e, CERTIFICATE, TOKEN, etc. + interface: + type: array + items: + $ref: '#/components/schemas/Interface' + + RequestedService: + type: object + description: | + Optional information of the required service. This object contains the service requirements of the requester + system. + properties: + service-definition: + type: string + description: Service definition + interfaces: + type: array + items: + $ref: '#/components/schemas/Interface' + security: + type: array + items: + $ref: '#/components/schemas/SecurityType' + metadata: + $ref: '#/components/schemas/Metadata' + version: + $ref: '#/components/schemas/VersionReq' + + Service: + type: object + properties: + name: + type: string + description: Service instance human-readable name + service-type: + $ref: '#/components/schemas/TypeIdentifier' + version: + $ref: '#/components/schemas/Version' + addresses: + description: + A collection of addresses, each with a unique tag name. The tag names _may_ be used to + help a service consumer chose the most appropriate address. The service consumer may, + however, simply try all of them in any order until it finds one that works. + type: object + patternProperties: + .*: { $ref: '#/components/schemas/Address' } + interface: + type: array + items: + $ref: '#/components/schemas/Interface' + auth-info: + type: string + description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. + metadata: + $ref: '#/components/schemas/Metadata' + + SecurityType: + type: string + enum: + - TOKEN + - NON-SECURE + - CERTIFICATE + + ServiceRequestForm: + type: object + properties: + requesting-system: + $ref: '#/components/schemas/RequesterSystem' + requested-service: + $ref: '#/components/schemas/RequestedService' + preferred-providers: + type: array + items: + $ref: '#/components/schemas/PreferredProvider' + + OrchestrationResponse: + type: object + properties: + providers: + type: array + items: + $ref: '#/components/schemas/ProviderSystem' + service: + $ref: '#/components/schemas/Service' + auth-tokens: + $ref: '#/components/schemes/Auth-tokens' + warnings: + type: array + items: + $ref: '#/components/schemas/Warning' + + Version: + description: | + A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and + PATCH numbers are omitted, the ones omitted are assumed to be zero. + type: string + pattern: ^\d+(?:\.\d+(?:\.\d+)?)?$ + example: 1.4 + + VersionReq: + description: | + Object describing the required service version, maximun version and minimun version allowed for the + required service. + type: object + properties: + version-required: + $ref: '#/components/schemas/Version' + min-version: + $ref: '#/components/schemas/Version' + max-version: + $ref: '#/components/schemas/Version' + + Warning: + definition: A JSON object containing string warnings that may be returned as part of an orchestration response. + FROM_OTHER_CLOUD -> if the provider is in another cloud to that of the requesting system + TTL_EXPIRED -> if the provider is no longer accessible + TTL_EXPIRING -> the provider will be inaccessible within a short time + TTL_UNKNOWN - > the provider does not especify an expiration time + type: string + enum: + - FROM_OTHER_CLOUD + - TTL_EXPIRED + - TTL_EXPIRING + - TTL_UNKNOWN \ No newline at end of file diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml index dc52a83..08cb0bb 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -572,6 +572,10 @@ components: type: object patternProperties: .*: { $ref: '#/components/schemas/Address' } + interface: + type: array + items: + $ref: '#/components/schemas/Interface' auth-info: type: string description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. @@ -596,6 +600,12 @@ components: - providerID - service + interface: + description: A string that describes the interface in Protocol-SecurityType-MimeType format. SecurityType can be either SECURE or + INSECURE. + type: string + pattern: ^([a-zA-Z0-9_-]+)-(SECURE|INSECURE)-([a-zA-Z0-9_-]+)$ + example: HTTP-SECURE-JSON TimeToLive: description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index 49ddca5..3e9a501 100644 --- a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -144,6 +144,10 @@ components: type: object patternProperties: .*: { $ref: '#/components/schemas/Address' } + interface: + type: array + items: + $ref: '#/components/schemas/Interface' auth-info: type: string description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. @@ -175,6 +179,13 @@ components: pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ example: 2d12h + interface: + description: A string that describes the interface in Protocol-SecurityType-MimeType format. SecurityType can be either SECURE or + INSECURE. + type: string + pattern: ^([a-zA-Z0-9_-]+)-(SECURE|INSECURE)-([a-zA-Z0-9_-]+)$ + example: HTTP-SECURE-JSON + Version: description: | A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and From dc4a3e6703c9175928e6022cfb702d01e9c32429 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 18 Jan 2024 15:50:10 +0100 Subject: [PATCH 11/23] Fixed orchestration-pull summary Fixed orchestration-pull summary --- .../eu.arrowhead.orchestration-pull-http-json.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml index beb37d4..f161094 100644 --- a/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml @@ -18,7 +18,12 @@ paths: /orchestration/orchestration-pull: post: - summary: Submit a service request and get orchestration response. + summary: Submit a service request and get orchestration response. If no service definition is specified, the orchestration + will return the suggested services and their appropriate providers for the consuming system to fulfil its tasks, depending + on a existing SoS configuration or Orchestration rules. + + Information of the requesting system is mandatory. Requested service is optional. If a requested service object is specified, + the service definition and at least one interface must be specified. requestBody: required: true content: From 3b01f04e4685a09fba39340857d62c004e7ea33d Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 18 Jan 2024 15:52:02 +0100 Subject: [PATCH 12/23] Changed folder naming structure --- .../eu.arrowhead.authorization-http-json.yml | 0 .../eu.arrowhead.authorization-management-http-json.yml | 0 .../eu.arrowhead.orchestration-pull-http-json.yml | 0 .../eu.arrowhead.service-discovery-http-json.yml | 0 .../eu.arrowhead.service-registry-administration-http-json.yml | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename 5.0 Draft/IDD/{IDD Authorization Service => IDDs Authorization System}/eu.arrowhead.authorization-http-json.yml (100%) rename 5.0 Draft/IDD/{IDD Authorization Service => IDDs Authorization System}/eu.arrowhead.authorization-management-http-json.yml (100%) rename 5.0 Draft/IDD/{IDD Orchestration Service => IDDs Orchestration System}/eu.arrowhead.orchestration-pull-http-json.yml (100%) rename 5.0 Draft/IDD/{IDD Service Registry => IDDs Service Registry}/eu.arrowhead.service-discovery-http-json.yml (100%) rename 5.0 Draft/IDD/{IDD Service Registry => IDDs Service Registry}/eu.arrowhead.service-registry-administration-http-json.yml (100%) diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml similarity index 100% rename from 5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-http-json.yml rename to 5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml diff --git a/5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml similarity index 100% rename from 5.0 Draft/IDD/IDD Authorization Service/eu.arrowhead.authorization-management-http-json.yml rename to 5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml diff --git a/5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml similarity index 100% rename from 5.0 Draft/IDD/IDD Orchestration Service/eu.arrowhead.orchestration-pull-http-json.yml rename to 5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml similarity index 100% rename from 5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-discovery-http-json.yml rename to 5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml diff --git a/5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml similarity index 100% rename from 5.0 Draft/IDD/IDD Service Registry/eu.arrowhead.service-registry-administration-http-json.yml rename to 5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml From 631cf58eb2ec5cc238f9a1cf68d700106b91f6e1 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Fri, 19 Jan 2024 15:24:05 +0100 Subject: [PATCH 13/23] Added initial draft for Orchestration Store Management Added initial draft for Orchestration Store Management, simple specification of orchestration rules. TODO: fix orchestration Targets --- ...chestration-store-management-http-json.yml | 259 ++++++++++++++++++ ...vice-registry-administration-http-json.yml | 1 - 2 files changed, 259 insertions(+), 1 deletion(-) create mode 100644 5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml new file mode 100644 index 0000000..2c091c5 --- /dev/null +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml @@ -0,0 +1,259 @@ +openapi: 3.0.0 +info: + title: Orchestration Management API + version: 1.0.0 +paths: + /orchestration/rules: + get: + summary: Get All Orchestration Rules + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Rule' + post: + summary: Create Orchestration Rule + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Rule' + responses: + '201': + description: Orchestration Rule created successfully + '400': + description: Invalid request + + /orchestration/rules/{ruleId}: + get: + summary: Get Orchestration Rule by ID + parameters: + - name: ruleId + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/Rule' + '404': + description: Orchestration Rule not found + + put: + summary: Update Orchestration Rule + parameters: + - name: ruleId + in: path + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/Rule' + responses: + '200': + description: Orchestration Rule updated successfully + '404': + description: Orchestration Rule not found + '400': + description: Invalid request + + delete: + summary: Delete Orchestration Rule + parameters: + - name: ruleId + in: path + required: true + schema: + type: string + responses: + '204': + description: Orchestration Rule deleted successfully + '404': + description: Orchestration Rule not found + + /orchestration/configurations: + post: + summary: Upload System of Systems Configuration + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + responses: + '201': + description: Configuration uploaded successfully + '400': + description: Invalid request + + get: + summary: Get Orchestration Configurations + responses: + '200': + description: Successful response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Configuration' + + /orchestration/configurations/{id}: + delete: + summary: Delete Configuration + parameters: + - name: id + in: path + required: true + schema: + type: string + responses: + '204': + description: Configuration deleted successfully + '404': + description: Configuration not found + + /orchestration/configurations/active-configuration: + get: + summary: Get Active Configuration + responses: + '200': + description: Successful response + content: + application/json: + schema: + $ref: '#/components/schemas/ActiveConfiguration' + + put: + summary: Set Active Configuration + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ActiveConfiguration' + responses: + '200': + description: Active Configuration set successfully + '400': + description: Invalid request + +components: + schemas: + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + + ActiveConfiguration: + type: object + properties: + configuration: + $ref: '#/components/schemas/Configuration' + validity: + $ref: '#/components/schemas/TimeToLive' + + Configuration: + type: object + properties: + configId: + type: string + description: unique identifier of the SoS configuration + name: + type: string + description: configuration human readable name + rules: + type: array + description: set of rules that compose the configuration + items: + $ref: '#/components/schemas/Rule' + target: + type: object + description: Target of the orchestration configuration + #TODO: define how the target should look like, is it just one target? is it an array of targets? Are the targets within the rules? + + Metadata: + description: | + Additional details of relevance when consuming a service. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + + Rule: + type: object + properties: + ruleId: + type: string + provider: + $ref: '#/components/schemas/System' + consumer: + $ref: '#/components/schemas/System' + service: + $ref: '#/components/schemas/Service' + Metadata: + $ref: '#/components/schemas/Metadata' + + Service: + type: object + description: Information about the orchestrated service + properties: + serviceID: + type: string + description: identifier of service + serviceInstance: + type: string + description: name of the service instance + + System: + type: object + description: information describing a system within a local cloud. + properties: + system-name: + type: string + description: human readable name of the system + address: + $ref: '#/components/schemas/Address' + + TimeToLive: + description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or + expiration. + type: string + pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ + example: 2d12h + diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index 3e9a501..34075bd 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -125,7 +125,6 @@ components: pattern: ^[^!*,:@^~]+$ example: eu.arrowhead.authorization-http-json - Service: type: object properties: From dd22011f09268ba875b2198a6cce5fcffe2c2263 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 22 Jan 2024 13:14:49 +0100 Subject: [PATCH 14/23] Added description and additional information Completed description and additional information from Orchestration-pull and store --- ...arrowhead.orchestration-pull-http-json.yml | 35 +++++++++++++++---- ...chestration-store-management-http-json.yml | 27 +++++++++++++- 2 files changed, 55 insertions(+), 7 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index f161094..673e1bb 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -1,10 +1,33 @@ -openapi: 3.0.0 +openapi: 3.0.3 info: title: Orchestration-pull service API description - version: 1.0.0 -description: An API for using the orchestration-pull service of the Orchestration core system. This service - uses the orchestration store policies to recommend service providers to the requesting consumer to fulfil - its task. + description: | + An API for using the orchestration-pull service of the Orchestration core system. This service + uses the orchestration store policies to recommend service providers to the requesting consumer to fulfil + its task. + + The consumer system request for orchestration either by specifying the service definition that the consumer requires or + by using stored SoS configurations or Orchestration rules if no service information is defined. + + _SoS configurations_ represents the connections needed in a SoS for it to perform its designed task. This means, describing what services + must each of the systems consume to perform their individual tasks. A SoS configuration can be seen as a series of _Orchestration rules_. + _Orchestration rules_ represents a desired interaction between systems consuming specific services from specific preferred providers. + + In the context of this document, we reffer to the Orchestration consumer as _requesting-system_ where _system-id_ is the + unique identifier that represents that system. The _requested-service_ represents the service information that the _requesting-system_ + requires orchestration. In case the _requested_service_ is specified, the requires service definition must be included in the form, + in addition, at least one interface must be specified. The orchestration system will attempt to match the _requested-service_ information + with services present on the orchestration rules or SoS configurations. + +version: 5.0.0-rc.1 + +# Additional information present in the IDD template +x-transfer-protocol: [HTTP, HTTPS] +x-encryption-method: to-add +x-encoding: JSON +x-compression: to-add +x-semantics: to-add +x-Ontology: to-add paths: /orchestration/echo: @@ -144,7 +167,7 @@ components: type: object description: Information of the system requesting orchestration information. properties: - systemName: + system-name: type: string description: Short human readable system name. systemID: diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml index 2c091c5..25cfc1d 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml @@ -1,7 +1,32 @@ openapi: 3.0.0 info: title: Orchestration Management API - version: 1.0.0 + description: | + This API defines interfaces to interact with the Orchestration store where Orchestration rules and Sos configurations + are stored. + + An _orchestration rule_ connects a specified _provider_ providing a _service_ with a _consumer_. This means that the + _consumer_ is adviced to consume the _service_, prefferably from the listed _provider_. Additional matching metadata + can be specified as part of the orchestration rule. + + The orchestration store has also the capability of storing system of systems (SoS) configurations. These configurations + are expressed as a series of orchestration rules, and represent desired SoS states for specific tasks. Configurations can + be stored and retrieved using the described interfaces in this document. Moreover, active configurations for a local cloud + can be defined using the _active-configuration_ endpoint. The active configuration is used by the orchestration to + provide orchestration responses to consumers. + + When setting active configurations, a time-to-live parameter can be defined to specify for how long the specific configuration + is valid in the local cloud. +version: 5.0.0-rc.1 + +# Additional information present in the IDD template +x-transfer-protocol: [HTTP, HTTPS] +x-encryption-method: to-add +x-encoding: JSON +x-compression: to-add +x-semantics: to-add +x-Ontology: to-add + paths: /orchestration/rules: get: From b0defdfabd78a507a240bf5f4645bead178d996b Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Mon, 22 Jan 2024 22:34:59 +0100 Subject: [PATCH 15/23] Create eu.arrowhead.orchestration-push.yml Draft for Orchestration-push service --- .../eu.arrowhead.orchestration-push.yml | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml new file mode 100644 index 0000000..cc5c23f --- /dev/null +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml @@ -0,0 +1,143 @@ +asyncapi: 2.0.0 +info: + title: Push Orchestration Service + description: | + The push Orchestration service allows for systems to load System of systems (SoS) configurations into another systems. + This allows to load service consumption directives remotely into systems to perform a task. + + If no configuration is specified in the triggering message, the active configuration on the orchestrator will be pushed + into the target system. SoS Configurations are expressed as a series of orchestration rules, and represent desired SoS states + for specific tasks. + + An _orchestration rule_ connects a specified _provider_ providing a _service_ with a _consumer_. This means that the + _consumer_ is adviced to consume the _service_, prefferably from the listed _provider_. Additional matching metadata + can be specified as part of the orchestration rule. + +version: 5.0.0-rc.1 + +# Additional information present in the IDD template +x-transfer-protocol: [HTTP, HTTPS] +x-encryption-method: to-add +x-encoding: JSON +x-compression: to-add +x-semantics: to-add +x-Ontology: to-add + +channels: + pushConfiguration: + publish: + message: + $ref: "#/components/messages/SystemConfigurationEvent" + bindings: + amqp: + # Specify AMQP-specific details here if using AMQP + mqtt: + # Specify MQTT-specific details here if using MQTT + http: + # Specify HTTP-specific details here if using HTTP +components: + schemas: + Address: + description: | + Identifies a _transport_ and a _location_. + + The _transport_ identifies the base protocol that facilitates addressing a specific service + instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` + and `unix`. A protocol only counts as a transport if it both (A) provides a way of + addressing and, by extension, sending messages to service providers and consumers, as well + as (B) does not build upon another protocol also providing this capability. I other words, + TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which + satisfy condition A. + + What the _location_ part consists of depends on what transport is identified. If the + transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal + numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If + the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in + [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a + colon and a port number. If the transport is `unix`, the location is an absolute filesystem + path to a Unix socket file. + type: string + pattern: ^(?[^:]+):\w*(?.*)$ + example: tcp4:192.168.0.7:45326 + + Configuration: + type: object + properties: + configId: + type: string + description: unique identifier of the SoS configuration + name: + type: string + description: configuration human readable name + rules: + type: array + description: set of rules that compose the configuration + items: + $ref: '#/components/schemas/Rule' + target: + type: object + description: Target of the orchestration configuration + #TODO: define how the target should look like, is it just one target? is it an array of targets? Are the targets within the rules? + + Metadata: + description: | + Additional details of relevance when consuming a service. What metadata is made available + depends on the type of the service holding the metadata. Possible examples of metadata are + HTTP base paths, message size restrictions and caching directives. + type: object + example: {"basePath":"v2"} + + Rule: + type: object + properties: + ruleId: + type: string + provider: + $ref: '#/components/schemas/System' + consumer: + $ref: '#/components/schemas/System' + service: + $ref: '#/components/schemas/Service' + Metadata: + $ref: '#/components/schemas/Metadata' + + Service: + type: object + description: Information about the orchestrated service + properties: + serviceID: + type: string + description: identifier of service + serviceInstance: + type: string + description: name of the service instance + + System: + type: object + description: information describing a system within a local cloud. + properties: + system-name: + type: string + description: human readable name of the system + address: + $ref: '#/components/schemas/Address' + + TimeToLive: + description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or + expiration. + type: string + pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ + example: 2d12h + + + messages: + SystemConfigurationEvent: + summary: Event triggered to push system configurations to a target system + payload: + type: object + properties: + systemId: + type: string + description: Identifier of the system for which configuration is pushed + configuration: + $ref: '#/components/schemas/Configuration' From b2bb2ed7c10638b760e4ffea696b346c45d73ba4 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Tue, 23 Jan 2024 17:40:03 +0100 Subject: [PATCH 16/23] Small auth-token fix Moved auth-token from response to request --- .../eu.arrowhead.orchestration-pull-http-json.yml | 5 +++-- .../eu.arrowhead.orchestration-push.yml | 5 ++++- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index 673e1bb..57397ea 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -243,6 +243,9 @@ components: ServiceRequestForm: type: object properties: + auth-tokens: + description: Authentication token of the requesting system + $ref: '#/components/schemes/Auth-tokens' requesting-system: $ref: '#/components/schemas/RequesterSystem' requested-service: @@ -261,8 +264,6 @@ components: $ref: '#/components/schemas/ProviderSystem' service: $ref: '#/components/schemas/Service' - auth-tokens: - $ref: '#/components/schemes/Auth-tokens' warnings: type: array items: diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml index cc5c23f..51af3b0 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml @@ -16,7 +16,7 @@ info: version: 5.0.0-rc.1 # Additional information present in the IDD template -x-transfer-protocol: [HTTP, HTTPS] +x-transfer-protocol: [to-add] x-encryption-method: to-add x-encoding: JSON x-compression: to-add @@ -25,6 +25,7 @@ x-Ontology: to-add channels: pushConfiguration: + address: 'orchestration/push' publish: message: $ref: "#/components/messages/SystemConfigurationEvent" @@ -35,6 +36,8 @@ channels: # Specify MQTT-specific details here if using MQTT http: # Specify HTTP-specific details here if using HTTP + + components: schemas: Address: From c6ac5175e9d4c89b4cd26e2fae694d75895d3192 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Fri, 26 Jan 2024 14:13:25 +0100 Subject: [PATCH 17/23] Fixed some comments on Authorization services --- .../eu.arrowhead.authorization-http-json.yml | 119 ++++++++++-------- ...ead.authorization-management-http-json.yml | 39 +++++- 2 files changed, 100 insertions(+), 58 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml index 2d42466..c94b86c 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml @@ -4,19 +4,26 @@ info: title: Authorization HTTP(S)-JSON description: | This specification outlines how to realize the _Arrowhead Core Authorization_ service on top of - either of the HTTP or HTTPS protocols with payloads encoded in JSON. The service allows for - service providers to check if their own _consumers_ are authorized to perform certain - _access-rights_ on certain _resource_, without having to know any details about how the - authorization decision is reached. + either of the HTTP or HTTPS protocols with payloads encoded in JSON. This service allows for + _resource_ ownwers to check _access-rights_ of _subjects_ attempting to perform operations over + their protected _resources_. Authorization queries are then made in the form of the _triple_ + (subject, access-right, resource). In the context of service consumption authorization, + service providers act as resource owners for their provideded services (or _resources_), while + consumers are _subjects_ trying to apply their _access right_ to consume a service. For such + application, an authorization query shall look as: + + subject: "MWtzOXIpaUEsOyEhc1NsTwo=" + access-right: "consume" + resource: "/OutsideTemp" In the context of this document, we understand an _access-right_ to be a string identifier that - names something a consumer can request that a certain type of service performs on its behalf. We - also understand an _object_ to be any kind resource that is acted upon while an operation is + names something a subject can request that a certain type of service performs on its behalf. We + also understand an _resource_ to be any kind resource that is acted upon while an operation is performed. If, for example, a file storage service is provided, then possible _access-right_ could be `"upload"` and `"download"` while the _resource_ of the service are the files it stores. No requirements are imposed on an implementation of this service with regards to how it - determines if certain consumers are allowed to perform certain access rights on certain resources. + determines if certain subjects are allowed to perform certain access rights on certain resources. It may implement something akin to the INCITS 565-2020 standard, also known as _Next Generation_ _Access Control_ (NGAC), or something much less sophisticated. It is also assumed that the service provider is informed about what authorization requests to approve via some other service @@ -77,7 +84,7 @@ paths: Allows for bulk authorization requests to be sent to the authorization system in a single API request Queries the authorization system for authorization decision for each specified access right over the - specified consumer and resource pair. + specified subject and resource pair. As a reponse, for each request in the request body, an authorization decision will be returned. requestBody: @@ -85,42 +92,24 @@ paths: content: application/json: schema: - type: array - items: - type: object - properties: - consumer: - type: string - description: The identifier of the entity making the request. The format of the string is - dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) - access-right: - type: string - description: String identifier for the access right needed to be authorized. These access rights - must be pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) - resource: - type: string - description: The identifier of the resource being accessed, e.g., service instance identifier. - required: - - consumer - - access-right - - resource + $ref: '#/components/schemas/AccessRequests' examples: example1: summary: Three authorization requests from different users to different resources. value: - - consumer: "user123" + - subject: "user123" access-right: "write" resource: "eu.arrowhead.tempreadings-http-json@MWtzOXIpaUEsOyEhc1NsTwo" - - consumer: "MWtzOXIpaUEsOyEhc1NsTwo=" + - subject: "MWtzOXIpaUEsOyEhc1NsTwo=" access-right: "consume" resource: "/OutsideTemp" - - consumer: "user789" + - subject: "user789" access-right: "read" resource: "91" example2: summary: a single authorization request. value: - consumer: "user234" + subject: "user234" access-right: "read" resource: "document4" responses: @@ -129,17 +118,24 @@ paths: content: application/json: schema: - type: array - items: - type: string - description: An array of decisions for each requested triple. + type: object + properties: + authorizationDecisions: + type: array + items: + type: string + enum: + - allowed + - denied examples: example1: - - "allowed" - - "denied" - - "allowed" + value: + authorizationDecisions: ["allowed", "denied"] + summary: Example response with both allowed and denied decisions example2: - - "allowed" + value: + authorizationDecisions: ["allowed", "allowed", "denied"] + summary: Example response with multiple decisions headers: Cache-Control: @@ -171,9 +167,9 @@ components: [RFC 9111 Section 5.2.2](https://datatracker.ietf.org/doc/html/rfc9111#name-response-directives). The `max-age` directive indicates for how many seconds the decision in the response may be - cached before being requested again by the consumer. The `must-revalidate` directive is used - to forbid the consumer from using the decision after the `max-age` has expired and the - attempt to request it again failed. The `no-store` directive instructs the consumer not to + cached before being requested again by the subject. The `must-revalidate` directive is used + to forbid the subject from using the decision after the `max-age` has expired and the + attempt to request it again failed. The `no-store` directive instructs the subject not to cache the decision at all. schema: type: string @@ -192,7 +188,7 @@ components: Retry-After: description: | - An indication, in seconds, of how long a consumer is to wait before attempting the failed + An indication, in seconds, of how long a subject is to wait before attempting the failed request again. schema: type: number @@ -320,6 +316,12 @@ components: schemas: + AccessRequests: + description: An array of authorization Triplets to be submitted to the Authorization system + type: array + items: + $ref: '#/components/schemas/Triplet' + Address: description: | Identifies a _transport_ and a _location_. @@ -346,7 +348,7 @@ components: Error: description: | An indication of why a received request was rejected. It is formulated with the assumption - that the consumer knows of and can interpret the status code in the response. + that the subject knows of and can interpret the status code in the response. type: object properties: message: @@ -355,12 +357,23 @@ components: Triplet: description: | - Three strings identifying a _consumer_, an _operation_ and an _object_, in that order. - Together they describe how a certain consumer wishes do perform a certain operation on a - certain object. - type: array - items: - type: string - minItems: 3 - maxItems: 3 - example: ["yBXJ2b+1XtvKJCRYJgHdcA==", "read", "se.company.heat-sensor-b5421.temperature"] + Three strings identifying a _subject_, an _operation_ and an _resource_, in that order. + Together they describe how a certain subject wishes do perform a certain operation on a + certain resource. + type: object + properties: + subject: + type: string + description: The identifier of the entity making the request. The format of the string is + dependant on the Authentication mechanism used. (e.g., a certificate string, token, id, etc) + access-right: + type: string + description: String identifier for the access right needed to be authorized. These access rights + must be pre-defined within the policy engine used. ("consume", "read", "write", "delete", "update", etc) + resource: + type: string + description: The identifier of the resource being accessed, e.g., service instance identifier. + required: + - subject + - access-right + - resource \ No newline at end of file diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml index b6d4cf8..2dbfc68 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml @@ -26,7 +26,7 @@ paths: /management/associations: post: summary: Create a New association - description: Create a new association relating resources to resource-attributes, subjects (consumers) to + description: Create a new association relating resources to resource-attributes, subjects to subject attributes, or attribute-attribute associations. The resource or subject must be an existing object. The specified attribute can be one existing from the attributes collection, or if a non-existant attribute is specified, the new attribute will be created in @@ -57,10 +57,9 @@ paths: application/json: schema: $ref: '#/components/schemas/Association' - get: - summary: List Policies - description: Retrieve a list of all policies. + summary: List Associations + description: Retrieve a lizst of all associations. responses: '200': description: Successful operation @@ -70,6 +69,10 @@ paths: type: array items: $ref: '#/components/schemas/Association' + headers: + Limit: + $ref: '#/components/headers/Limit' + /management/associations/{associationId}: get: summary: Get Policy by ID @@ -158,7 +161,7 @@ paths: $ref: '#/components/schemas/Permission' get: - summary: List Permission + summary: List Permissions description: Retrieve a list of all Permissions. responses: '200': @@ -169,6 +172,9 @@ paths: type: array items: $ref: '#/components/schemas/Permission' + headers: + Limit: + $ref: '#/components/headers/Limit' /management/permissions/{permissionId}: get: summary: Get permission by ID @@ -234,6 +240,9 @@ paths: type: array items: $ref: '#/components/schemas/Subject' + headers: + Limit: + $ref: '#/components/headers/Limit' /management/subjects/{subjectId}: get: summary: Get Subject by ID @@ -276,6 +285,9 @@ paths: type: array items: $ref: '#/components/schemas/Resource' + headers: + Limit: + $ref: '#/components/headers/Limit' post: summary: Create a new resource description: Create a new resource to be the target of authorization rules. @@ -332,6 +344,9 @@ paths: type: array items: $ref: '#/components/schemas/Attribute' + headers: + Limit: + $ref: '#/components/headers/Limit' /management/user-attributes/{uaId}: get: summary: Get user attribute by ID @@ -374,6 +389,9 @@ paths: type: array items: $ref: '#/components/schemas/Attribute' + headers: + Limit: + $ref: '#/components/headers/Limit' /management/object-attributes/{oaId}: get: summary: Get user object by ID @@ -406,6 +424,17 @@ paths: components: + headers: + Limit: + description: | + An indication of the maximum number of records the consuming system is allowed to have + included in the response to its query. + schema: + type: number + format: int32 + minimum: 0 + required: true + schemas: Policy: type: object From a3b50003da42b17c68e90f1e6f115f22d0b99cc5 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Wed, 31 Jan 2024 12:53:29 +0100 Subject: [PATCH 18/23] Fixed missing Association and Permission Im pretty sure they were there before... Fixed anyhow Some other comment fixing --- .../eu.arrowhead.authorization-http-json.yml | 2 +- ...ead.authorization-management-http-json.yml | 138 ++++++++++++------ ...arrowhead.orchestration-pull-http-json.yml | 38 ++++- .../eu.arrowhead.orchestration-push.yml | 4 +- 4 files changed, 124 insertions(+), 58 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml index c94b86c..57918e4 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml @@ -69,7 +69,7 @@ info: paths: - /echo: + /ping: get: summary: Endpoint to check the core system availability. description: Returns an OK to indicate that the core system is available. diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml index 2dbfc68..c39ef84 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml @@ -6,12 +6,34 @@ info: protocols with payload encoded in JSON. The service allows for resources, data owners, service providers, or system administrators to manage and express authorization rules to resources. + Although the interface definition for the authorization system does not impose requirements on an implementation of that service + with regards to how it determines if certain subjects are allowed to perform certain access rights on certain resources. This interface + definition is designed to allow for Attribute-based Access Control to be enforced in the Authorization system. However, the same + definition can be used to describe and manage role-based or rule-based policies by the flexible use of associations and permissions. + + This interface understands _resources_ as the entities needing protection, e.g., services, data-bases, files, etc. On the other + hand, _subjects_ represents the entities trying to access or consume the previously defined _resources_. Finally, _access-rights_ + represents the actions that _subjects_ attempt to performed over the protected _resources_, these can be defined with different levels + of granularity, such as service consumption, or read or write of data. Moreover, this interface definition understands _attributes_ as + characteristics from users or resources to which policies can be defined. These properties describe the relevant entities and are mainly + of two types: User Attributes and Object Attributes. User attributes describe the entities trying to access resources. These can be + characteristics such as roles, clearance levels, job title, etc. Moreove, object attributes describe the properties of the resources being + accessed and protected. These properties can be such as data classifications, sensitivity levels, file type, location, source, etc. + As an example, one can set attributes to behave as roles, e.g., the user 'Alice' can be assigned to the 'IT staff' attribute, while the + devices 'TempSensor1' and 'TempSensor2' are both assigned to the 'Sensor data' attribute. If a policy connects the User Attribute 'IT staff' + with the object attribute 'Sensor data', then Alice will be able to consume data from both Temperature sensors. + To express authorization policies over resources needing protection, a _resource_ object must be created in the policy engine. This newly created resource can be _associated_ to existing attributes using the _/management/associations_ endpoint. The same applies whenever a new _subject_ wanting to consume a _resource_ enters to the environment. A _subject_ object must be created in the policy engine, and it needs to be connected to an attribute using the _/management/associations_ endpoint. This association will connect the newly created _resource_ or _subject_ to existing authorization policies. + Connections between _User Attributes_ and _Object Attributes_ are made through the creation of _permissions_ by using the + _/management/permissions_ endpoint. Creating a permission means that the _User Attribute_ get permission for the specified _access-rights_ + to be executed on the specified _resource attribute_. This means, for example, if a permission using the user attribute 'IT staff' with the + _access-rights_ + version: 1.0.0 # Additional information present in the IDD template @@ -23,6 +45,14 @@ info: x-Ontology: to-add paths: + /ping: + get: + summary: Endpoint to check the core system availability. + description: Returns an OK to indicate that the core system is available. + responses: + '200': + description: OK + /management/associations: post: summary: Create a New association @@ -436,54 +466,45 @@ components: required: true schemas: - Policy: - type: object - required: - - name - - effect - properties: - id: - type: string - description: The unique identifier of the policy. - name: - type: string - description: The human-readable name of the policy. - description: - type: string - description: A detailed description of the policy. - access-rights: - type: array - items: - type: string - description: List of access rights that the policy controls. - subjects: - type: array - items: - type: string - description: List of entities subject to the policy. - resources: - type: array - items: - type: string - description: List of resources to which the policy applies. - effect: - type: string - enum: ['allow', 'deny', 'associate'] - description: The desired effect of the policy in the policy engine, this may allow the usage of ABAC, RBAC or rule-based - policy engine. For example, a policy containg only subjects, resources, and access-rights with the effect 'allow' would - create a rule-based policy (subject, ar, resource). A policy containing only subjects/resources and user-attributes/object-attributes - and with the effect 'associate' would create an attribute-based or role-based association between the specified user or object and - the respective attributes. The 'deny' effect can be used to create explicit access prohibitions. - user-attributes: - type: array - items: - type: string - description: List of user-attributes (ua) that the policy controls. - object-attributes: - type: array - items: - type: string - description: List of object-attributes (oa) that the policy controls. + + Association: + oneOf: + - $ref: "#/components/schemas/ResourceAttributeAssociation" + - $ref: "#/components/schemas/SubjectAttributeAssociation" + - $ref: "#/components/schemas/AttributeAttributeAssociation" + + ResourceAttributeAssociation: + type: object + properties: + resource: + $ref: '#/components/schemas/Resource' + attribute: + $ref: '#/components/schemas/Attribute' + required: + - resource + - attribute + + SubjectAttributeAssociation: + type: object + properties: + subject: + $ref: '#/components/schemas/Subject' + attribute: + $ref: '#/components/schemas/Attribute' + required: + - subject + - attribute + + AttributeAttributeAssociation: + type: object + properties: + attribute1: + $ref: '#/components/schemas/Attribute' + attribute2: + $ref: '#/components/schemas/Attribute' + required: + - attribute1 + - attribute2 Attribute: type: object @@ -529,6 +550,27 @@ components: description: Authentication information in case needed. E.g., certificate information of consuming systems. metadata: { $ref: '#/components/schemas/Metadata' } + Permission: + type: object + properties: + id: + type: string + description: "Identifier of the permission" + subjectAttribute: + $ref: "#/components/schemas/Attribute" + accessRights: + type: array + items: + type: string + description: "Access rights, e.g., ['consume']" + description: "List of access rights" + resourceAttribute: + $ref: "#/components/schemas/Attribute" + required: + - id + - subjectAttribute + - accessRights + Resource: required: type: object diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index 57397ea..d5dd948 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -1,8 +1,8 @@ openapi: 3.0.3 info: - title: Orchestration-pull service API description + title: Service Orchestration-pull service API description description: | - An API for using the orchestration-pull service of the Orchestration core system. This service + An API for using the Service Orchestration-pull service of the Orchestration core system. This service uses the orchestration store policies to recommend service providers to the requesting consumer to fulfil its task. @@ -120,11 +120,35 @@ components: example: {"interfaceName1":"token1"} interface: - description: A string that describes the interface in Protocol-SecurityType-MimeType format. SecurityType can be either SECURE or - INSECURE. - type: string - pattern: ^([a-zA-Z0-9_-]+)-(SECURE|INSECURE)-([a-zA-Z0-9_-]+)$ - example: HTTP-SECURE-JSON + description: An object describing interfaces used by services. This object contains information on the used + protocol and the security requirements. Depending on the protocol, additional properties could be appropriate, + such as 'version', 'contentTypes', 'ipv4Address', 'port', 'x509PublicKey', 'basePath' or 'topic'. The same + applying to security. + type: object + properties: + protocol: + type: object + properties: + name: + type: string + description: "Transport protocol, such as 'https', 'coaps+tcp', 'json-rpc', or 'mqtt'" + additionalProperties: true + required: + - name + security: + type: array + items: + type: object + properties: + name: + type: string + description: "Security method name, such as 'tokenAuthentication'" + additionalProperties: true + required: + - name + required: + - protocol + - security Metadata: description: | diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml index 51af3b0..a1e6ab1 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml @@ -1,8 +1,8 @@ asyncapi: 2.0.0 info: - title: Push Orchestration Service + title: Service Orchestration-push Service description: | - The push Orchestration service allows for systems to load System of systems (SoS) configurations into another systems. + The Service Orchestration-push service allows for systems to load System of systems (SoS) configurations into another systems. This allows to load service consumption directives remotely into systems to perform a task. If no configuration is specified in the triggering message, the active configuration on the orchestrator will be pushed From e91c884117156f3bde99fa85a7000fa455a64975 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 1 Feb 2024 10:35:12 +0100 Subject: [PATCH 19/23] Orchestration improvements Made the Orchestration a more stand-alone service which recommends configurations to systems, without giving the full information of the required connections --- ...arrowhead.orchestration-pull-http-json.yml | 64 ++++++------------- ...chestration-store-management-http-json.yml | 29 --------- 2 files changed, 18 insertions(+), 75 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index d5dd948..3a317af 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -39,7 +39,7 @@ paths: description: OK - /orchestration/orchestration-pull: + /orchestration/service-recommendations: post: summary: Submit a service request and get orchestration response. If no service definition is specified, the orchestration will return the suggested services and their appropriate providers for the consuming system to fulfil its tasks, depending @@ -63,9 +63,9 @@ paths: items: $ref: '#/components/schemas/OrchestrationResponse' - /orchestration/orchestration-pull/{id}: + /orchestration/service-recommendations/{id}: get: - summary: Get Orchestration by system id + summary: Get complete Orchestration plan for a given system, queried by system id parameters: - name: id in: path @@ -119,7 +119,7 @@ components: type: object example: {"interfaceName1":"token1"} - interface: + Interface: description: An object describing interfaces used by services. This object contains information on the used protocol and the security requirements. Depending on the protocol, additional properties could be appropriate, such as 'version', 'contentTypes', 'ipv4Address', 'port', 'x509PublicKey', 'basePath' or 'topic'. The same @@ -146,9 +146,6 @@ components: additionalProperties: true required: - name - required: - - protocol - - security Metadata: description: | @@ -207,7 +204,7 @@ components: items: $ref: '#/components/schemas/Interface' - RequestedService: + RequestedService: #TODO: How much of this information should be asked? type: object description: | Optional information of the required service. This object contains the service requirements of the requester @@ -215,47 +212,23 @@ components: properties: service-definition: type: string - description: Service definition + description: Service definition string identifier interfaces: type: array + description: Interface requirement items: $ref: '#/components/schemas/Interface' - security: - type: array - items: - $ref: '#/components/schemas/SecurityType' - metadata: - $ref: '#/components/schemas/Metadata' version: $ref: '#/components/schemas/VersionReq' + required: + - service-definition - Service: + ServiceInstance: type: object properties: - name: - type: string - description: Service instance human-readable name - service-type: - $ref: '#/components/schemas/TypeIdentifier' - version: - $ref: '#/components/schemas/Version' - addresses: - description: - A collection of addresses, each with a unique tag name. The tag names _may_ be used to - help a service consumer chose the most appropriate address. The service consumer may, - however, simply try all of them in any order until it finds one that works. - type: object - patternProperties: - .*: { $ref: '#/components/schemas/Address' } - interface: - type: array - items: - $ref: '#/components/schemas/Interface' - auth-info: - type: string - description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. - metadata: - $ref: '#/components/schemas/Metadata' + id: string + description: service instance unique identifier, the consumer getting the response use this to query the service registry to get + full service information and connection address. SecurityType: type: string @@ -271,7 +244,8 @@ components: description: Authentication token of the requesting system $ref: '#/components/schemes/Auth-tokens' requesting-system: - $ref: '#/components/schemas/RequesterSystem' + type: string + description: Requesting system unique identifier requested-service: $ref: '#/components/schemas/RequestedService' preferred-providers: @@ -282,17 +256,15 @@ components: OrchestrationResponse: type: object properties: - providers: + services: type: array items: - $ref: '#/components/schemas/ProviderSystem' - service: - $ref: '#/components/schemas/Service' + $ref: '#/components/schemas/ServiceInstance' warnings: type: array items: $ref: '#/components/schemas/Warning' - + Version: description: | A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml index 25cfc1d..4a3acc6 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml @@ -182,29 +182,6 @@ paths: components: schemas: - Address: - description: | - Identifies a _transport_ and a _location_. - - The _transport_ identifies the base protocol that facilitates addressing a specific service - instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` - and `unix`. A protocol only counts as a transport if it both (A) provides a way of - addressing and, by extension, sending messages to service providers and consumers, as well - as (B) does not build upon another protocol also providing this capability. I other words, - TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which - satisfy condition A. - - What the _location_ part consists of depends on what transport is identified. If the - transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal - numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If - the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in - [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a - colon and a port number. If the transport is `unix`, the location is an absolute filesystem - path to a Unix socket file. - type: string - pattern: ^(?[^:]+):\w*(?.*)$ - example: tcp4:192.168.0.7:45326 - ActiveConfiguration: type: object properties: @@ -227,10 +204,6 @@ components: description: set of rules that compose the configuration items: $ref: '#/components/schemas/Rule' - target: - type: object - description: Target of the orchestration configuration - #TODO: define how the target should look like, is it just one target? is it an array of targets? Are the targets within the rules? Metadata: description: | @@ -272,8 +245,6 @@ components: system-name: type: string description: human readable name of the system - address: - $ref: '#/components/schemas/Address' TimeToLive: description: TTL, duration specigying the maximun amount of time a service regristration remains valid before requiring renewal or From d85d10d5689cc1fc3383fa88f1086cd1e385fe57 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Wed, 7 Feb 2024 13:18:30 +0100 Subject: [PATCH 20/23] Fixed syntax errors --- .../eu.arrowhead.authorization-http-json.yml | 73 ++++---- ...ead.authorization-management-http-json.yml | 116 ++++++------- ...arrowhead.orchestration-pull-http-json.yml | 14 +- ...chestration-store-management-http-json.yml | 4 +- ....arrowhead.service-discovery-http-json.yml | 163 ++++++++++++++---- ...vice-registry-administration-http-json.yml | 6 +- 6 files changed, 240 insertions(+), 136 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml index 57918e4..58d9d05 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml @@ -78,40 +78,40 @@ paths: description: OK /authorizations: - post: - summary: Bulk Authorize access rights for Resources - description: | - Allows for bulk authorization requests to be sent to the authorization system in a single API request - - Queries the authorization system for authorization decision for each specified access right over the - specified subject and resource pair. - - As a reponse, for each request in the request body, an authorization decision will be returned. - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/AccessRequests' - examples: - example1: - summary: Three authorization requests from different users to different resources. - value: - - subject: "user123" - access-right: "write" - resource: "eu.arrowhead.tempreadings-http-json@MWtzOXIpaUEsOyEhc1NsTwo" - - subject: "MWtzOXIpaUEsOyEhc1NsTwo=" - access-right: "consume" - resource: "/OutsideTemp" - - subject: "user789" - access-right: "read" - resource: "91" - example2: - summary: a single authorization request. - value: - subject: "user234" - access-right: "read" - resource: "document4" + post: + summary: Bulk Authorize access rights for Resources + description: | + Allows for bulk authorization requests to be sent to the authorization system in a single API request + + Queries the authorization system for authorization decision for each specified access right over the + specified subject and resource pair. + + As a reponse, for each request in the request body, an authorization decision will be returned. + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AccessRequests' + examples: + example1: + summary: Three authorization requests from different users to different resources. + value: + - subject: "user123" + access-right: "write" + resource: "eu.arrowhead.tempreadings-http-json@MWtzOXIpaUEsOyEhc1NsTwo" + - subject: "MWtzOXIpaUEsOyEhc1NsTwo=" + access-right: "consume" + resource: "/OutsideTemp" + - subject: "user789" + access-right: "read" + resource: "91" + example2: + summary: a single authorization request. + value: + subject: "user234" + access-right: "read" + resource: "document4" responses: '200': description: Successful authorization @@ -133,11 +133,10 @@ paths: authorizationDecisions: ["allowed", "denied"] summary: Example response with both allowed and denied decisions example2: - value: + value: authorizationDecisions: ["allowed", "allowed", "denied"] summary: Example response with multiple decisions - - headers: + headers: Cache-Control: $ref: '#/components/headers/Cache-Control' Limit: diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml index c39ef84..66cda5f 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml @@ -108,7 +108,7 @@ paths: summary: Get Policy by ID description: Retrieve details of a specific policy by its identifier. parameters: - - name: policyId + - name: associationId in: path required: true schema: @@ -119,12 +119,12 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Policy' + $ref: '#/components/schemas/Association' put: - summary: Update Policy - description: Update an existing policy by its identifier. + summary: Update Association + description: Update an existing Association by its identifier. parameters: - - name: policyId + - name: associationId in: path required: true schema: @@ -134,19 +134,19 @@ paths: content: application/json: schema: - $ref: '#/components/schemas/Policy' + $ref: '#/components/schemas/Association' responses: '200': description: Successful operation content: application/json: schema: - $ref: '#/components/schemas/Policy' + $ref: '#/components/schemas/Association' delete: - summary: Delete Policy - description: Delete a policy by its identifier. + summary: Delete Association + description: Delete an Association by its identifier. parameters: - - name: policyId + - name: associationId in: path required: true schema: @@ -287,9 +287,9 @@ paths: '200': description: Successful operation content: - application/json: - schema: - $ref: '#/components/schemas/Subject' + application/json: + schema: + $ref: '#/components/schemas/Subject' delete: summary: Delete subject description: Delete a subject by its identifier. @@ -345,9 +345,9 @@ paths: '200': description: Successful operation content: - application/json: - schema: - $ref: '#/components/schemas/Resource' + application/json: + schema: + $ref: '#/components/schemas/Resource' delete: summary: Delete resource. description: Delete a resource by its identifier. @@ -391,9 +391,9 @@ paths: '200': description: Successful operation content: - application/json: - schema: - $ref: '#/components/schemas/Attribute' + application/json: + schema: + $ref: '#/components/schemas/Attribute' delete: summary: Delete user attribute. description: Delete an user attribute by its identifier. @@ -436,9 +436,9 @@ paths: '200': description: Successful operation content: - application/json: - schema: - $ref: '#/components/schemas/Attribute' + application/json: + schema: + $ref: '#/components/schemas/Attribute' delete: summary: Delete object attribute. description: Delete an object attribute by its identifier. @@ -467,44 +467,44 @@ components: schemas: - Association: - oneOf: - - $ref: "#/components/schemas/ResourceAttributeAssociation" - - $ref: "#/components/schemas/SubjectAttributeAssociation" - - $ref: "#/components/schemas/AttributeAttributeAssociation" + Association: + oneOf: + - $ref: "#/components/schemas/ResourceAttributeAssociation" + - $ref: "#/components/schemas/SubjectAttributeAssociation" + - $ref: "#/components/schemas/AttributeAttributeAssociation" - ResourceAttributeAssociation: - type: object - properties: - resource: - $ref: '#/components/schemas/Resource' - attribute: - $ref: '#/components/schemas/Attribute' - required: - - resource - - attribute + ResourceAttributeAssociation: + type: object + properties: + resource: + $ref: '#/components/schemas/Resource' + attribute: + $ref: '#/components/schemas/Attribute' + required: + - resource + - attribute - SubjectAttributeAssociation: - type: object - properties: - subject: - $ref: '#/components/schemas/Subject' - attribute: - $ref: '#/components/schemas/Attribute' - required: - - subject - - attribute + SubjectAttributeAssociation: + type: object + properties: + subject: + $ref: '#/components/schemas/Subject' + attribute: + $ref: '#/components/schemas/Attribute' + required: + - subject + - attribute - AttributeAttributeAssociation: - type: object - properties: - attribute1: - $ref: '#/components/schemas/Attribute' - attribute2: - $ref: '#/components/schemas/Attribute' - required: - - attribute1 - - attribute2 + AttributeAttributeAssociation: + type: object + properties: + attribute1: + $ref: '#/components/schemas/Attribute' + attribute2: + $ref: '#/components/schemas/Attribute' + required: + - attribute1 + - attribute2 Attribute: type: object @@ -573,9 +573,9 @@ components: Resource: required: - type: object - id - name + type: object properties: id: type: string diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index 3a317af..858f8be 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -1,4 +1,5 @@ openapi: 3.0.3 + info: title: Service Orchestration-pull service API description description: | @@ -18,8 +19,8 @@ info: requires orchestration. In case the _requested_service_ is specified, the requires service definition must be included in the form, in addition, at least one interface must be specified. The orchestration system will attempt to match the _requested-service_ information with services present on the orchestration rules or SoS configurations. + version: 5.0.0-rc.1 -version: 5.0.0-rc.1 # Additional information present in the IDD template x-transfer-protocol: [HTTP, HTTPS] @@ -226,9 +227,10 @@ components: ServiceInstance: type: object properties: - id: string - description: service instance unique identifier, the consumer getting the response use this to query the service registry to get - full service information and connection address. + id: + type: string + description: service instance unique identifier, the consumer getting the response use this to query the service registry to get + full service information and connection address. SecurityType: type: string @@ -242,7 +244,7 @@ components: properties: auth-tokens: description: Authentication token of the requesting system - $ref: '#/components/schemes/Auth-tokens' + $ref: '#/components/schemas/Auth-tokens' requesting-system: type: string description: Requesting system unique identifier @@ -287,7 +289,7 @@ components: $ref: '#/components/schemas/Version' Warning: - definition: A JSON object containing string warnings that may be returned as part of an orchestration response. + description: A JSON object containing string warnings that may be returned as part of an orchestration response. FROM_OTHER_CLOUD -> if the provider is in another cloud to that of the requesting system TTL_EXPIRED -> if the provider is no longer accessible TTL_EXPIRING -> the provider will be inaccessible within a short time diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml index 4a3acc6..2cb5135 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml @@ -1,4 +1,4 @@ -openapi: 3.0.0 +openapi: 3.0.3 info: title: Orchestration Management API description: | @@ -17,7 +17,7 @@ info: When setting active configurations, a time-to-live parameter can be defined to specify for how long the specific configuration is valid in the local cloud. -version: 5.0.0-rc.1 + version: 5.0.0-rc.1 # Additional information present in the IDD template x-transfer-protocol: [HTTP, HTTPS] diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml index 08cb0bb..0270214 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -74,43 +74,35 @@ paths: summary: Endpoint to check the core system availability. description: Returns an OK to indicate that the core system is available. responses: - '200': + '204': description: OK /services: get: - operationId: query + operationId: list description: | - Searches for records matching any query parameters. If no query parameters are specified, - any records the consuming system are permitted to access may be provided in the response. - - If the `limit` query parameter is used and given a value larger than 16, or if the `offset` - query parameter is used with any value, the operation is escalated from type `query` to type - `scan`. Permission to use the latter operation is intended only for consumers that need to - interact with larger number of service providers, that analyze larger numbers of records, - that list them for administrators or operators, or that have other special needs. + Lists the services registered in the service registry. Each service is returned with its + registered information, containing information on how to reach each service instance. + + As a default, only 16 services will be returned in the list request. This can be changed + by using the list-size parameter. - As long as the operation remains a plain `query`, it will always limit its response to 16 - records, unless a smaller `limit` is specified. If escalated to type `scan`, default and - maximum limits depend on how the service is configured. The limits may vary depending on the - attributes of the consumer, such as by allowing for a higher limit if the consumer is an - administrator. + Moreover, a filter string expression can be included in the request. This filter string refines + the list results to include only those services that satisfy the filter string. Especifications + on how filter strings are structurated can be found in '#/components/parameters/filter' - Any matching records a consumer are not allowed to access will be silently discarded before - the record limit is imposed. parameters: - - $ref: '#/components/parameters/query-limit' - $ref: '#/components/parameters/query-offset' - - $ref: '#/components/parameters/query-q' + - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/list-size' responses: '200': description: Matching service records. content: application/json: schema: - type: array - items: { $ref: '#/components/schemas/Record' } + $ref: '#/components/schemas/Records' headers: Cache-Control: $ref: '#/components/headers/Cache-Control' @@ -239,19 +231,20 @@ components: explode: false allowReserved: true - query-limit: - name: limit + list-size: + name: size in: query description: | An indication of the maximum number of records a consuming system wants to have included in - the response to its query. + the response to the list request. example: 24 schema: description: | Indicates a maximum number of records a consuming service wishes to have included in the - response to some query. + response to the list request. type: number format: int32 + default: 16 minimum: 1 query-offset: @@ -283,6 +276,40 @@ components: explode: false allowReserved: true + filter: + name: filterString + in: query + description: | + Filter expressions to refine the results from the list request to the service registry. A filter + string is composed by one or more filter expressions, which are composed of a parameter, a matching + operator, and a value. For example: + Equality & Inequality checks + == "" + != "" + + Scalar comparison + > "" + >= "" + < "" + <= "" + + Emptiness checks + is empty + is not empty + + Contains checks or Substring Matching + "" in + "" not in + contains "" + not contains "" + + Valid parameters can be: Version, Interface, Security, ServiceType, Address, Port, ServiceInstanceID, ServiceName. + + Multiple expressions can be used to compose a filter string. These expressions can be connected with Boolean operators + such as 'or', 'and', 'not'. The composition of filter strings allows for parenthesis grouping. + schema: + type: string + responses: 400-BadRequest-ExpressionIsInvalid: @@ -511,6 +538,34 @@ components: type: string example: "Required property missing: 'interfaces'." + Interface: + description: An object describing interfaces used by services. This object contains information on the used + protocol and the security requirements. Depending on the protocol, additional properties could be appropriate, + such as 'version', 'contentTypes', 'ipv4Address', 'port', 'x509PublicKey', 'basePath' or 'topic'. The same + applying to security. + type: object + properties: + protocol: + type: object + properties: + name: + type: string + description: "Transport protocol, such as 'https', 'coaps+tcp', 'json-rpc', or 'mqtt'" + additionalProperties: true + required: + - name + security: + type: array + items: + type: object + properties: + name: + type: string + description: "Security method name, such as 'tokenAuthentication'" + additionalProperties: true + required: + - name + Metadata: description: | Additional details of relevance when consuming a service. What metadata is made available @@ -560,7 +615,7 @@ components: name: type: string description: Service instance human-readable name - service-type: + serviceType: $ref: '#/components/schemas/TypeIdentifier' version: $ref: '#/components/schemas/Version' @@ -570,18 +625,53 @@ components: help a service consumer chose the most appropriate address. The service consumer may, however, simply try all of them in any order until it finds one that works. type: object - patternProperties: - .*: { $ref: '#/components/schemas/Address' } + additionalProperties: + $ref: '#/components/schemas/Address' interface: type: array items: $ref: '#/components/schemas/Interface' - auth-info: + authInfo: type: string description: Specifies the authentication method needed (if any) to consume this service, e.g., certificate, token, etc. metadata: $ref: '#/components/schemas/Metadata' + ServiceQuery: + type: object + description: Object with properties needed to refine the list results from the service registry list operation. All parameters + in this object are optional. Version, Interface, Security, ServiceType, Address, Port, ServiceInstanceID, ServiceName. + properties: + serviceInstanceIDs: + type: array + items: + type: string + description: The list of service instances IDs required in the list results. + ServiceNames: + type: array + items: + type: string + description: The list of service names required in the list results + VersionReq: + description: Service version requirements + $ref: '#/components/schemas/VersionReq' + AddressReq: + description: Service address requirements + type: array + items: + $ref: '#/components/schemas/Address' + interfacesReq: + type: array + description: Interface requirement + items: + $ref: '#/components/schemas/Interface' + + Records: + type: array + description: Envelope for array of Results for service list response. + items: + $ref: '#/components/schemas/Record' + Record: type: object properties: @@ -593,7 +683,7 @@ components: description: The ID of the system which produces the registered service. service: $ref: '#/components/schemas/Service' - time-to-live: + timeToLive: $ref: '#/components/schemas/TimeToLive' required: - serviceID @@ -629,3 +719,16 @@ components: type: string pattern: ^\d+(?:\.\d+(?:\.\d+)?)?$ example: 1.4 + + VersionReq: + description: | + Object describing the required service version, maximun version and minimun version allowed for the + required service. + type: object + properties: + version-required: + $ref: '#/components/schemas/Version' + min-version: + $ref: '#/components/schemas/Version' + max-version: + $ref: '#/components/schemas/Version' diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index 34075bd..091960c 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -141,8 +141,8 @@ components: help a service consumer chose the most appropriate address. The service consumer may, however, simply try all of them in any order until it finds one that works. type: object - patternProperties: - .*: { $ref: '#/components/schemas/Address' } + additionalProperties: + $ref: '#/components/schemas/Address' interface: type: array items: @@ -178,7 +178,7 @@ components: pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ example: 2d12h - interface: + Interface: description: A string that describes the interface in Protocol-SecurityType-MimeType format. SecurityType can be either SECURE or INSECURE. type: string From 755ddcc71399435dbf3c3efc64211ef5d86ab2b3 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Thu, 8 Feb 2024 13:18:26 +0100 Subject: [PATCH 21/23] Changed filter mechanism for Service discovery Added serviceQuery as an object to be filled with the service requirements --- .../eu.arrowhead.service-discovery-http-json.yml | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml index 0270214..05c38c8 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -88,13 +88,13 @@ paths: As a default, only 16 services will be returned in the list request. This can be changed by using the list-size parameter. - Moreover, a filter string expression can be included in the request. This filter string refines - the list results to include only those services that satisfy the filter string. Especifications - on how filter strings are structurated can be found in '#/components/parameters/filter' + Moreover, a service Query object can be included in the request. This service query refines + the list results to include only those services that satisfy the requirements specified in the + Service Query object. parameters: - $ref: '#/components/parameters/query-offset' - - $ref: '#/components/parameters/filter' + - $ref: '#/components/parameters/serviceQueryParam' - $ref: '#/components/parameters/list-size' responses: '200': @@ -310,6 +310,14 @@ components: schema: type: string + serviceQueryParam: + name: serviceQuery + in: query + description: | + Service object with filtering requirements for service discovery. All parameters in the object are optional. + schema: + $ref: '#/components/schemas/ServiceQuery' + responses: 400-BadRequest-ExpressionIsInvalid: From 98e111ea0b8c8de2ebd0a3e7cba200721830b4f1 Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Tue, 13 Feb 2024 14:59:46 +0100 Subject: [PATCH 22/23] Update eu.arrowhead.service-discovery-http-json.yml Simplified interaction with the service discovery interfaces. Service discovery interfaces are not only able to register, unregister and list services. Modifying existing entries is restricted to service-registry-administration interfaces. --- ....arrowhead.service-discovery-http-json.yml | 54 ++++++++++++------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml index 05c38c8..b8702b9 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -119,25 +119,25 @@ paths: '500': { $ref: '#/components/responses/500-InternalServerError' } '503': { $ref: '#/components/responses/503-ServiceUnavailable' } - patch: - operationId: register + /services/register: + post: + summary: Add a new service entry description: | - Registers or updates one or more records. + Registers one or more records. The combination of the provider and type identifiers inside each record must be unique. - Providing a record when a corresponding combination of identifiers are already registered - will be interpreted as an attempt to replace the existing record. If more than one record - with corresponding identifiers are in the request, the last one in its payload will replace - all others. + If more than one record with corresponding identifiers are in the request, the last one + in its payload will replace all others. requestBody: + required: true content: application/json: schema: - type: array - items: { $ref: '#/components/schemas/Record' } + $ref: '#/components/schemas/Records' + responses: '204': - description: Confirms that the records in question have been registered or updated. + description: Confirms that the records in question have been registered. '400': { $ref: '#/components/responses/400-BadRequest-RecordIsInvalid' } '401': { $ref: '#/components/responses/401-Unauthorized' } '403': { $ref: '#/components/responses/403-Forbidden' } @@ -148,23 +148,39 @@ paths: '431': { $ref: '#/components/responses/431-RequestHeaderFieldsTooLarge' } '500': { $ref: '#/components/responses/500-InternalServerError' } '503': { $ref: '#/components/responses/503-ServiceUnavailable' } + + /services/{service-id}: + get: + summary: get service by ID + description: Retrieve details of a specific service entry by its identifier. + parameters: + - name: service-id + in: path + required: true + schema: + type: string + responses: + '200': + description: Successful operation + content: + application/json: + schema: + $ref: '#/components/schemas/Record' delete: operationId: deregister description: | - Deregisters all records matching any query parameters. If no query parameters are specified, - all records are deregistered the consuming system are permitted to deregister. + Deregisters the service matching the service-id. - A provider wishing to deregister all of its own service records _should_ avoid sending plain - `DELETE /services` requests. If it has more access rights than it is aware of, it may - deregister more services than it intended. To ensure only its own services are deregistered, - it _should_ add its own provider identifier as part of the query parameter, as in - `DELETE /services?q=@MWtzOXIpaUEsOyEhc1NsTwo=`. parameters: - - $ref: '#/components/parameters/deregister-q' + - name: service-id + in: path + required: true + schema: + type: string responses: '204': - description: Confirms that the records in question have been deregistered. + description: Confirms that the record in question have been deregistered. '400': { $ref: '#/components/responses/400-BadRequest-ExpressionIsInvalid' } '401': { $ref: '#/components/responses/401-Unauthorized' } '403': { $ref: '#/components/responses/403-Forbidden' } From 79671719570b9326d5406e87dd1198ddd6fc60ee Mon Sep 17 00:00:00 2001 From: Alex Chiquito Date: Tue, 13 Feb 2024 16:48:55 +0100 Subject: [PATCH 23/23] Sinetiq version for Arrowhead Pull Request Final fixings, removal of additional information from IDD templates. --- .../eu.arrowhead.authorization-http-json.yml | 8 - ...ead.authorization-management-http-json.yml | 7 - ...arrowhead.orchestration-pull-http-json.yml | 147 ++---------------- .../eu.arrowhead.orchestration-push.yml | 13 +- ...chestration-store-management-http-json.yml | 21 ++- ....arrowhead.service-discovery-http-json.yml | 8 - ...vice-registry-administration-http-json.yml | 49 +++++- 7 files changed, 70 insertions(+), 183 deletions(-) diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml index 58d9d05..9465fb2 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-http-json.yml @@ -58,14 +58,6 @@ info: payloads up to 4096 bytes in size. If payload compression is supported, then this limit applies after decompression. version: 5.0.0-rc.1 - - # Additional information present in the IDD template - x-transfer-protocol: [HTTP, HTTPS] - x-encryption-method: to-add - x-encoding: JSON - x-compression: to-add - x-semantics: to-add - x-Ontology: to-add paths: diff --git a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml index 66cda5f..6bb3576 100644 --- a/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Authorization System/eu.arrowhead.authorization-management-http-json.yml @@ -36,13 +36,6 @@ info: version: 1.0.0 - # Additional information present in the IDD template - x-transfer-protocol: [HTTP, HTTPS] - x-encryption-method: to-add - x-encoding: JSON - x-compression: to-add - x-semantics: to-add - x-Ontology: to-add paths: /ping: diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml index 858f8be..66ea46b 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-pull-http-json.yml @@ -3,12 +3,11 @@ openapi: 3.0.3 info: title: Service Orchestration-pull service API description description: | - An API for using the Service Orchestration-pull service of the Orchestration core system. This service - uses the orchestration store policies to recommend service providers to the requesting consumer to fulfil - its task. + An API for using the Service Orchestration-pull service of the Orchestration core system. This service uses the orchestration store policies + to recommend service providers to the requesting consumer to fulfil its task. - The consumer system request for orchestration either by specifying the service definition that the consumer requires or - by using stored SoS configurations or Orchestration rules if no service information is defined. + The consumer system request for orchestration either by specifying the service definition that the consumer requires or by using stored SoS + configurations or Orchestration rules if no service information is defined. _SoS configurations_ represents the connections needed in a SoS for it to perform its designed task. This means, describing what services must each of the systems consume to perform their individual tasks. A SoS configuration can be seen as a series of _Orchestration rules_. @@ -17,18 +16,10 @@ info: In the context of this document, we reffer to the Orchestration consumer as _requesting-system_ where _system-id_ is the unique identifier that represents that system. The _requested-service_ represents the service information that the _requesting-system_ requires orchestration. In case the _requested_service_ is specified, the requires service definition must be included in the form, - in addition, at least one interface must be specified. The orchestration system will attempt to match the _requested-service_ information - with services present on the orchestration rules or SoS configurations. - version: 5.0.0-rc.1 - + The orchestration system will attempt to match the _requested-service_ information with services present on the orchestration rules or SoS + configurations. -# Additional information present in the IDD template -x-transfer-protocol: [HTTP, HTTPS] -x-encryption-method: to-add -x-encoding: JSON -x-compression: to-add -x-semantics: to-add -x-Ontology: to-add + version: 5.0.0-rc.1 paths: /orchestration/echo: @@ -47,7 +38,7 @@ paths: on a existing SoS configuration or Orchestration rules. Information of the requesting system is mandatory. Requested service is optional. If a requested service object is specified, - the service definition and at least one interface must be specified. + the service definition must be specified. requestBody: required: true content: @@ -91,63 +82,13 @@ paths: components: schemas: - Address: - description: | - Identifies a _transport_ and a _location_. - - The _transport_ identifies the base protocol that facilitates addressing a specific service - instance. Examples of transports that can be supported are `tcp4`, `tcp6`, `udp4`, `udp6` - and `unix`. A protocol only counts as a transport if it both (A) provides a way of - addressing and, by extension, sending messages to service providers and consumers, as well - as (B) does not build upon another protocol also providing this capability. I other words, - TLS and DTLS are _not_ transports, because they build upon the TCP and UDP protocols, which - satisfy condition A. - - What the _location_ part consists of depends on what transport is identified. If the - transport is `tcp4` or `udp4`, the location is an IPv4 address expressed as four decimal - numbers separated by dots, a colon and a port number, such as in `192.168.3.22:64075`. If - the transport is `tcp6` or `udp6`, the location is an IPv6 address, rendered as described in - [RFC 5952](https://www.rfc-editor.org/rfc/rfc5952), within square brackets, followed by a - colon and a port number. If the transport is `unix`, the location is an absolute filesystem - path to a Unix socket file. - type: string - pattern: ^(?[^:]+):\w*(?.*)$ - example: tcp4:192.168.0.7:45326 Auth-tokens: description: | - An (k,v) object containing authorization tokens for each interface contained in the response + An (k,v) object containing authorization tokens required to consume orchestration services type: object example: {"interfaceName1":"token1"} - Interface: - description: An object describing interfaces used by services. This object contains information on the used - protocol and the security requirements. Depending on the protocol, additional properties could be appropriate, - such as 'version', 'contentTypes', 'ipv4Address', 'port', 'x509PublicKey', 'basePath' or 'topic'. The same - applying to security. - type: object - properties: - protocol: - type: object - properties: - name: - type: string - description: "Transport protocol, such as 'https', 'coaps+tcp', 'json-rpc', or 'mqtt'" - additionalProperties: true - required: - - name - security: - type: array - items: - type: object - properties: - name: - type: string - description: "Security method name, such as 'tokenAuthentication'" - additionalProperties: true - required: - - name - Metadata: description: | Additional details of relevance when consuming a service. What metadata is made available @@ -156,56 +97,7 @@ components: type: object example: {"basePath":"v2"} - PreferredProvider: - type: object - description: information of a preferred provider to consume services from. - properties: - provider-cloud: - $ref: '#/components/schemas/ProviderCloud' - provider: - $ref: '#/components/schemas/ProviderSystem' - - ProviderSystem: - type: object - description: information describing a provider system within a local cloud. - properties: - system-name: - type: string - address: - $ref: '#/components/schemas/Address' - - ProviderCloud: - type: object - description: an object describing the cloud in which a provider is located - properties: - operator: - type: string - description: Name of the operator company - name: - type: string - description: name of the cloud - - RequesterSystem: - type: object - description: Information of the system requesting orchestration information. - properties: - system-name: - type: string - description: Short human readable system name. - systemID: - type: string - description: unique identifier of requester system - address: - $ref: '#/components/schemas/Address' - auth-info: - type: string - description: Authentication info, i.e, CERTIFICATE, TOKEN, etc. - interface: - type: array - items: - $ref: '#/components/schemas/Interface' - - RequestedService: #TODO: How much of this information should be asked? + RequestedService: type: object description: | Optional information of the required service. This object contains the service requirements of the requester @@ -214,11 +106,9 @@ components: service-definition: type: string description: Service definition string identifier - interfaces: - type: array - description: Interface requirement - items: - $ref: '#/components/schemas/Interface' + service-type: + type: string + description: Service type string identifier version: $ref: '#/components/schemas/VersionReq' required: @@ -232,13 +122,6 @@ components: description: service instance unique identifier, the consumer getting the response use this to query the service registry to get full service information and connection address. - SecurityType: - type: string - enum: - - TOKEN - - NON-SECURE - - CERTIFICATE - ServiceRequestForm: type: object properties: @@ -250,10 +133,6 @@ components: description: Requesting system unique identifier requested-service: $ref: '#/components/schemas/RequestedService' - preferred-providers: - type: array - items: - $ref: '#/components/schemas/PreferredProvider' OrchestrationResponse: type: object diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml index a1e6ab1..047c298 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-push.yml @@ -15,14 +15,6 @@ info: version: 5.0.0-rc.1 -# Additional information present in the IDD template -x-transfer-protocol: [to-add] -x-encryption-method: to-add -x-encoding: JSON -x-compression: to-add -x-semantics: to-add -x-Ontology: to-add - channels: pushConfiguration: address: 'orchestration/push' @@ -78,9 +70,10 @@ components: items: $ref: '#/components/schemas/Rule' target: - type: object + type: array description: Target of the orchestration configuration - #TODO: define how the target should look like, is it just one target? is it an array of targets? Are the targets within the rules? + items: + $ref: '#/components/schemas/System' Metadata: description: | diff --git a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml index 2cb5135..2ef641f 100644 --- a/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml +++ b/5.0 Draft/IDD/IDDs Orchestration System/eu.arrowhead.orchestration-store-management-http-json.yml @@ -19,13 +19,6 @@ info: is valid in the local cloud. version: 5.0.0-rc.1 -# Additional information present in the IDD template -x-transfer-protocol: [HTTP, HTTPS] -x-encryption-method: to-add -x-encoding: JSON -x-compression: to-add -x-semantics: to-add -x-Ontology: to-add paths: /orchestration/rules: @@ -234,9 +227,14 @@ components: serviceID: type: string description: identifier of service - serviceInstance: + serviceDefinition: type: string description: name of the service instance + serviceType: + type: string + description: name of the service type + version: + $ref: '#/components/schemas/Version' System: type: object @@ -253,3 +251,10 @@ components: pattern: ^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$ example: 2d12h + Version: + description: | + A MAJOR, MINOR and a PATCH number, separated by dots. If both or the latter of the MINOR and + PATCH numbers are omitted, the ones omitted are assumed to be zero. + type: string + pattern: ^\d+(?:\.\d+(?:\.\d+)?)?$ + example: 1.4 \ No newline at end of file diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml index b8702b9..e28d8d5 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-discovery-http-json.yml @@ -49,7 +49,6 @@ info: Every service instance registered via this service interface _must_ be associated with a unique identifier. In contexts where authentication is not used, providers _must_ chose their own identifiers. Those identifiers _should_ remain consistent between restarts of those providers. - In contexts where authentication is used, the identifier _must_ be derived as follows: TODO. ## Size Limits @@ -59,13 +58,6 @@ info: limit the sizes of individual parts within each request. It _must_, however, receive request URI:s up to 2816 bytes in size, as well as request payloads up to 4096 bytes in size. version: 5.0.0-rc.1 - # Additional information present in the IDD template - x-transfer-protocol: [HTTP, HTTPS] - x-encryption-method: to-add - x-encoding: JSON - x-compression: to-add - x-semantics: to-add - x-Ontology: to-add paths: diff --git a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml index 091960c..b7bfb69 100644 --- a/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml +++ b/5.0 Draft/IDD/IDDs Service Registry/eu.arrowhead.service-registry-administration-http-json.yml @@ -8,15 +8,48 @@ info: registry catalog. To register a service, the service provider, a system administrator, or a supporting system must fill a _ServiceEntry_ object with the details of the service and the service provider. Additional inforation can be especified in the _metadata_ parameter. - version: 1.0.0 - # Additional information present in the IDD template - x-transfer-protocol: [HTTP, HTTPS] - x-encryption-method: to-add - x-encoding: JSON - x-compression: to-add - x-semantics: to-add - x-Ontology: to-add + ## Compression and Language + + An implementation of this service interface _may_ be designed to support compression and/or + human-readable error texts in different languages than English, as described in + [RFC 9110, Section 12](https://www.rfc-editor.org/rfc/rfc9110#name-content-negotiation). Not + using compression _must_ be supported and be the default. Also, the default language for error + messages _must_ be American English (`en-US`). + + ## Managing Record Life-Cycles + + In a typical use case, this service interface is meant to hold records for all service providers + currently part of its context. When a service provider joins or leaves a context, it is expected + to register and deregister its services, respectively. However, service providers can fail or be + detached from the context before they get a chance to deregister their services. This can make + it relevant to monitor service providers and temporarily suppress or permanently prune records + associated with unhealthy or inaccessible providers. Implementations of this service interface + are free to suppress and/or prune records in whatever way best supports the use cases they are + designed for. + + ## Record Ownership + + It is the provider indicated inside each record that is the owner of the record, and not the + consumer registering it. This means that a consumer may be forbidden from registering or + deregistering a record for certain or all other service providers, even if it may register + and/or deregister records with itself as provider. + + ## Provider Identifiers + + Every service instance registered via this service interface _must_ be associated with a unique + identifier. In contexts where authentication is not used, providers _must_ chose their own + identifiers. Those identifiers _should_ remain consistent between restarts of those providers. + + ## Size Limits + + As a mitigation against denial-of-service attacks, all implementations of this service + interface _should_ reject incoming requests that are larger than a predefined limit. That limit + _must not_ be smaller than 8192 bytes for each received request. An implementation _may_ also + limit the sizes of individual parts within each request. It _must_, however, receive request + URI:s up to 2816 bytes in size, as well as request payloads up to 4096 bytes in size. + + version: 1.0.0 paths: /service-registry/list: