Proposal to simplify device object and improve interoperability #233
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,8 +30,11 @@ This document captures guidelines for the API design in CAMARA project. These gu | |
| - [5.1 Versioning Strategy](#51-versioning-strategy) | ||
| - [5.2 Backwards and Forward Compatibility](#52-backwards-and-forward-compatibility) | ||
| - [6. Error Responses](#6-error-responses) | ||
| - [6.1 Standardized use of CAMARA error responses](#61-standardized-use-of-camara-error-responses) | ||
| - [6.2 Error Responses - Device Object](#62-error-responses---device-object) | ||
| - [Templates](#templates) | ||
| - [Response template](#response-template) | ||
| - [Examples template](#examples-template) | ||
| - [7. Common Data Types](#7-common-data-types) | ||
| - [8. Pagination, Sorting and Filtering](#8-pagination-sorting-and-filtering) | ||
| - [8.1 Pagination](#81-pagination) | ||
|
|
@@ -43,6 +46,8 @@ This document captures guidelines for the API design in CAMARA project. These gu | |
| - [10.2 Security Implementation](#102-security-implementation) | ||
| - [11. Definition in OpenAPI](#11-definition-in-openapi) | ||
| - [11.1 General Information](#111-general-information) | ||
| - [Info object](#info-object) | ||
| - [Servers object](#servers-object) | ||
| - [11.2 Published Routes](#112-published-routes) | ||
| - [11.3 Request Parameters](#113-request-parameters) | ||
| - [11.4 Response Structure](#114-response-structure) | ||
|
|
@@ -51,8 +56,14 @@ This document captures guidelines for the API design in CAMARA project. These gu | |
| - [Inheritance](#inheritance) | ||
| - [Polymorphism](#polymorphism) | ||
| - [11.6 Security definition](#116-security-definition) | ||
| - [OpenAPI security schemes definition](#openapi-security-schemes-definition) | ||
| - [Expressing Security Requirements](#expressing-security-requirements) | ||
| - [Mandatory template for `info.description` in CAMARA API specs](#mandatory-template-for-infodescription-in-camara-api-specs) | ||
| - [11.6.1 Scope naming](#1161-scope-naming) | ||
| - [APIs which do not deal with explicit subscriptions](#apis-which-do-not-deal-with-explicit-subscriptions) | ||
| - [Examples](#examples) | ||
PedroDiez marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - [APIs which deal with explicit subscriptions](#apis-which-deal-with-explicit-subscriptions) | ||
| - [API-level scopes (sometimes referred to as wildcard scopes in CAMARA)](#api-level-scopes-sometimes-referred-to-as-wildcard-scopes-in-camara) | ||
| - [12. Subscription, Notification \& Event](#12-subscription-notification--event) | ||
| - [12.1 Subscription](#121-subscription) | ||
| - [Instance-based (implicit) subscription](#instance-based-implicit-subscription) | ||
|
|
@@ -68,6 +79,7 @@ This document captures guidelines for the API design in CAMARA project. These gu | |
| - [Security Considerations](#security-considerations) | ||
| - [Abuse Protection](#abuse-protection) | ||
| - [Notification examples](#notification-examples) | ||
| - [Appendix A: `info.description` template for `device` identification from access token](#appendix-a-infodescription-template-for-device-identification-from-access-token) | ||
|
|
||
|
|
||
| ## Common Vocabulary and Acronyms | ||
|
|
@@ -1372,7 +1384,9 @@ The documentation template available in [CAMARA API Specification - Authorizatio | |
|
|
||
| #### 11.6.1 Scope naming | ||
|
|
||
| ##### APIs which do not deal with explicit subscriptions | ||
|
|
||
| Regarding scope naming for APIs which do not deal with explicit subscriptions, the guidelines are: | ||
|
|
||
| * Define a scope per API operation with the structure: | ||
|
|
||
|
|
@@ -1395,6 +1409,7 @@ where | |
| - `write` : For operations creating or modifying the resource, when differentiation between `create` and `update` is not needed. | ||
|
|
||
| * Eventually we may need to add an additional level to the scope, such as `api-name:[resource:]action[:detail]`, to deal with cases when only a set of parameters/information has to be allowed to be returned. Guidelines should be enhanced when those cases happen. | ||
|
|
||
| ###### Examples | ||
|
|
||
| | API | path | method | scope | | ||
|
|
@@ -1405,8 +1420,9 @@ where | |
|
|
||
| <br> | ||
|
|
||
| ##### APIs which deal with explicit subscriptions | ||
|
|
||
| Regarding scope naming for APIs which deal with explicit subscriptions, the guidelines propose some changes as compared to the above format and this is described below: | ||
|
|
||
| Scopes should be represented as below for APIs that offer explicit event subscriptions with action read and delete: | ||
|
|
||
|
|
@@ -1421,7 +1437,8 @@ Event-type: org.camaraproject.device-roaming-subscriptions.v0.roaming-on | |
| Grant-level, action on resource: create | ||
| For e.g. device-roaming-subscriptions:org.camaraproject.device-roaming-subscriptions.v0.roaming-on:create | ||
|
|
||
| ##### API-level scopes (sometimes referred to as wildcard scopes in CAMARA) | ||
|
|
||
| The decision on the API-level scopes was made within the [Identity and Consent Management Working Group](https://github.com/camaraproject/IdentityAndConsentManagement) and is documented in the design guidelines to ensure completeness of this document. The scopes will always be those defined in the API Specs YAML files. Thus, a scope would only provide access to all endpoints and resources of an API if it is explicitly defined in the API Spec YAML file and agreed in the corresponding API subproject. | ||
|
|
||
|
|
||
|
|
@@ -1800,3 +1817,41 @@ response: | |
| ```http | ||
| 204 No Content | ||
| ``` | ||
|
|
||
| ## Appendix A: `info.description` template for `device` identification from access token | ||
|
|
||
| The documentation template below is recommended to be used as part of the API documentation in `info.description` property in the CAMARA API specs which use the `device`object defined in [CAMARA_common.yaml](https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml) artifact. This template provides guidance on how to handle device information in API requests **when using 3-legged access tokens and the device can be uniquely identified by the token**. | ||
|
|
||
| Note: With the current 3-legged authorization flows used by CAMARA, only a single end user can be associated with the access token. For the OIDC authorization code flow, only a single device can call the `/authorize` endpoint and obtain the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). | ||
|
|
||
| ```md | ||
| # Identifying a device from the access token | ||
|
|
||
| This specification defines the `device` object field as optional in API requests, specifically in cases where the API is accessed using a 3-legged access token and the device can be uniquelly identified by the token. This approach simplifies API usage for API consumers by relying on the device information associated with the access token used to invoke the API. | ||
|
|
||
| ## Handling of device information: | ||
|
|
||
| ### Optional device object for 3-legged tokens: | ||
|
|
||
| - When using a 3-legged access token, the device associated with the access token must be considered as the device for the API request. This means that the device object is not required in the request, and if included it must identify the same device, therefore **it is recommended NOT to include it in these scenarios** to simplify the API usage and avoid additional validations. | ||
|
|
||
|
There was a problem hiding this comment. We (E///) think that we rather should recommend to have the additional validation in place and compare the target device in the access token against the target device named on the API input. This gives additional security and allows for a better reporting in line with GDPR. There was a problem hiding this comment. I don't see how comparing the device identifier in the API request to the target device in the access token provides any additional security. And if we take the access token information as the source of truth, if we can rely directly on the access token, we would avoid additional validations that add complexity and new potential points of failure. In addition to improving interoperability as explained in #171 (comment) |
||
| ### Validation mechanism: | ||
|
|
||
| - The server will extract the device identification from the access token, if available. | ||
| - If the API request additionally includes a `device` object when using a 3-legged access token, the API will validate that the device identifier provided matches the one associated with the access token. | ||
| - If there is a mismatch, the API will respond with a 403 - INVALID_TOKEN_CONTEXT error, indicating that the device information in the request does not match the token. | ||
|
|
||
| ### Error handling for unidentifiable devices: | ||
|
|
||
| - If the `device` object is not included in the request and the device information cannot be derived from the 3-legged access token, the server will return a 422 `UNIDENTIFIABLE_DEVICE` error. | ||
|
|
||
| ### Restrictions for tokens without an associated authenticated identifier: | ||
|
|
||
| - For scenarios which do not have a single device identifier associated to the token during the authentication flow, e.g. 2-legged access tokens, the `device` object MUST be provided in the API request. This ensures that the device identification is explicit and valid for each API call made with these tokens. | ||
| ``` | ||
|
|
||
| By following these guidelines, API consumers can use the authenticated device identifier associated with 3-legged access tokens, simplifying implementation and validation. This mechanism ensures that device identification is handled efficiently and securely, and appropriately accommodates different token types. | ||
|
|
||
| Depending on the functionality provided by the CAMARA API, some API subprojects may still define other specific identifiers that differs from the common `device` object definition. Not all APIs necessarily have to refer to a device, e.g. Carrier Billing API only defines a phone number as a way to identify the mobile account to be billed, Know Your Costumer only defines a phone number as a way to identify the associated account data or Home Devices QoD API defines public IP v4 address as a way to identify the user home network. | ||
|
|
||
| Therefore, the mechanism described in this template is not applicable to all APIs, but could be used as way to make `device` object more interoperable and usable for API consumers. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We do not think that it is reasonable to remove the networkAccessIdentifier, even though it is not widely used yet.
We actually would like to add a further option to allow identification via the operator token.
For security reasons we see a mandatory need to allow verification of the data subject named in the access token against the target resource, which is input to the api call. We need to keep all option open, especially since we are discussing (in issue #145 in ICM group requesting to support the operator token).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
We are focusing on a proposal in the scope of the next meta release. The proposal to remove the networkAccessIdentifier is precisely because the feedback so far has been favourable to doing so, and there is no explicit feedback from any WG participant that they are currently using it. Of course, it could be revisited for future releases if the WG needs it, and it could be re-evaluated whether or not to include it again.
The operatorToken discussed in camaraproject/IdentityAndConsentManagement#145 is just an open discussion for now (in ICM backlog), so I would suggest not even considering it for this meta release. In fact, operatorToken might fit as networkAccessIdentifier from our point of view, but it should be discussed for a release when there is a clear position and solution defined in CAMARA for operatorToken.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we try to find a middle way here? I would propose that we could write in the guidelines that the networkAccessIdentifier is only part of the schema to be able to be future-proof and Camara currently does not permit its use.
Post meta-release work, and after the resolution of the relevant issues in ICM, its use will have to be explicitly documented in ICM and in the guidelines.
This will be similar to what we have done for subscriptions where even though event type is an array (for being future-proof), we are allowing for the meta release the use of just single event type and after the meta-release we will target usecases which need subscriptions to support multiple event types.
WDYT?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If it works and helps us reach an agreement, that would be fine with me. But I think it would be better to just have an artifact definition of what needs to be supported and allowed to be used. And then just evolve it in the next releases.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@Elisabeth-Ericsson : Could you please confirm if this suggested middle way would be ok for you as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Middle way agreement applied in 4ae03bb
Please have a look @shilpa-padgaonkar @Elisabeth-Ericsson and suggest any necessary changes to the wording I use.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If an API client only provides the networkAccessIdentifier, we can return a 422 error, and if the networkAccessIdentifier is provided along with other allowed identifiers, it should be ignored.
Should we also add this to the NOTE included in the common.yaml file? Should it be documented in the corresponding API subprojects?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This clarification is very useful, could you confirm if we can add this in our API subprojects?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is general guideline in API Design Guidelines section 6.2 Error Responses - Device Object.
The clarification above is in line with it, so it can be added in subprojects.
If more detailed guideline is needed for networkAccessIdentifier it can be added as a fix for API Design Guidelines.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Agree with Rafal