From 3079e4f73f010d77e95f1629be155ccc947f5c58 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 18:39:09 +0100 Subject: [PATCH 01/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 23 +++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..7ab4a9cc 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -793,7 +793,7 @@ The Following table compiles the guidelines to be adopted: | 1 | None of the provided device identifiers is supported by the implementation | 422 | UNSUPPORTED_DEVICE_IDENTIFIERS | phoneNumber is required. | | 2 | Some identifier cannot be matched to a device | 404 | DEVICE_NOT_FOUND | Device identifier not found. | | 3 | Device identifiers mismatch | 422 | DEVICE_IDENTIFIERS_MISMATCH | Provided device identifiers are not consistent. | -| 4 | Invalid access token context | 403 | INVALID_TOKEN_CONTEXT | Device identifiers are not consistent with access token. | +| 4 | An explicit device identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_DEVICE_IDENTIFIER | The API subject is already identified by the access token. | | 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. | | 6 | The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token | 422 | UNIDENTIFIABLE_DEVICE | The device cannot be identified. | @@ -1976,11 +1976,26 @@ response: 204 No Content ``` -## Appendix A: `info.description` template for `device` identification from access token +## Appendix A (Informative): `info.description` template for API subject identification from the access token or explicit identifier -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](/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**. +When an API requires a User or Resource Owner (the "subject" of the API) to be identified in order to get access to the subject's data, that subject can be identified in one of two ways: +- If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the phone number or IP address (and optional port) of a physical device. +- If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. -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 get the code. And for CIBA, `login_hint` is currently limited to a single phone number or IP address (which can optionally include a port). +This pattern can result in a number of errors for API Providers that allow both 2- and 3-legged access tokens to be used for a given API: +- Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer. + + Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. + + In this case, a `422 UNNECESSARY_DEVICE_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token" + +- Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer. + + One or other MUST be provided. + + In this case, `422 UNIDENTIFIABLE_DEVICE` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. + +The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation in CAMARA API specifications which both require an API subject to be identified and accept both 2- and 3-legged access tokens in order to explain to the API consumer how the pattern works. ```md # Identifying a device from the access token From e13381c8a140f653f9b0413a8512587f54a7b063 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 18:48:58 +0100 Subject: [PATCH 02/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 7ab4a9cc..76d8b752 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1976,7 +1976,7 @@ response: 204 No Content ``` -## Appendix A (Informative): `info.description` template for API subject identification from the access token or explicit identifier +## Appendix A (Informative): `info.description` template for when API subject identification can be from either an access token or explicit identifier When an API requires a User or Resource Owner (the "subject" of the API) to be identified in order to get access to the subject's data, that subject can be identified in one of two ways: - If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the phone number or IP address (and optional port) of a physical device. From 0424073d279ced8b3b4a545239c2943bf786c2a2 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 22:58:38 +0100 Subject: [PATCH 03/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 41 ++++++++++---------------- 1 file changed, 15 insertions(+), 26 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 76d8b752..8e9ecfb3 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1982,7 +1982,7 @@ When an API requires a User or Resource Owner (the "subject" of the API) to be i - If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the phone number or IP address (and optional port) of a physical device. - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. -This pattern can result in a number of errors for API Providers that allow both 2- and 3-legged access tokens to be used for a given API: +This pattern requires that API Providers that allow both 2- and 3-legged access tokens to be used for a given API to detect the following errors: - Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer. Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. @@ -1995,36 +1995,25 @@ This pattern can result in a number of errors for API Providers that allow both In this case, `422 UNIDENTIFIABLE_DEVICE` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. -The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation in CAMARA API specifications which both require an API subject to be identified and accept both 2- and 3-legged access tokens in order to explain to the API consumer how the pattern works. +The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation to explain to the API consumer how the pattern works. This template is applicable to CAMARA APIs which: +- require an API subject to be identified; and +- may have implementations which accept 2-legged access tokens; and +- whose scope does not allow the API to confirm whether or not the optional API subject identifier when provided matches that of the 3-legged access token -```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 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. - -## 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. +The template should be customised for each API using it by deleting one of the options where marked by (*) -### Validation mechanism: +```md +# Identifying the API subject from the access token -- 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. +The API subject is the user or resource owner whose data is being requested or processed by this API. +- When the API is invoked using a 2-legged access token, the API subject will be identified from the optional [`device` object | `phoneNumber` field](*). +- When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the API subject will be uniquely identified from the token. -### Error handling for unidentifiable devices: +This approach simplifies API usage for API consumers using a 3-legged access token to invoke the API by relying on the API subject information that is associated with the access token and was identified during the API consumer authentication process. -- 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. +## Error handling: -### Restrictions for tokens without an associated authenticated identifier: +- If the API subject cannot be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is not included in the request, then the server will return an error with the `422 UNIDENTIFIABLE_DEVICE` error code. -- 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. +- If the API subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_DEVICE_IDENTIFIER` error code. This will the case even if the same user or resource owner is identified by these two methods. ``` - -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. From c668153807ce11dccef06c230233d7a74d27ac92 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:01:13 +0100 Subject: [PATCH 04/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 8e9ecfb3..f9a3e6c5 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1979,7 +1979,7 @@ response: ## Appendix A (Informative): `info.description` template for when API subject identification can be from either an access token or explicit identifier When an API requires a User or Resource Owner (the "subject" of the API) to be identified in order to get access to the subject's data, that subject can be identified in one of two ways: -- If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the phone number or IP address (and optional port) of a physical device. +- If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the IP address (and optional port) of a physical device, or the phone number associated with the user's account. - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. This pattern requires that API Providers that allow both 2- and 3-legged access tokens to be used for a given API to detect the following errors: From f675b18fe4fdf6d8fb3bcf066bce5cbacee067b5 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:08:53 +0100 Subject: [PATCH 05/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index f9a3e6c5..40fe35ca 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1982,13 +1982,14 @@ When an API requires a User or Resource Owner (the "subject" of the API) to be i - If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the IP address (and optional port) of a physical device, or the phone number associated with the user's account. - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. -This pattern requires that API Providers that allow both 2- and 3-legged access tokens to be used for a given API to detect the following errors: +If an API provider issues 3-legged access tokens, the following error may occur : - Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer. Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. - In this case, a `422 UNNECESSARY_DEVICE_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token" + In this case, a `422 UNNECESSARY_DEVICE_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. +If an API provider issues 2-legged access tokens, the following error may occur : - Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer. One or other MUST be provided. From 88cbc9dab569375378f28b24fd69349be2f2b2fd Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:10:43 +0100 Subject: [PATCH 06/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 40fe35ca..6de9963c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1994,9 +1994,11 @@ If an API provider issues 2-legged access tokens, the following error may occur One or other MUST be provided. - In this case, `422 UNIDENTIFIABLE_DEVICE` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. + In this case, a `422 UNIDENTIFIABLE_DEVICE` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. -The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation to explain to the API consumer how the pattern works. This template is applicable to CAMARA APIs which: +The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation to explain to the API consumer how the pattern works. + +This template is applicable to CAMARA APIs which: - require an API subject to be identified; and - may have implementations which accept 2-legged access tokens; and - whose scope does not allow the API to confirm whether or not the optional API subject identifier when provided matches that of the 3-legged access token From 98d7330aa7121e716ee748e61a604e8d3970fbbd Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:14:40 +0100 Subject: [PATCH 07/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 6de9963c..88a97565 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -2005,7 +2005,7 @@ This template is applicable to CAMARA APIs which: The template should be customised for each API using it by deleting one of the options where marked by (*) -```md +>```md # Identifying the API subject from the access token The API subject is the user or resource owner whose data is being requested or processed by this API. From 0a92aa7661dae1cc9f95f3598cd4d17f96c5783b Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:19:20 +0100 Subject: [PATCH 08/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 88a97565..6de9963c 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -2005,7 +2005,7 @@ This template is applicable to CAMARA APIs which: The template should be customised for each API using it by deleting one of the options where marked by (*) ->```md +```md # Identifying the API subject from the access token The API subject is the user or resource owner whose data is being requested or processed by this API. From f56d8255cb1c3bfe530b2c3e716a2c28f5bed165 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Mon, 21 Oct 2024 23:21:12 +0100 Subject: [PATCH 09/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 6de9963c..8b8f8e71 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -2009,7 +2009,7 @@ The template should be customised for each API using it by deleting one of the o # Identifying the API subject from the access token The API subject is the user or resource owner whose data is being requested or processed by this API. -- When the API is invoked using a 2-legged access token, the API subject will be identified from the optional [`device` object | `phoneNumber` field](*). +- When the API is invoked using a 2-legged access token, the API subject will be identified from the optional [`device` object | `phoneNumber` field](*), which therefore MUST be provided. - When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the API subject will be uniquely identified from the token. This approach simplifies API usage for API consumers using a 3-legged access token to invoke the API by relying on the API subject information that is associated with the access token and was identified during the API consumer authentication process. From 5a571379a5fde28df9fa46e81e74addfef0ac800 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 22 Oct 2024 17:28:34 +0100 Subject: [PATCH 10/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 33 +++++++++++++------------- 1 file changed, 16 insertions(+), 17 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 8b8f8e71..99464925 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -793,9 +793,9 @@ The Following table compiles the guidelines to be adopted: | 1 | None of the provided device identifiers is supported by the implementation | 422 | UNSUPPORTED_DEVICE_IDENTIFIERS | phoneNumber is required. | | 2 | Some identifier cannot be matched to a device | 404 | DEVICE_NOT_FOUND | Device identifier not found. | | 3 | Device identifiers mismatch | 422 | DEVICE_IDENTIFIERS_MISMATCH | Provided device identifiers are not consistent. | -| 4 | An explicit device identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_DEVICE_IDENTIFIER | The API subject is already identified by the access token. | +| 4 | An explicit identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. | | 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. | -| 6 | The device identifier is not included in the request and the device information cannot be derived from the 3-legged access token | 422 | UNIDENTIFIABLE_DEVICE | The device cannot be identified. | +| 6 | An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. | @@ -1976,25 +1976,25 @@ response: 204 No Content ``` -## Appendix A (Informative): `info.description` template for when API subject identification can be from either an access token or explicit identifier +## Appendix A (Normative): `info.description` template for when API subject identification can be from either an access token or explicit identifier When an API requires a User or Resource Owner (the "subject" of the API) to be identified in order to get access to the subject's data, that subject can be identified in one of two ways: - If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the IP address (and optional port) of a physical device, or the phone number associated with the user's account. - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. -If an API provider issues 3-legged access tokens, the following error may occur : +If an API provider issues 3-legged access tokens for use with the API, the following error may occur : - Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer. Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. - In this case, a `422 UNNECESSARY_DEVICE_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. + In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. -If an API provider issues 2-legged access tokens, the following error may occur : +If an API provider issues 2-legged access tokens for use with the API, the following error may occur : - Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer. - One or other MUST be provided. + One or other MUST be provided to identify the API subject. - In this case, a `422 UNIDENTIFIABLE_DEVICE` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. + In this case, a `422 MISSING_IDENTIFIER` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation to explain to the API consumer how the pattern works. @@ -2003,20 +2003,19 @@ This template is applicable to CAMARA APIs which: - may have implementations which accept 2-legged access tokens; and - whose scope does not allow the API to confirm whether or not the optional API subject identifier when provided matches that of the 3-legged access token -The template should be customised for each API using it by deleting one of the options where marked by (*) - +The template SHOULD be customised for each API using it by deleting one of the options where marked by (*) ```md -# Identifying the API subject from the access token +# Identifying the [ device | phone number ](*) from the access token -The API subject is the user or resource owner whose data is being requested or processed by this API. -- When the API is invoked using a 2-legged access token, the API subject will be identified from the optional [`device` object | `phoneNumber` field](*), which therefore MUST be provided. -- When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the API subject will be uniquely identified from the token. +This API requires the API consumer to identify a [ device | phone number ](*) as the subject of the API as follows: +- When the API is invoked using a 2-legged access token, the subject will be identified from the optional [`device` object | `phoneNumber` field](*), which therefore MUST be provided. +- When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the subject will be uniquely identified from the token. -This approach simplifies API usage for API consumers using a 3-legged access token to invoke the API by relying on the API subject information that is associated with the access token and was identified during the API consumer authentication process. +This approach simplifies API usage for API consumers using a 3-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the API consumer authentication process. ## Error handling: -- If the API subject cannot be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is not included in the request, then the server will return an error with the `422 UNIDENTIFIABLE_DEVICE` error code. +- If the subject cannot be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is not included in the request, then the server will return an error with the `422 MISSING_IDENTIFIER` error code. -- If the API subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_DEVICE_IDENTIFIER` error code. This will the case even if the same user or resource owner is identified by these two methods. +- If the subject can be identified from the access token and the optional [`device` object | `phoneNumber` field](*) is also included in the request, then the server will return an error with the `422 UNNECESSARY_IDENTIFIER` error code. This will the case even if the same [ device | phone number ](*) is identified by these two methods, as the server is unable to make this comparison. ``` From 8569208a48291df1b2940735a01392ce0218b6f4 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 22 Oct 2024 17:31:23 +0100 Subject: [PATCH 11/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 99464925..59005272 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1983,14 +1983,14 @@ When an API requires a User or Resource Owner (the "subject" of the API) to be i - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. If an API provider issues 3-legged access tokens for use with the API, the following error may occur : -- Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer. +- **Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer.** Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. If an API provider issues 2-legged access tokens for use with the API, the following error may occur : -- Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer. +- **Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer.** One or other MUST be provided to identify the API subject. From e0d043b02a4e29c22b36d6411ff32732582e3ba0 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Tue, 5 Nov 2024 09:19:37 +0000 Subject: [PATCH 12/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 59005272..a581fb72 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1985,7 +1985,7 @@ When an API requires a User or Resource Owner (the "subject" of the API) to be i If an API provider issues 3-legged access tokens for use with the API, the following error may occur : - **Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer.** - Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification), for others it may exceed the scope consented to by the User or Resource Owner. + Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User or Resource Owner. In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. From ef1757a6c131b8e2bab167b9af9020ca529dd271 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 13 Nov 2024 12:56:47 +0000 Subject: [PATCH 13/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index a581fb72..bdfe247e 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1982,7 +1982,7 @@ When an API requires a User or Resource Owner (the "subject" of the API) to be i - If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the IP address (and optional port) of a physical device, or the phone number associated with the user's account. - If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. -If an API provider issues 3-legged access tokens for use with the API, the following error may occur : +If an API provider issues 3-legged access tokens for use with the API, the following error may occur: - **Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer.** Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User or Resource Owner. From 078b969b9c2c519d52d5a21328632c27d66cb2fa Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Wed, 13 Nov 2024 12:56:57 +0000 Subject: [PATCH 14/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index bdfe247e..8b83bc89 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1989,7 +1989,7 @@ If an API provider issues 3-legged access tokens for use with the API, the follo In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. -If an API provider issues 2-legged access tokens for use with the API, the following error may occur : +If an API provider issues 2-legged access tokens for use with the API, the following error may occur: - **Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer.** One or other MUST be provided to identify the API subject. From ac145024fe1912473ab5b54ece0c93de9f31622a Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 15 Nov 2024 18:06:42 +0000 Subject: [PATCH 15/17] Update API-design-guidelines.md --- documentation/API-design-guidelines.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 8b83bc89..651a8ebf 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1976,32 +1976,32 @@ response: 204 No Content ``` -## Appendix A (Normative): `info.description` template for when API subject identification can be from either an access token or explicit identifier +## Appendix A (Normative): `info.description` template for when User identification can be from either an access token or explicit identifier -When an API requires a User or Resource Owner (the "subject" of the API) to be identified in order to get access to the subject's data, that subject can be identified in one of two ways: -- If the access token is a 3-legged access token, then it is the `sub` claim of associated the ID token, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` of the OIDC CIBA flow, where `login_hint` can be either the IP address (and optional port) of a physical device, or the phone number associated with the user's account. -- If the access token is a 2-legged access token, an explicit API subject identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. +When an API requires a User (as defined by the [ICM Glossary](https://github.com/camaraproject/IdentityAndConsentManagement/blob/main/documentation/CAMARA-API-access-and-user-consent.md#glossary-of-terms-and-concepts)) to be identified in order to get access to that User's data (as Resource Owner), the User can be identified in one of two ways: +- If the access token is a 3-legged access token, then the User will already have been associated with that token by the API provider, which in turn may be identfied from the physical device that calls the `/authorize` endpoint for the OIDC authorisation code flow, or from the `login_hint` parameter of the OIDC CIBA flow (which can be a device IP, phone number or operator token). The `sub` claim of the ID token returned with the access token will confirm that an association with the User has been made, although this will not identify the User directly. +- If the access token is a 2-legged access token, no User is associated with the token, an hence an explicit identifier MUST be provided. This is typically either a `Device` object named `device`, or a `PhoneNumber` string named `phoneNumber`. Both of these schema are defined in the [CAMARA_common.yaml](/artifacts/CAMARA_common.yaml) artifact. In both cases, it is the User that is being identified, although the `device` identifier allows this indirectly by identifying an active physical device. If an API provider issues 3-legged access tokens for use with the API, the following error may occur: -- **Both a 3-legged access token and an explicit API subject identifier are provided by the API consumer.** +- **Both a 3-legged access token and an explicit User identifier (device or phone number) are provided by the API consumer.** - Whilst it might be considered harmless to proceed if both identify the same API subject, returning an error only when the two subjects do not match would allow the API consumer to confirm the identity associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User or Resource Owner. + Whilst it might be considered harmless to proceed if both identify the same User, returning an error only when the two do not match would allow the API consumer to confirm the identity of the User associated with the access token, which they might otherwise not know. Although this functionality is supported by some APIs (e.g. Number Verification, KYC Match), for others it may exceed the scope consented to by the User. In this case, a `422 UNNECESSARY_IDENTIFIER` error code MUST be returned unless the scope of the API allows it to explicitly confirm whether or not the supplied identity matches that bound to the 3-legged token. If an API provider issues 2-legged access tokens for use with the API, the following error may occur: -- **Neither a 3-legged access token nor an explicit API subject identifier are provided by the API consumer.** +- **Neither a 3-legged access token nor an explicit User identifier (device or phone number) are provided by the API consumer.** - One or other MUST be provided to identify the API subject. + One or other MUST be provided to identify the User. - In this case, a `422 MISSING_IDENTIFIER` error code MUST be returned, indicating that the API provider cannot identify the API subject from the provided information. + In this case, a `422 MISSING_IDENTIFIER` error code MUST be returned, indicating that the API provider cannot identify the User from the provided information. The documentation template below is RECOMMENDED to be used as part of the `info.description` API documentation to explain to the API consumer how the pattern works. This template is applicable to CAMARA APIs which: -- require an API subject to be identified; and +- require the User (i.e. resource owner) to be identified; and - may have implementations which accept 2-legged access tokens; and -- whose scope does not allow the API to confirm whether or not the optional API subject identifier when provided matches that of the 3-legged access token +- do NOT allow the API to confirm whether or not the optional User identifier (`device` or `phoneNumber`) matches that associated with the 3-legged access token The template SHOULD be customised for each API using it by deleting one of the options where marked by (*) ```md @@ -2009,9 +2009,9 @@ The template SHOULD be customised for each API using it by deleting one of the o This API requires the API consumer to identify a [ device | phone number ](*) as the subject of the API as follows: - When the API is invoked using a 2-legged access token, the subject will be identified from the optional [`device` object | `phoneNumber` field](*), which therefore MUST be provided. -- When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the subject will be uniquely identified from the token. +- When a 3-legged access token is used however, this optional identifer MUST NOT be provided, as the subject will be uniquely identified from the access token. -This approach simplifies API usage for API consumers using a 3-legged access token to invoke the API by relying on the information that is associated with the access token and was identified during the API consumer authentication process. +This approach simplifies API usage for API consumers using a 3-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. ## Error handling: From d784f434962d6e86a229afdc9a25a0c4769153b0 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 15 Nov 2024 18:07:26 +0000 Subject: [PATCH 16/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 651a8ebf..01e06ff1 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -795,7 +795,7 @@ The Following table compiles the guidelines to be adopted: | 3 | Device identifiers mismatch | 422 | DEVICE_IDENTIFIERS_MISMATCH | Provided device identifiers are not consistent. | | 4 | An explicit identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. | | 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. | -| 6 | An identifier is not included in the request and the API subject cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. | +| 6 | An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. | From 95d6e1a7966ee383bf5e3f04db753c09236eddb7 Mon Sep 17 00:00:00 2001 From: Eric Murray Date: Fri, 15 Nov 2024 18:07:39 +0000 Subject: [PATCH 17/17] Update documentation/API-design-guidelines.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Pedro Díez García --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 01e06ff1..0cd0feb6 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -793,7 +793,7 @@ The Following table compiles the guidelines to be adopted: | 1 | None of the provided device identifiers is supported by the implementation | 422 | UNSUPPORTED_DEVICE_IDENTIFIERS | phoneNumber is required. | | 2 | Some identifier cannot be matched to a device | 404 | DEVICE_NOT_FOUND | Device identifier not found. | | 3 | Device identifiers mismatch | 422 | DEVICE_IDENTIFIERS_MISMATCH | Provided device identifiers are not consistent. | -| 4 | An explicit identifier is provided when an API subject has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. | +| 4 | An explicit identifier is provided when a device or phone number has already been identified from the access token | 422 | UNNECESSARY_IDENTIFIER | The device is already identified by the access token. | | 5 | Service not applicable to the device | 422 | DEVICE_NOT_APPLICABLE | The service is not available for the provided device. | | 6 | An identifier is not included in the request and the device or phone number identification cannot be derived from the 3-legged access token | 422 | MISSING_IDENTIFIER | The device cannot be identified. |