Update Diagram with RFC 9101 to secure the /authorize endpoint

[mhfoo]

Problem description
To secure the /authorize endpoint from being abused

Possible evolution
Proposal to follow Telefonica's proposal to use RFC 9101 Signed Request Object

Alternative solution
N.A

Additional context
#71

[mhfoo]

@AxelNennker @bigludo7 @fernandopradocabrillo @ECORMAC @jgarciahospital

Please review the diagram above and provide your comments.

[ECORMAC]

Hi Ming,
Is the aggregated view in issue #128 and if so is it the version issued on Feb 26 that was approved?
We mentioned that perhaps the aggregated view may be good to show here also for completness.
Thanks,
Cormac

[mhfoo]

@ECORMAC

I will share the aggregator version later, after the standalone version is reviewed. Please review the standalone version first and comment.

[mhfoo]

In the YAML

• (1): Authentication must be automatic without any user interactions. Authentication methods such as SMS OTP or user/password are incompatible, as the goal is to validate the mobile phone number that is accessing the App. So it is required to be authentication via mobile network and without the user being involved. the use of parameter prompt=none, as described in OIDC Connect, ensures no user interaction.

In ICM auth code flow, under interaction 8 of the sequence diagram, there is a consent capturing mechanism.

Will the prompt be disabled in this case?

In OIDC 3.1.2.1

prompt input parameter
OPTIONAL. Space-delimited, case-sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are:

none
The Authorization Server MUST NOT display any authentication or consent user interface pages. An error is returned if an End-User is not already authenticated or the Client does not have pre-configured consent for the requested Claims or does not fulfill other conditions for processing the request. The error code will typically be login_required, interaction_required, or another code defined in Section 3.1.2.6. This can be used as a method to check for existing authentication and/or consent.

login
The Authorization Server SHOULD prompt the End-User for reauthentication. If it cannot reauthenticate the End-User, it MUST return an error, typically login_required.

consent
The Authorization Server SHOULD prompt the End-User for consent before returning information to the Client. If it cannot obtain consent, it MUST return an error, typically consent_required.

select_account
The Authorization Server SHOULD prompt the End-User to select a user account. This enables an End-User who has multiple accounts at the Authorization Server to select amongst the multiple accounts that they might have current sessions for. If it cannot obtain an account selection choice made by the End-User, it MUST return an error, typically account_selection_required.

Should the prompt value be consent instead of none?

[mhfoo]

Federated Diagram

[garciasolero]

For security reasons, this authorization flow should ignore the max_age parameter, as the user must actively authenticate on every request. Therefore, I would remove the reference to that parameter in the diagram.

[pendula95]

There is an issue with brokering/Federated diagram. This sequence implies that code exchange from Z to Y is done before client requests code exchange from Z. This should not be the case and is wasting resources and time before the request is even made. Maybe client will never call /token on Z? I suggest that as soon as Y returns user to Z, Z should redirect back to client. When client requests token exchange on Z, Z should only then send token exchange call to Y.

[mhfoo]

There is an issue with brokering/Federated diagram. This sequence implies that code exchange from Z to Y is done before client requests code exchange from Z. This should not be the case and is wasting resources and time before the request is even made. Maybe client will never call /token on Z? I suggest that as soon as Y returns user to Z, Z should redirect back to client. When client requests token exchange on Z, Z should only then send token exchange call to Y.

@pendula95
Federated flows are discusssed in GSMA Open Gateway GitHub repository Chapter 6.

The rational was discussed previously.

[mhfoo]

For security reasons, this authorization flow should ignore the max_age parameter, as the user must actively authenticate on every request. Therefore, I would remove the reference to that parameter in the diagram.

@garciasolero
I believe the auth code flow is also used in direct carrier billing scenarios. There could be use cases where carrier billing could be setup once by a merchant, and any future individual purchases could be charged, using the access token.

[garciasolero]

For security reasons, this authorization flow should ignore the max_age parameter, as the user must actively authenticate on every request. Therefore, I would remove the reference to that parameter in the diagram.

@garciasolero I believe the auth code flow is also used in direct carrier billing scenarios. There could be use cases where carrier billing could be setup once by a merchant, and any future individual purchases could be charged, using the access token.

If you want to create a diagram for a generic authorization code flow, I have nothing to add on that matter. However, for the Number Verification use case, the max_age parameter is irrelevant, as network authentication must occur for each and every authorization.

[mhfoo]

@garciasolero

However, for the Number Verification use case, the max_age parameter is irrelevant, as network authentication must occur for each and every authorization.

Yes, agree. The home operator should ignore the requested max_age value and default its own value for the Number Verification use cases. This should be reflected in the expires_in response parameter of the /token endpoint.

I believe your concern for max_age should be documented in the Number Verification YAML files?

[ECORMAC]

GSMA have just approved a spec "ASAC.01-Seamless Authenticator subsystem enhancement for TS.43 Operator Token" which also deals with the security of the authorize endpoint. Think David W was chair of this group. The plan is that GSMA will submit it to Camara (it will probably go initially to the consent&identity group-not sure??). It may be a good idea to align the above with that initiative (they also have aggregator flows inbuilt).
Regarding the standalone flow perhaps we shall remove the "consent management" box as discussions are ongoing in Identity&Consent regarding consent (legitimate interest etc).
Step 22: identity token returned - also returned in step 21?

[AxelNennker]

While looking at Chapter 6 API General Federated Call Flows I was wondering why many of the detailed flows use CIBA when all flows start at the user's device.

It seems to me the consumption device and the authentication device are the same in many (all?) flows.

Are the puml files of the diagrams public? I did not find them e.g. here https://github.com/GSMA-Open-Gateway/Open-Gateway-Documents/tree/main/SupportingDocuments

Anyone willing to edit and re-create the diagrams so that they show the flow detailed above?

[AxelNennker]

And add the NumberVerification puml files to this repo somewhere, please.
Or include them mermaid-style here?

[AxelNennker]

GSMA have just approved a spec "ASAC.01-Seamless Authenticator subsystem enhancement for TS.43 Operator Token" which also deals with the security of the authorize endpoint. Think David W was chair of this group. The plan is that GSMA will submit it to Camara (it will probably go initially to the consent&identity group-not sure??). It may be a good idea to align the above with that initiative (they also have aggregator flows inbuilt). Regarding the standalone flow perhaps we shall remove the "consent management" box as discussions are ongoing in Identity&Consent regarding consent (legitimate interest etc). Step 22: identity token returned - also returned in step 21?

Notes on the above:

• The ASAC WG approved their own document and it is now looking for approval by higher committees. Those usually just rubber stamp a WG's work.
• After the ASAC document is approved we should add it here or in ICM as a supporting document and create issues here on how to incorporate it into Camara.
• The current TS.43 spec is here https://www.gsma.com/newsroom/wp-content/uploads//TS.43-v11.0-Service-Entitlement-Configuration.pdf
• The AcquireOperatorToken is defined in this document v11.
• ASAC specifies some things to be used with AcquireOperatorToken e.g. scope values.
• ASAC specifies how to obtain the "jwt" which is called EligibilityToken there and access_token in TS.43

[mhfoo]

And add the NumberVerification puml files to this repo somewhere, please. Or include them mermaid-style here?

@AxelNennker

As requested, added in the following commit

[mhfoo]

Are the puml files of the diagrams public? I did not find them e.g. here https://github.com/GSMA-Open-Gateway/Open-Gateway-Documents/tree/main/SupportingDocuments

@AxelNennker the diagrams are codes in the respective *.MD file.
Example, see the raw file of Chapter 6

[bigludo7]

Great proposal @mhfoo and thanks for that.
Few small comments (reviewed with @sebdewet)

Standalone:

• As the phoneNumber is keyed on the phone in flow 3. we must add explicitly phoneNumber (and this send in the 23 flow)
• Not sure to understand the name of the lifeline Network Auth Server - why not Authorization Server ? Probably because this component is making both the Network enrichment to get the number + playing as an AS; Probably something that could be indicated in the accompanying text.

Federated:

• Token could generated in 25 or in 35 right?. No problem to keep is as it but just to be sure to get it.

Very naive question @mhfoo, as I'm not an expert, but from a developer perspective when i will make the call I do not know is I'm facing the scenario standalone or federated... so it's means that I need to make my code working for both situation right? is it acceptable from their perspective?

Again thanks for this great contribution.

[mhfoo]

@bigludo7

Great proposal @mhfoo and thanks for that.

Proposal is from Telefónica team (Thanks to @garciasolero). See ICM Issue #128

Standalone:

• As the phoneNumber is keyed on the phone in flow 3. we must add explicitly phoneNumber (and this send in the 23 flow)

Examples flow / use case:

• Number Verification:Retrieval is used during the customer onboarding to the bank app, consent is given by the owner to the bank app to retrieve the mobile number from CAMARA and stored in the bank's database (OTP against the mobile number is required to mitigate mobile data tethering issue).
• Number Verification:Verify is used in every bank transaction to verify that the transactions are performed on the mobile network with the same onboarded mobile number (which is retrieved from the bank's database).

The diagram is illustrating the 2nd bullet point above.

• Not sure to understand the name of the lifeline Network Auth Server - why not Authorization Server ? Probably because this component is making both the Network enrichment to get the number + playing as an AS; Probably something that could be indicated in the accompanying text.

Yes.

Federated:

• Token could generated in 25 or in 35 right?. No problem to keep is as it but just to be sure to get it.

Yes. 25 is the auth_code, 35 is the access_token.

Very naive question @mhfoo, as I'm not an expert, but from a developer perspective when i will make the call I do not know is I'm facing the scenario standalone or federated... so it's means that I need to make my code working for both situation right? is it acceptable from their perspective?

To the developer, both the standalone and federated are the "same", as they will need to follow the API response for the HTTP 302 redirection URLs. The redirection URLs will contain the next request payload.

Again thanks for this great contribution.

Thank you

[mhfoo]

Added purpose attribute under the Request Object
Updated both diagrams and source

[ECORMAC]

As we stated in the meeting today if we also had a flow showing an aggregator then I think we would be complete (for this discussion). Would that be possible to do?
Thanks again Ming for the great work.

[mhfoo]

As we stated in the meeting today if we also had a flow showing an aggregator then I think we would be complete (for this discussion). Would that be possible to do?

@ECORMAC
The federated diagram is the aggregator flow as well.
Operator Z is acting as an aggregator.
Am I missing something?

[ECORMAC]

As we stated in the meeting today if we also had a flow showing an aggregator then I think we would be complete (for this discussion). Would that be possible to do?

@ECORMAC The federated diagram is the aggregator flow as well. Operator Z is acting as an aggregator. Am I missing something?

@mhfoo I was thinking more a representation as they have today in the ID&Consent (API Access & user Consent-https://github.com/camaraproject/IdentityAndConsentManagement/blob/e3fb2f4619ac031eba3814f5bd0dd35d4931f4b7/documentation/CAMARA-API-access-and-user-consent.md), flow is simpler, plus step 51 in the federated above would probably go from the aggregator etc.

[mhfoo]

As we stated in the meeting today if we also had a flow showing an aggregator then I think we would be complete (for this discussion). Would that be possible to do?

@ECORMAC The federated diagram is the aggregator flow as well. Operator Z is acting as an aggregator. Am I missing something?

@mhfoo I was thinking more a representation as they have today in the ID&Consent (API Access & user Consent-https://github.com/camaraproject/IdentityAndConsentManagement/blob/e3fb2f4619ac031eba3814f5bd0dd35d4931f4b7/documentation/CAMARA-API-access-and-user-consent.md), flow is simpler, plus step 51 in the federated above would probably go from the aggregator etc.

@ECORMAC I understand the confusion now.

Do you have access to Open Gateway Chapter 6?

The federation and aggregator flows are discussed there. Federation == Aggregator in this context.

Normally, the frontend application (mobile or browser) will have a corresponding application backend server, which will interact with the aggregator (which is a backend server).

The diagram in ICM should remove the aggregator label and ICM (and CAMARA) normally discuss the standalone flows.

[mhfoo]

@ECORMAC from Open Gateway Chapter 6

The flow is the same as the federated flow (but with more details). The boxes "Aggregator" and "Telco Finder" is "Operator Z" and "OGW Platform@Operator" is "Operator Y"

[AxelNennker]

And add the NumberVerification puml files to this repo somewhere, please. Or include them mermaid-style here?

@AxelNennker added in the following commit

That reads as if I added the puml in that commit. I did not.

I view those puml files as a good starting point, BUT - I think - in Camara we are providing the north bound APIs and their documentation. I think developers do not and should not care about OpenGateway details like Telco Finder.

Am I wrong?

[mhfoo]

And add the NumberVerification puml files to this repo somewhere, please. Or include them mermaid-style here?

@AxelNennker added in the following commit

That reads as if I added the puml in that commit. I did not.

@AxelNennker

I have corrected the statement in the orignal comment.