Update error codes and info.description template for device / phone number identifiers#324
Conversation
|
Hi @eric-murray , However, it seems the template does not have this, so, would it be possible to add the phrase "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" to line 2021 or near there? Thanks, |
The template is anyway only recommended, not mandatory, and the point of the text before was to indicate to sub-projects that the template does not apply to APIs that support "Number Verification" functionality. So you are free to add your own documentation to the YAML. I don't think including the proposed template in a given API and then saying that it doesn't apply to that API is particularly helpful to the API consumer. |
|
Thanks, @eric-murray . Understood. Another proposal I had from the discussion in the Issue was for Line 1988:
Could you add KYC Match to "(e.g. Number Verification)"? Thanks, |
|
@ToshiWakayama-KDDI |
|
|
||
| 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 IP address (and optional port) of a physical device, or the phone number associated with the user's account. |
There was a problem hiding this comment.
| - 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 3-legged access token, then it MUST be inferred from the access token information, which in turn may be identified 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. |
There was a problem hiding this comment.
Prefer to be generic in this way. Indicating the API Subject -> "it is the sub claim of associated the ID token", is just an internal implementation option.
How to a Telco Operator implements API Subject Identification within the access token is outside the scope of Commonalities and different security policies may be present among Telco operators so at the end that is internal up to each Telco Operator
There was a problem hiding this comment.
I think "identifier" is too generic - APIs use many identifiers, but only one is the subject of the API. I appreciate that the value of the sub claim of the ID token is implementation, but the existence of the ID token with a sub claim is not - that is specified as a requirement by CAMARA (albeit adopted from OIDC).
The message I want to get across is "If an ID token has been provided to the API consumer, then the "API subject" (the user or end user identified by the sub claim) is already known, so providing additional explicit API subject identifiers in the service API call is an error".
I'll have a think on some updated text that is clearer and update my proposal later. Remember that the text outside of the template itself is primarily intended to guide API implementors, not API consumers, for whom the template text is intended. So I think it reasonable that specific technical terms are used here.
There was a problem hiding this comment.
I did not think about the text outside the template was the primarely intention to guide API implementators (any case it would read as an option, not the unique option). Any case I have to read deeply the rewording proposed
There was a problem hiding this comment.
No need to refer to sub, I think.
As I said below, a valid 3-legged access token always contains or is associated with the information the API needs.
That information might be one or more of IMSI, MSISDN, phone number, IMEI, ...
There was a problem hiding this comment.
I agree that understanding of the sub is not essential to understanding the requirements and their rationale. But I have seen examples of confusion around the access token, which arise from RFC 6749 not standardising the access token format in any way.
But OIDC core DOES standardise the ID token, particularly the sub claim:
subREQUIRED. Subject Identifier. A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client
So, if an ID token has been returned to the API consumer, there should be no confusion that the API subject has already been identified, and an attempt to identify them again later (by explicit parameter) will fail.
| 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 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. |
There was a problem hiding this comment.
| - 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 the access token is a 2-legged access token, 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. |
Co-authored-by: Rafal Artych <121048129+rartych@users.noreply.github.com>
What type of PR is this?
What this PR does / why we need it:
Issue #259 identified that API consumers could obtain "Number Verification" functionality from any API by providing both a 3-legged access token and explicit device or phone number. To avoid this for APIs whose scope does not allow this, it was agreed that this should always be an error for such APIs, irrespective of whether the identifiers match or not.
This API:
422 UNECESSARY_IDENTIFIERfor this case422 UNIDENTIFIABLE_DEVICEto422 MISSING_IDENTIFERto match the new error code, as both are referenced in the template403 INVALID_TOKEN_CONTEXTas the error code to return when explicit device or phone number provided is not consistent with 3-legged access tokenThe error naming convention follows that proposed in this comment, but does not update the other errors that are discussed in that comment. This PR can be updated with whatever names are finally agreed.
Which issue(s) this PR fixes:
Fixes #259
Special notes for reviewers:
See also #321
403 INVALID_TOKEN_CONTEXTis used by some APIs for other reasons than that listed in this section of the guidelines, so cannot be removed completely.Does this PR introduce a breaking change?
Changes in error codes and and new suggested info.description content
Changelog input
Additional documentation
None