The eudi-lib-jvm-siop-openid4vp-kt
is a Kotlin library, targeting JVM, that supports
the SIOPv2 (draft 12)
and OpenId4VP (draft 20) protocols.
In particular, the library focus on the wallet's role using those two protocols with constraints
included in ISO 23220-4 and ISO-18013-7
Wallet receives an OAUTH2 Authorization request, formed by the Verifier, that may represent
- a SIOPv2 authentication request, or
- a OpenID4VP authorization request or,
- a combined SIOP & OpenID4VP request
In the same device scenario, the aforementioned authorization request reaches the wallet in terms of a deep link. Similarly, in the cross-device scenario, the request would be obtained via scanning a QR Code.
Regardless of the scenario, wallet must take the URI (of the deep link or the QR Code) that represents the
authorization request and ask the SDK to validate the URI (that is to make sure that it represents one of the supported
requests mentioned aforementioned) and in addition gather from Verifier additional information that may be included by
reference (such as presentation_definition_uri
, client_metadata_uri
etc.)
The interface that captures the aforementioned functionality is AuthorizationRequestResolver
import eu.europa.ec.eudi.openid4vp.*
val authorizationRequestUri : String // obtained via a deep link or scanning a QR code
val resolution = siopOpenId4Vp.resolveRequestUri(authorizationRequestUri)
val requestObject = when (resolution) {
is Resolution.Invalid -> throw resolution.error.asException()
is Resolution.Success -> resolution.requestObject
}
After receiving a valid authorization, the wallet has to process it. Depending on the type of request, this means
- For a SIOPv2 authentication request, wallet must get holder's consensus and provide an
id_token
- For an OpenID4VP authorization request,
- wallet should check whether holder has claims that can fulfill verifier's requirements
- let the holder choose which claims will be presented to the verifier and form a
vp_token
- For a combined SIOP & OpenID4VP request, wallet should perform both actions described above.
This functionality is a wallet concern, and it is not supported directly by the library
After collecting holder's consensus, wallet can use the library to form an appropriate response and then dispatch it
to the verifier.
Depending on the response_mode
that the verifier included in his authorization request, this is done via
- either a direct post (when
response_mode
isdirect_post
ordirect_post.jwt
), or - by forming an appropriate
redirect_uri
(when response mode isfragment
,fragment.jwt
,query
orquery.jwt
)
The library tackles this dispatching via Dispatcher
Please note that in case of response_mode
direct_post
or direct_post.jwt
the library actually performs the
actual HTTP call against the verifier's receiving end-point.
On the other hand, in case of a response_mode
which is neither direct_post
nor direct_post.jwt
the library
just forms an appropriate redirect URI.
It is the caller's responsibility to redirect the user to this URI.
val requestObject // calculated in previous step
val idToken : Jwt // provided by wallet
val consensus = Consensus.PositiveConsensus.IdTokenConsensus(idToken)
val dispatchOutcome = siopOpenId4Vp.dispatch(requestObject, consensus)
Project contains an example which
demonstrates the functionality of the library and in particular the interaction of a
Verifier
and a Wallet
via Verifier's trusted end-point to perform an SIOP Authentication.
To run the example, you will need to clone Verifier's trusted end-point and run it using
./gradlew bootRun
and then run the Example.
A Wallet can take the form of a web or mobile application.
OpenId4VP describes flows for both cases. Given that we are focusing on a mobile wallet we could
assume that AuthorizationRequest
contains always a response_mode
Library currently supports response_mode
direct_post
direct_post.jwt
fragment
fragment.jwt
query
query.jwt
Library requires the presence of client_id_scheme
with one of the following values:
pre-registered
assuming out of bound knowledge of verifier meta-data. A verifier may send an authorization request signed (JAR) or plainx509-san-dns
where verifier must send the authorization request signed (JAR) using by a suitable X509 certificatex509-san-uri
where verifier must send the authorization request signed (JAR) using by a suitable X509 certificateredirect_uri
where verifier must send the authorization request in plain (JAR cannot be used)did
where verifier must send the authorization request signed (JAR) using a key resolvable via DID URL.verifier_attestation
where verifier must send the authorization request signed (JAR), witch contains a verifier attestation JWT from a trusted issuer
OAUTH2 foresees that AuthorizationRequest
is encoded as an HTTP GET
request which contains specific HTTP parameters.
OpenID4VP on the other hand, foresees in addition, support to
RFC 9101 where
the aforementioned HTTP Get contains a JWT encoded AuthorizationRequest
Finally, ISO-23220-4 requires the usage of RFC 9101
Library supports obtaining the request object both by value (using request
attribute) or
by reference (using request_uri
)
The Verifier articulated requirements of the Credential(s) that are requested using
presentation_definition
and presentation_definition_uri
parameters that contain a
Presentation Definition JSON object.
According to OpenId4VP, verifier may pass the presentation_definition
either
Library supports all these options
According to OpenId4VP verifier may pass his metadata (client metadata) either
- by value, or
- by reference
Library supports both options
Library currently supports response_type
equal to id_token
, vp_token
or vp_token id_token