login_hint statement for auth code flow

[jpengar]

What type of PR is this?

• documentation

What this PR does / why we need it:

This PR adds WG requested statement about login_hint for auth code flow in CAMARA profile document as closure for issue #191.

Which issue(s) this PR fixes:

Fixes #191

Special notes for reviewers:

CC @Elisabeth-Ericsson @eric-murray @HuubAppelboom @shilpa-padgaonkar

Changelog input

login_hint statement for auth code flow

Additional documentation

https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/56754234/2024-12-18+ICM+Minutes

[AxelNennker]

I think login_hint is an important parameter to support.

For example if the API consumer wants to trigger consent collection for any API and purpose, they would provide login_hint as a hint which API provider user identifier the end-user provided. If the subscriber has multiple contracts, then the end-user can provide the MSISDN this consent collection is about.
The parameter login_hint is also important to make it easy for the API consumer to help the end-user to remember which API provider account id they used the last time. This scenario is one of the intended uses of login_hint because users often do not remember which account they used. I mentioned the scenario above that one subscriber has several contracts but there is also the scenario where one end-user has several contracts but each of the contracts has its own separate account and the user identifier for the account might be different for each account. The user identifier might be an email address.

Consent collection inherently requires a end-user interaction. I cite GDPR but his applies globally, I think.
https://gdprhub.eu/index.php?title=Article_7_GDPR
So, we should make it convenient for the end-user grant their consent and find the account the have at the API provider.

This has nothing to do with interoperability.

How the API provider authenticates the end-user is for the API provider to decide. That implies that the account identifier used for end-user authentication is for the API provider to decide. The API consumer can use login_hint to provide a hint which account identifier should be used.

[eric-murray]

@AxelNennker
Given the Spring '25 meta-release M3 date is 17th January, what do you think the ICM guidelines for that meta-release should be saying about login_hint support for authorisation code flow?

I'm not aware of any standardised registry of login_hint schemes, so mandating support beyond the currently defined tel, ipport and operatortoken would not seem possible at the moment. How would an API consumer learn which other login_hint schemes are supported by an API provider that they may not even know they are dealing with in an aggregated or federated scenario?

[AxelNennker]

From the minutes:

Clarity on login_hint (#191):
The issue revolves around whether login_hint should be mandatory or optional in the authorization code flow. Historically defined as mandatory in CIBA, its use for other flows was less clear.
WG consensus: “Optional” status for login_hint in the authorization code flow, ensuring implementations can ignore it if not applicable. A PR will be created to update the documentation accordingly, emphasizing interoperability.

The "historically" statement in the minutes plain wrong to be begin with.

Historically login_hint was specified in OIDC and OIDC precedes CIBA.
In CIBA some hint is mandatory otherwise the authorization server does not know which authentication device to send a message to.
In OIDC the parameter login_hintis already optional and the WG consensus is in fact OIDC standard. This PR is not needed to implement the WG consensus. Also, OIDC defines that even if the parameter login_hint is provided the interpretation is left to the OP's discretion.

login_hint
OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the phone_number Claim. The use of this parameter is left to the OP's discretion.

This PR does not implement the WG consensus.

We have consensus that the authorization server can choose any user authentication method when consent needs to be collected. The parameter login_hint provides a hint for which user account to use. This PR prevents this.

[AxelNennker]

@AxelNennker Given the Spring '25 meta-release M3 date is 17th January, what do you think the ICM guidelines for that meta-release should be saying about login_hint support for authorisation code flow?

I'm not aware of any standardised registry of login_hint schemes, so mandating support beyond the currently defined tel, ipport and operatortoken would not seem possible at the moment. How would an API consumer learn which other login_hint schemes are supported by an API provider that they may not even know they are dealing with in an aggregated or federated scenario?

ICM guidelines do not need to say anything about the OIDC login_hint parameter itself. It is standardized in OIDC. The parameter login_hint is optional in OIDC and the values are left to the authorization server's discretion.

E.g. when end-user consent is collected using "prompt=consent" then the user needs to be authenticated and login_hint could provide the identifier of the user account. Or if max_age=0 then the end-user needs to login and login_hint could provide the identifier of the user account. Or if the authorization server determines that consent is needed and prompt=none was not provided, then the login_hint could provide the identifier of the user account.

Regarding "registry", there is no need for a registry. What the CAMARA Security and Interoperability Profile specifies is the format of some values.

This CAMARA document clarifies the values used in login_hint in the following way:

tel

For phone numbers. The login_hint must be a tel URI as defined in RFC 3966 for global phone numbers without visual separators in E.164 format. For example, tel:+34666666666.

ipport

For IPv4 and IPv6 addresses, that can optionally include a port. For example, ipport:80.90.34.2:16790, ipport:80.90.34.2, ipport:[2001:db8::1]:8080 or ipport:[2001:db8::1].

The CAMARA Security and Interoperability Profile specifies that IF the value is phone number then the format is as defined.
The CAMARA Security and Interoperability Profile specifies that IF the value is ipport then the format is as defined.
The CAMARA Security and Interoperability Profile does not specify the format of other hints.
The CAMARA Security and Interoperability Profile does not prevent other hints to be used.
For example at Telekom Deutschland the user account identifier is usually an email address. (Help text in German https://www.telekom.de/hilfe/vertrag-rechnung/meine-telekom/kundencenter/login-daten)

[eric-murray]

We have consensus that the authorization server can choose any user authentication method when consent needs to be collected. The parameter login_hint provides a hint for which user account to use. This PR prevents this.

The purpose of the PR is to try and prevent authorisation servers throwing an error when the contents of login_hint are not recognised and the use case allows network authentication. How does the proposed wording prevent an API consumer providing a login_hint that the authorisation server does recognise?

[AxelNennker]

We have consensus that the authorization server can choose any user authentication method when consent needs to be collected. The parameter login_hint provides a hint for which user account to use. This PR prevents this.

The purpose of the PR is to try and prevent authorisation servers throwing an error when the contents of login_hint are not recognised and the use case allows network authentication. How does the proposed wording prevent an API consumer providing a login_hint that the authorisation server does recognise?

The OIDC standard says that the login_hint is optional.
The OIDC standard says that the login_hint is to the discretion of the the authorization server. Why one earth should the AZ throw an error in OIDC authorization code flow?

An example: Let the value of login_hint be "foobar". IF the AZ decides that the end-user must be authenticated then the AZ redirects to a login page with e.g. username and password field. The username field is then pre-filled with the value "foobar". The end-user is usually allowed to change the username input field. That end-user can enter their API provider username und password and be authenticated. There is never an error thrown for any "hint". The "hints" are there for better user experience and not to stop the user flow.

For OIDC authorization code flow the above is even true, if the pattern for phone number for a login_hint with prefix tel: does not match. The ever helpful AZ which receives e.g. login_hint=tel:FooBar can ignore the login_hint completely. The AZ knows what valid identifiers for user accounts are. If the AZ usually does Passkey authentication and the login_hint matches some Cookie value that the AZ uses for that login-method then the AZ could suggest the Passkey with that "label" if Cookies indicate that the user last time used a Passkey. That is mend by OIDC the use of login_hint is at the OpenId Providers discretion. No sane implementation of OIDC authorization code flow would throw an error for a "hint".

OIDC authorization code flow is very different from CIBA, because in CIBA the login_hint determines to which phone number the authentication message is send. Without a valid login_hint CIBA fails.
The is not true for OIDC authorization code flow. The login_hint in standard OIDC is a hint, not more.

Note: the CAMARA Security and Interoperability Profile does not prevent a login_hint with a value of "foobar". That section says: For phone numbers use tel:, for IP addresses use ipport: That section does not say anything for any other user identifiers.

[eric-murray]

Why one earth should the AZ throw an error in OIDC authorization code flow?

Maybe because the authorisation server has no idea who "foobar" is, and hence cannot authenticate "foobar". As you are well aware, not all authorisation servers are being bought "off the shelf".

But if your view is that the authorisation will anyway never throw an error even for unrecognised login hints, what is the problem with the PR, as it is just recommending this exact behaviour? You haven't explained why you think this PR "prevents" an authorisation server from requiring a login_hint, nor acting on a login_hint that it does recognise.

The OIDC standard says that the login_hint is to the discretion of the the authorization server

The point of this PR is to deal with the situation where the API provider that the application has been dealing with requires, for example, login_hint=foobar. The application then finds itself dealing with a different API provider (say, because of a SIM change) that does not require any login_hint, but continues to include login_hint=foobar (because it's designed that way). That scenario should not cause any problems to the new API provider.

But you still haven't explained how this would all work in an aggregated or federated scenario. If API provider 1 requires "foobar" and API provider 2 requires "raboof@example.com", how does the application learn which one of those identifiers it is meant to use when the only authorisation server it knows about is that of the aggregator?

That section does not say anything for any other user identifiers

Indeed, which means it is unlikely that all authorisation servers will have common requirements for these "other user identifiers" in an aggregated or federated scenario. If an application is only dealing directly with a single CSP, then they can agree the requirements between them. But that is not really the point of CAMARA.

CAMARA has not made any statement along the lines that "where login_hint is intended to identify an end user, the login_hint MUST be an e-mail address and, if not recognised by the authorisation server, the end user MUST be prompted to register with the authorisation server using that e-mail address, and the API request CANNOT proceed until that registration is complete". It is currently undefined, and so different API providers can have different requirements for identifying end users.

[AxelNennker]

Maybe because the authorisation server has no idea who "foobar" is, and hence cannot authenticate "foobar". As you are well aware, not all authorisation servers are being bought "off the shelf".

OIDC authorization code flow is a redirect-base flow. As I said, login_hint in only used to fill-in the user's account identifier into the login form when the end-user is authenticated. The CAMARA authorization server does not need to know about the login_hint value, except those CAMARA-defined prefixes.

This PR does not reflect the WGs consensus as written in the minutes.

WG consensus: “Optional” status for login_hint in the authorization code flow, ensuring implementations can ignore it if not applicable. A PR will be created to update the documentation accordingly, emphasizing interoperability.

The WG consensus is what OIDC standardized already, so this PR is not needed and can be closed.
I think the WG consensus might be a misunderstanding of the OIDC standard.
I'll repeat the OIDC standard here again:

login_hint
OPTIONAL. Hint to the Authorization Server about the login identifier the End-User might use to log in (if necessary). This hint can be used by an RP if it first asks the End-User for their e-mail address (or other identifier) and then wants to pass that value as a hint to the discovered authorization service. It is RECOMMENDED that the hint value match the value used for discovery. This value MAY also be a phone number in the format specified for the phone_number Claim. The use of this parameter is left to the OP's discretion.

The PR goes beyond the WG consensus by RECOMMENDING that the logiin_hint SHOULD be ignored.
This hinders to API provider in implementing a smooth user experience if the end-user needs to be authenticated.
Because OIDC authorization is a redirect-based flow there are likely Cookies that also help the end user remember the account identifier they used last time but the the login_hint provides a mechanism that the API consumer can help.

Why should the API provider ignore help?

[eric-murray]

The PR goes beyond the WG consensus by RECOMMENDING that the logiin_hint SHOULD be ignored.

No, it does not, Please read it again. It recommends that the login_hint should be ignored IF IT IS NOT RECOGNISED. That is not at all the same thing as recommending that it should always be ignored.

The bit I don't understand about your view is - how should an API provider treat a login_hint that they do not recognise, and where is this behaviour standardised?

• If your view is that they can do what they like because "use of this parameter is left to the OP's discretion", then their discretion may be to return an error
• If your view is that they can do what they like other than return an error, where is this behaviour standardised? Certainly not by OIDC.

[AxelNennker]

WG consensus: “Optional” status for login_hint in the authorization code flow, ensuring implementations CAN ignore it if not applicable. A PR will be created to update the documentation accordingly, emphasizing interoperability.

The word "can" means that the "SHOULD" from the PR should be a "MAY" instead.

To ensure better interoperability, CAMARA RECOMMENDS that if login_hint parameter is present in the authentication request and the authorization server does not recognise it, it SHOULD ignore it.
The following wouldt better reflect the WG consensus:
To ensure better interoperability, CAMARA RECOMMENDS that if login_hint parameter is present in the authentication request and the authorization server does not recognise it, it MAY ignore it.
Althoug RECOMMENDS and MAY do not go well together in English.
So maybe:
To ensure better interoperability, CAMARA clarifies that, if login_hint parameter is present in the authentication request and the authorization server does not recognise it, it MAY ignore it.

I guess I can live with the last sentence, but I think that "recognise" is not well defined.
Maybe:

To ensure better interoperability, CAMARA clarifies that, if login_hint parameter is present in the authentication request and the authorization server does not support it, it MAY ignore it.
Example: If all account identifiers are valid email addresses, but the login_hint value is not, then the API provider may ignores it.

So, the complete paragraph would be:

The OIDC Authentication Request defines login_hint as an OPTIONAL request parameter. CAMARA does not define a specific handling for this parameter in OIDC Authorization Code Flow. To ensure better interoperability, CAMARA clarifies that, if login_hint parameter is present in the authentication request and the authorization server does not support it, it MAY ignore it.

I can live with that, BUT end-user authentication is never a topic for "interoperability" because one operator can use end-user authentication with username and password, where the username is an email address. Other operators require 2FA.
OIDC provides a protocol the request user authentication but the authentication method is out-of-scope. AND the authentication method is also out-of-scope in CAMARA.

Regarding "returning an error", all "hints" in OIDC authorization code flow are there to improve the user experience. There is never an error if a received hint is not supported.

[shilpa-padgaonkar]

/LGTM

[sebdewet]

LGTM

[jpengar]

@AxelNennker @sebdewet Please re-review.

[sebdewet]

LGTM