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

eric-murray commented 1 month ago

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:

Does this PR introduce a breaking change?

[x] 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 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

@ToshiWakayama-KDDI OK, done

jlurien commented 1 week ago

@eric-murray, @PedroDiez,

Are we going to align as well the rest of codes to the new values as discussed in https://github.com/camaraproject/Commonalities/issues/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 commented 1 week ago

@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 commented 1 week ago

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.

camaraproject / Commonalities