Authorization Error Response: technical implementation details

[Zicchio]

The purpose of this issue is to expand on the topic of issue #368, which contains a brief description of a missing feature without including a full suggestion on how to implement it.

To contextualize the changes required by a full resolution of issue #368, we include a summary of the current authentication flows follows as described in the diagram described in the italian specs, which can be summarized as:

1. a pre authentication / login begin step, where either a QR code is displayer (cross device flow) or the wallet app is inoked via deep link in the user smartphone; the http handler associated to this behaviour is this
   

   eudi-wallet-it-python/pyeudiw/satosa/default/openid4vp_backend.py

   Line 219 in 0bb0d98

   def pre_request_endpoint(

   
   1.1. in case of cross device flow, a javascript is polling on the /status endpoint; the primary purpose of this polling is to notify when step 3. is finished.

   eudi-wallet-it-python/pyeudiw/satosa/default/openid4vp_backend.py

   Line 356 in 0bb0d98

   def status_endpoint(self, context: Context) -> JsonResponse:

2. a "jar" request step: the wallet calls via HTTP request the url in the QR code (or in the deep link) to obtain the authentication request jwt that includes, in the claims, the oauth request performed by the RP toward the Wallet; the http handler associated to this behaviour is this
   

   eudi-wallet-it-python/pyeudiw/satosa/default/openid4vp_backend.py

   Line 219 in 0bb0d98

   def pre_request_endpoint(

3. an authorizatin response step: the wallet sends the to the wallet the user digital credential via an HTTP; the handler associated to that endpoint is this

   eudi-wallet-it-python/pyeudiw/satosa/default/response_handler.py

   Line 94 in 0bb0d98

   def response_endpoint(

   
   the response to this endpoint is either
   3.1 [Cross Device Flow] 200 Ok response; then the /status endpoint will finally get an ok response containing a redirect URL in its body (that is invoked by the user agent) to go on with step 4.
   3.2 [Same Device Flow] 200 Ok with a redirect url to be invoked at step 4.
4. The user agent invoked the redirect_url (sometimes called response_uri in the italian specs), which in case of a positive outcome will pass the user digital credential to the satosa core to go on; the HTTP handler associated to that endpoint is this one

   eudi-wallet-it-python/pyeudiw/satosa/default/openid4vp_backend.py

   Line 313 in 0bb0d98

   def get_response_endpoint(self, context: Context) -> Response:

The parsing and validation of Authorization Error Response include implementation changes to step 3. and step 4.
In particular:
i. in step 3. the authorization error response must be validated and accepted (this is done by PR #376). According to the italian specs, successful validation of the authorization error response does not change this endpoint response: it is still a 200 OK + redirect url for the same device, or a 200 OK in the cross device flow, with the expectation that the /status endpoint will finally receive a 200 OK + redirect_url response.
ii. step 4 currently assumes that if we reach the redirect url, then the authentication is successful and we can go (in which case we go on passing relevant information to the satosa frontend module). In case of authentication error response this assumption is no longer true: this endpoint is intended to be reached even is no digital credential is obtained. In the "happy" case, the digital credential are fetched in this line of code

eudi-wallet-it-python/pyeudiw/satosa/default/openid4vp_backend.py

Line 352 in 0bb0d98

resp = internal_response.from_dict(finalized_session["internal_response"])

In the authorization error response we don't have digital credential, and instead of going on with the flow at the satosa frontend, we should stop the authentication flow and respond directly signaling that the authentication process failed. In particular, the italian specs suggests as possible responses 401 or 403 based on the table in this section¹
Note that PR #376 correctly stores the authorization error response in the session storage (in mongo). This is necessary as the authorization error response might contain information that is required for the elaboration of a meaningful response in step 4.

¹ IMO there is some ambiguity here in the italian specs and that probably deserves an issue in the docs. The ambiguity is that (1) the suggested user experience might be IMO bad, and (2) the section is basically exclusive for the cross device flow, leaving the same flow partially undefined at step 4.

[StefanoContento-tndigit]

I don't think that at the moment in the italian specs it is defined where the redirect_uri should take the user in case of Authorization Error Response (e.g. the user does not give consent to share the PID information to the RP).

The value of the redirect_uri could be determined based on the authorization error response saved in mongo.
By looking at the following flow from the ARF 1.7 I think that the option after receiving an Authorization Response are:

1. Give positive feedback and authenticate the user (ok flow)
2. Return to relying party service (in case of any Authorization Error Response )

@peppelinux shall we open an issue for this in the it-docs?

[Zicchio]

Expanding this issue for documentation purposes.

The openid4vp spec is very vague on the topic of authorization error responses and does not provide any indication on the user flow side. It simply states that if the wallets Authorization Error Respose with error+error_description+state direct_post is syntactially correct and valid, then the RP should reply to the wallet with 200 OK and OPTIONALLY a redirect uri.
The user flow in this case is, therefore, an implementation detail and is based on the necessities of the RP.
In particular, it does not state what the redirect uri should point to.
To me, this implies that:

1. if the redirect uri is used, then is should point to an error page.
2. if the redirect uri is NOT used, then the RP shopuld manage the error internally by inspecting the state associated to the request in the current browser session.

On top of that, satosa (like other proxy solution) adds the additional complexity that there is a front-end protocol like saml or oidc that is likely witing for... something, or at least for the flow to finish.
As such, one might argue that in the context of satosa a Wallet-send Authorization Error Response should (eventually) trigger an authorization error response (if frontend is oidc, or something equivalent if the frontend is saml).
From this POV, the redirect uri could be used as "endpoint" that triggers and error aat the frontend protocol level.
I think this other implementation approach might be more complex but is surely worth investigating if the benefit are there.

[peppelinux]

@Zicchio presentation flow got slightly updated in the current editor's copy, to be deployed as version 1.0.0 during the next week