Update error codes and info.description template for device / phone number identifiers

[eric-murray]

What type of PR is this?

• enhancement/feature

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:

• Introduces a new error code 422 UNECESSARY_IDENTIFIER for this case
• Updates and simplifies the suggested info.description documentation to explain this to the API consumer
• Changes error code 422 UNIDENTIFIABLE_DEVICE to 422 MISSING_IDENTIFER to match the new error code, as both are referenced in the template
• Deletes 403 INVALID_TOKEN_CONTEXT as the error code to return when explicit device or phone number provided is not consistent with 3-legged access token

The 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_CONTEXT is 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?

• Yes
• No

Changes in error codes and and new suggested info.description content

Changelog input

 release-note
 - Update error codes and info.description template for device / phone number identifiers

Additional documentation

None

[ToshiWakayama-KDDI]

Hi @eric-murray ,
Thank you very much for include 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" in the line 1990.

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,
Toshi
KDDI

[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?

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.

[ToshiWakayama-KDDI]

Thanks, @eric-murray . Understood.

Another proposal I had from the discussion in the Issue was for Line 1988:

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.

Could you add KYC Match to "(e.g. Number Verification)"?

Thanks,
Toshi
KDDI

[eric-murray]

@ToshiWakayama-KDDI
OK, done

[PedroDiez]

Editorial comments

[PedroDiez]

Suggested change

- 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.

[PedroDiez]

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

[eric-murray]

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.

[PedroDiez]

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

[AxelNennker]

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, ...

[eric-murray]

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:

sub REQUIRED. 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.

[PedroDiez]

Suggested change

	- 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.

[PedroDiez]

LGTM

[jpengar]

LGTM

[PedroDiez]

LGTM

[patrice-conil]

LGTM