Skip to content

Latest commit

 

History

History
182 lines (133 loc) · 6.5 KB

usage-examples.md

File metadata and controls

182 lines (133 loc) · 6.5 KB
Raw

OIDC4CI | Example

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:

https://issuer.walt.id/issuer-api/default/oidc

Issuer info

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.

ssikit oidc ci info -i "https://issuer.walt.id/issuer-api/default/oidc"

Output

[...]
Issuer:
https://issuer.walt.id/issuer-api/default
---
Issuable credentials:
- ProofOfResidence
---
[...]

The issuer lists the supported credential types, as well as required VPs, which are None in our demo service.

Initiate credential issuance session

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:

ssikit oidc ci auth -i "https://issuer.walt.id/issuer-api/default/oidc" -n "FOO" \
-r "https://blank" \
-c ProofOfResidence

{% hint style="info" %} For more options of the auth subcommand, type

ssikit oidc ci auth --help {% endhint %}

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

[...]
Point your browser to this address and authorize with the issuer:
https://issuer.walt.id/issuer-api/oidc/fulfillPAR?client_id=https://blank&request_uri=urn:ietf:params:oauth:request_uri:a58b8919-4922-4140-a46b-e89f7b36d87c

Then paste redirection url from browser to this command to retrieve the access token:
ssikit oidc ci token -i https://issuer.walt.id/issuer-api/oidc/ -r <url from browser>

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.

Token request

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:

Issuer redirect screenshot

We copy that URL from the browser and fetch the id_token and access_token from the issuer like so:

ssikit oidc ci token -i https://issuer.walt.id/issuer-api/default/oidc/ \
-r "https://blank/?code=a58b8919-4922-4140-a46b-e89f7b36d87c&state=XqLV33eiLjSJSJf58KC9m2U9PYfT6jmmMcnRfJaz_ow"

{% hint style="info" %} For more options of the token subcommand, type

ssikit oidc ci token --help {% endhint %}

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

[...]
Access token response:
{
   "access_token":"a58b8919-4922-4140-a46b-e89f7b36d87c",
   "refresh_token":"4OKWdsX2hOMveLwEGSpjhQnZwc5sNC-Bit6VbticyKI",
   "c_nonce":"5685e1d3-7da7-453c-9776-555217564f21",
   "id_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhNThiODkxOS00OTIyLTQxNDAtYTQ2Yi1lODlmN2IzNmQ4N2MifQ.AreLW-7O_P7tWB3_mkb69Fhdv8G9kVrcxWEA0wtDpp0",
   "token_type":"Bearer",
   "expires_in":300
}

Now get the credential using:
ssikit oidc ci credential -i https://issuer.walt.id/issuer-api/oidc/ -m OIDC -t a58b8919-4922-4140-a46b-e89f7b36d87c -n 5685e1d3-7da7-453c-9776-555217564f21 -d <subject did> -s <credential schema id>

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.

Credential request

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.

ssikit oidc ci credential -i https://issuer.walt.id/issuer-api/default/oidc/ \
-m OIDC \
-t a58b8919-4922-4140-a46b-e89f7b36d87c -n 5685e1d3-7da7-453c-9776-555217564f21 \
-d did:key:z6Mktxjvto1vueoMXiiAtLQiCrDPd2Xoi47isAnjK12nETRX \
-c ProofOfResidence \
--save

{% hint style="info" %} For more options of the credential subcommand, type

ssikit oidc ci credential --help {% endhint %}

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

[...]
VerifiableId(
    context=[
        https://www.w3.org/2018/credentials/v1
    ],
    id=urn:uuid:ad5a242e-4343-4c40-b58e-33ab60251b18,
    issuer=did:key:z6MkhHz9tcWcWmRXpKyoduLV6fYXhzFeRfmRmseoRggZeB6g,
    issued=2022-03-11T11:32:53.433306061Z,
[...]
    credentialSubject=VerifiableIdSubject(
        id=did:key:z6Mktxjvto1vueoMXiiAtLQiCrDPd2Xoi47isAnjK12nETRX,
[...]
    ),
[...]
    proof=Proof(
        type=Ed25519Signature2018,
        creator=did:key:z6MkhHz9tcWcWmRXpKyoduLV6fYXhzFeRfmRmseoRggZeB6g,
[...]
    )
)

Stored as urn:uuid:aa1a51cd-3ad2-49fe-ae3e-5ae50c4aed3b

As we can see, we received the VerifiableID credential for the DID subject we specified and the credential was stored.