For interacting with an OIDC credential issuer, we need to know the OIDC base URL of the issuer service. The SSIKit tries to resolve the OIDC discovery document relative to that base URL like this:
<base URL>/.well-known/openid-configuration
For this example, let's use our demo issuance service published on:
First let's get some information about the credentials, the issuer provides, and possibly, which types of credentials we must present, in order to obtain the issued credentials.
Output
The issuer lists the supported credential types, as well as required VPs, which are None in our demo service.
To initiate a credential issuance session, we have to push an authorization request to the issuer service, containing information about which credential we want to get issued, and a possibly required verifiable presentation:
For more options of the auth subcommand, type
ssikit oidc ci auth --help
Let's break up the above command:
-i [...]: Set the issuer base URL
-n [...]: A nonce we define, for the issuer to sign the id_token in a later step
-r [...]: Set a dummy redirect address, as we just need to copy the final redirection URL from the browser lateron.
-c [...]: Credential type of credential to be issued, like given by issuer metadata supported_credentials
Output
Let's now follow the instructions the CLI printed, and open that link in the browser: https://issuer.walt.id/issuer-api/oidc/fulfillPAR?[...], to proceed to the issuer portal and continue with the credential issuance session.
After completing the issuance session in the issuer web portal, we continue with the token request, as instructed by above command output.
Once we completed the issuance session on the issuer web portal, we get redirected to the dummy address we specified, like we can see in this screenshot:
We copy that URL from the browser and fetch the id_token and access_token from the issuer like so:
For more options of the token subcommand, type
ssikit oidc ci token --help
Breakdown of above command:
-i [...]: Set the issuer base URL
-r [...]: The redirection URL copied from the browser, including the authorization code parameter, generated by the issuer portal.
Output
Let's break down the important bits of the token response:
access_token: The token which we need to request the credentials
id_token: ID token, which should have been signed by the issuer, respecting the nonce challenge we defined previously in the auth subcommand.
c_nonce: The nonce challenge we need to use, to sign the DID ownership proof in the credential request.
expires_in: expiration period (seconds), after which the token will become invalid.
Let's now proceed with the credential request, like instructed by the command output.
Once we retrieved the access_token, we can fetch the actual credential from the issuer. This command can be repeated for each credential schema type we requested in the auth subcommand previously.
For more options of the credential subcommand, type
ssikit oidc ci credential --help
Breakdown of above command:
-i [...]: Set the issuer base URL
-m OIDC: Follow the OIDC standard (default)
-t [...]: The access_token we received previously
-n [...]: The nonce used for signing the DID ownership proof
-d [...]: The DID for which the credential should be issued (we have to proof DID ownership!)
-c [...]: Credential type of credential to be issued, like given by issuer metadata supported_credentials
--save: We instruct the CLI to save the received credential to the credential store
Output
As we can see, we received the VerifiableID credential for the DID subject we specified and the credential was stored.
The SSIKit also supports the OIDC/SIOPv2 credential presentation flow, allowing SDK and CLI users to present verifiable credentials to an OIDC compliant verifier.
The respective OIDC4VP/SIOPv2 specification can be found at:
Refer also to our web wallet documentation, for an example of an actual end-to-end integration of the OIDC verification flow:
This section shows how the SSIKit can be used to interact with OpenID Connect identity providers for the exchange of Verifiable Credentials and Verifiable Presentation.
Below you find sequence diagrams, for the issuance and verification flows.
Examples of using the SSIKit command line interface to interact with OIDC issuers and verifiers, can be found here:
- Credential Issuance
- Presentation Exchange
The SSIKit implements the OIDC credential issuance flow, allowing SDK and/or CLI users to get credentials issued from OIDC compliant issuers.
The respective OIDC4CI specification can be found at:
Refer also to our web wallet documentation, for an example of an actual end-to-end integration of the OIDC issuance flow:
The credential presentation flow is triggered from a Verifier portal, sending an OIDC/SIOP authorization request to the wallet, which acts as a Self-Issued OpenID Provider (SIOP).
To play through the verification flow, let's start at our demo verifier web portal at:
https://verifier.walt.id
To obtain a valid SIOP request URL from the verifier, let's open the verifier portal in a web browser.
Hit the F12 button, to open the developer tools and navigate to the "Network" tab (make sure the request type filter shows All requests), like shown in the following screenshot:
Now hit the "Connect to wallet using VerifiableID" button. The verifier portal redirects to the web wallet, and you find the relevant SIOP request, in the network tab with the request URI starting as /api/wallet/siopv2/initPresentation, like shown in this screenshot:
We want to copy the SIOP request URL, in this example it's:
Alternatively, we can simulate a SIOP request, by using the SSIKit command line interface, to generate such a request URL:
Breakdown of the command:
-v [...]: Dummy verifier address
-p [...]: Dummy verification redirect path, relative to verifier address
-n [...]: Nonce to include in verifiable presentation in the SIOP response
-s [...]: Schema ID of the requested credential
--state [...]: Custom state identifier, that is looped through to the SIOP response
Output
The command prints the SIOP request URI containing the required credential types, as specified in the command parameters.
Continuing the real-case scenario we started on our demo verifier portal, we can copy the SIOP request URL from the browser network tab, like shown in the previous section, and inspect the SIOP request to see which credentials we have to present, using the parse subcommand like this:
Output
The command prints the requested credentials and their schema IDs. Now we can create and send the SIOP response to the verifier portal.
Using the SIOP request URL we got in the previous sections, we can now generate and post the SIOP response, using the DID and credential issued in the issuance credential request example, to the verifier portal like so:
Command breakdown:
-u [...]: The SIOP request URL copied from the browser network tab
-d [...]: The DID to use, for signing the verifiable presentation
-c [...]: The ID of the credential to include in the verifiable presentation
Output
The command prints the SIOP response object and the redirection address, to which we now have to point our web browser, in order to complete the presentation flow.
The verifier portal shows a successful verification, like shown by this screenshot:
