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]

Suggested change

	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:
	When an API requires a device or phone number to be identified in order to get access to the data, that device or phone number can be identified in one of two ways:

[PedroDiez]

To align the wording with the template

[PedroDiez]

Suggested change

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 device or phone number, returning an error only when they 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 their functionality.

[PedroDiez]

Suggested change

	## 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 API subject identification can be from either an access token or explicit identifier
	In the context of this Appendix "API subject" or "subject" refers to a device or a phone number.

[PedroDiez]

Considering this comment, contextualizing "API subject" and suggesting some rewording along PR in some specific points.

[eric-murray]

The API subject is the "User" or "Resource Owner" defined in our glossary. The may be identified from knowledge of the device or phone number, but they remain a person and are not those identifiers.

And they may be identified from other identifiers in future, such as operator tokens or network access identifiers. That doesn't change the concept of "API subject" at all.

My original thought was just to define everything in terms of "User", but I have seen that term used to mean end user, which is not correct. But I might go back to that as there is an agreed definition of User.

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

Suggested change

	- 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 identifier MUST NOT be provided, as the subject will be uniquely identified from the token.

[jlurien]

@eric-murray, @PedroDiez,

Are we going to align as well the rest of codes to the new values as discussed in #321? Then we would need to update also the entries for:

• UNSUPPORTED_DEVICE_IDENTIFIERS -> UNSUPPORTED_IDENTIFIER
• DEVICE_NOT_FOUND -> IDENTIFIER_NOT_FOUND
• DEVICE_NOT_APPLICABLE -> SERVICE_NOT_APPLICABLE
• DEVICE_IDENTIFIERS_MISMATCH -> IDENTIFIER_MISMATCH

[PedroDiez]

@eric-murray, @PedroDiez,

Are we going to align as well the rest of codes to the new values as discussed in #321? Then we would need to update also the entries for:

• UNSUPPORTED_DEVICE_IDENTIFIERS -> UNSUPPORTED_IDENTIFIER
• DEVICE_NOT_FOUND -> IDENTIFIER_NOT_FOUND
• DEVICE_NOT_APPLICABLE -> SERVICE_NOT_APPLICABLE
• DEVICE_IDENTIFIERS_MISMATCH -> IDENTIFIER_MISMATCH

I have covered in PR #329 (to be merged after this PR)

[eric-murray]

I updated the text of the Annex using "User" (as defined in the ICM glossary) rather than "API subject". Whether device or phoneNumber is used does not change that we are trying to identify a user, albeit that device allows this indirectly via an active physical device. I'd like to get that message across.

Anyway, please review updated text and let me know your views

I accepted the updates for the definitions of the MISSING_IDENTIFIER and UNNECESSARY_IDENTIFIER error codes, so hopefully this PR is now compatible with #329.