From 4115919f193efebe95e21504837e406056b7a581 Mon Sep 17 00:00:00 2001 From: Kevin Smith Date: Tue, 17 Dec 2024 11:07:34 +0000 Subject: [PATCH] Update device identification, fixes #60 Fixes #60 --- .../simple-edge-discovery.yaml | 62 +++++++------------ 1 file changed, 22 insertions(+), 40 deletions(-) diff --git a/code/API_definitions/simple-edge-discovery.yaml b/code/API_definitions/simple-edge-discovery.yaml index 066bbcc..72e5c65 100644 --- a/code/API_definitions/simple-edge-discovery.yaml +++ b/code/API_definitions/simple-edge-discovery.yaml @@ -49,8 +49,8 @@ info: The API returns the closest Edge Cloud Zone to a given device, so that device needs to be identifiable by the network. This can be achieved either - by passing a device identifier in the request header, or, from the 3-legged - access token where implemented by the operator. + by passing a device identifier in the request header, or, from the + three-legged access token where implemented by the operator. ## Passing a device identifier in the request header @@ -112,50 +112,32 @@ info: Accept: application/json ``` - ## Identifying a device from the access token + ## Identifying the device from the access token - This specification defines the `device` identifying headers as optional in - API requests, specifically in cases where the API is accessed using a - 3-legged access token and the device can be uniquely 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. + This API requires the API consumer to identify a device as the subject of + the API as follows: - ### Handling of device information: + - When the API is invoked using a two-legged access token, the subject will be + identified from the optional [`device` object | `phoneNumber` field](*), which + therefore MUST be provided. + - When a three-legged access token is used however, this optional identifier + MUST NOT be provided, as the subject will be uniquely identified from the access + token. - #### Optional device identifying headers for 3-legged tokens: + This approach simplifies API usage for API consumers using a three-legged access + token to invoke the API by relying on the information that is associated with the + access token and was identified during the authentication process. - - 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 - a device identifying header 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. + ## Error handling: - #### Validation mechanism: + - If the subject cannot be identified from the access token and the optional `device` + object is not included in the request, then the server will return an error with the + `422 MISSING_IDENTIFIER` error code. - - The server will extract the device identification from the access token, if - available. - - If the API request additionally includes a `device` identifying header - 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` identifying header is not included in the request and the - device information cannot be derived from the 3-legged access token, nor - inferred by the operator if the request is made directly from the client, - 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, a - `device` identifying header 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. + - If the subject can be identified from the access token and the optional `device` + object is also included in the request, then the server will return an error with the + `422 UNNECESSARY_IDENTIFIER` error code. This will be the case even if the same device + is identified by these two methods, as the server is unable to make this comparison. # Responses