The IDP Kit is built on top of the Wallet Kit, providing the SSI credential verification and SIOP protocol logic and the SSI Kit, providing basic functionality with regards to credential and key management, as well as the NFT Kit for verification of NFTs and interaction with blockchain APIs.

It provides APIs for OIDC-clients to connect and initiate user authentication, as well as the SIOP APIs and NFT verification APIs for communication with the SSI and NFT wallets.

The following picture shows the overall architecture of the IDP Kit:

The IDP Kit makes it easy for you to build and launch your own OIDC compliant identity provider utilizing SSI, NFTs or Sign-In with Ethereum to obtain identity data.

Depending on your requirements the IDP Kit can be configured to map data from verifiable credentials or NFTs to standard OIDC claims (e.g. OIDC profile scope), or to deliver the presented credentials, NFTs or account addresses as they are via the custom vp_token and nft_token siwe claims.

The following overview summarizes the basic features of the IDP Kit:

• OIDC

  • Standard OIDC protocol support, when interfacing with end user applications

  • Support for OIDC scopes like profile, address, email, and standard claims

    • Support for custom vp_token and nft_token claims, to allow client applications to request credential or nft token data from the user

  • Support for various OIDC flows, including code flow, implicit flow and hybrid flows

  • Support for OIDC auto discovery via well-known endpoint for OpenID provider metadata

• SSI

  • Credential presentation exchange with SSI wallets via the OIDC/SIOPv2 protocol

  • Verification of credential and presentation signatures, challenges and compliance with the presentation request

    • Pluggability of additional verification policies

    • Support for custom verification policies

• NFTs

  • NFT metadata exchange with NFT wallets such as MetaMask

  • Verification of NFT collections and traits

• Sign-In with Ethereum

  • Get account addresses from wallets such as MetaMask

  • Verify ownership of the address

• Claims and claim mapping

  • Support for mapping credential and NFT data to standard OIDC claims and scopes

  • Custom vp_token claim to propagate the verified presentation including all required credentials to the end user application as user info

  • Custom nft_token claim to propagate verified NFT metadata, such as collection membership and token traits, to the end user application as user info

  • Custom siwe claim to propagate verified addresses to the end user application as user info

• Client authentication

  • Configuration of client IDs, client secrets and redirect uri, to enforce client authentication (via client_secret_basic mode)

  • Dynamic client registration

• Signature types

  • Support for RS256, EdDSA and ES256K key and signature types, for signing tokens

  • Publishing of public keys on standard OIDC JWK set endpoint, to enable clients to verify token signatures

This documentation will help you understand how the IDP Kit works and how you can use it.

The IDP Kit is built on top of our SSI and NFT software stacks, including the SSI Kit, the Wallet Kit and the NFT Kit, so

• if you are already familiar with SSI, NFTs, SSI Kit, Wallet Kit and NFT Kit, you can jump right to the introduction of the IDP Kit.

• if you are new to SSI, NFTs or our software stacks, you may want to start with the documentation of the individual concepts and stack components:

  • SSI - Self Sovereign Identity

  • NFTs - Non-Fungible Tokens

  • SSI Kit

  • Wallet Kit

  • NFT Kit

This section elaborates the theory behind the IDP Kit:

• IDP Kit Basics - Learn what the IDP Kit is and what it does.

• Architecture - Explore the architecture and components.

• Feature List - Explore all features in an overview list

Here are the most important things to know about the IDP Kit:

• It is open source (Apache 2). You can use the code for free and without limitations.

• It is an out-of-the-box solution that you can simply re-use or even white-label such as for building pilot projects quickly.

• It is customisable in a sense that you can individualise it based on your requirements.

• It is composable in a sense that you can plug your existing (d)apps into the IDP Kit in order to supercharge your (d)apps with SSI capabilities.

• It abstracts complexity such as low-level functionality related to key handling, data storage, signing and interactions with third party systems and SSI wallets.

• It is built on open standards to ensure interoperability and prevent lock-in effects.

• It is flexible in a sense that you can deploy and run an IDP on-premise, in your (multi) cloud environment or directly integrate our libraries.

• It enables you to use different identity ecosystems like Europe’s emerging identity ecosystem (EBSI, ESSIF) in anticipation of a multi-ecosystem future. (Consult the to find out which ecosystems the IDP Kit supports.)

The IDP Kit enables you to launch an OIDC compliant identity provider that utilizes the OIDC-SIOPv2 protocol and/or NFT blockchain APIs to retrieve identity data or NFT metadata via a suitable wallet, providing the data as user info and/or mapping it to standard OIDC claims.

This enables applications, that already support OIDC-based authentication, to connect to SSI, NFT wallets or leverage Sign-in with Ethereum (EIP-4361), where users act as self-issued identity providers, with minimum effort, which in the simplest case could involve nothing more than a configuration change.

Simple authentication flow with IDP Kit

The following picture shows a simple OIDC authentication flow between the end user application and the IDP Kit:

Identity federation via an external identity and access manager

The IDP Kit can be configured as a federated identity provider, with other Identity and Access Management systems, such as KeyCloak, as shown in the picture below:

There are different ways to get started with the IDP Kit:

• CLI tool: The IDP Kit comes with a command-line interface to e.g conveniently configure the IDP key among other configuration options.

• REST APIs: Discover the endpoints available to build your solution.

• Dependency (JVM): The IDP Kit can be used directly as JVM-dependency for Maven or Gradle.

If you just want to try out the IDP Kit, you may directly use our public deployments, which don't require any configuration or build environment.

Demos

• Try Login with NFTs - Mint a NFT and log into our demo walt.id membership page.

Tutorials

• Login with NFTs | Next.js

• Login with NFTs | Keycloak

• Login with SSI | Next.js

Installation & Running the Project

Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine

Binding address and port

API services

• OIDC API is available under the context path /api/oidc/

• SIOP API is available under the context path /api/siop/

Swagger API documentation

A swagger documentation of all exposed APIs is available under /api/swagger

Publicly deployed API documentation

The IDP Kit provides a simple command line interface, to run and/or configure the service.

In the following sections I will show examples using the command line interface of the IDP Kit.

For the sake of readability, I will shortcut the executable command as:

waltid-idpkit

Installation & Running the Project

Make sure you have Docker or a JDK 16 build environment including Gradle installed on your machine

Configuration

For configuring keys and managing verification policies, the IDP Kit integrates some commands from the SSI Kit for key and policy management.

The config command lets you define the context in which you want to execute the command, by specifying the arguments --oidc, --siop, before the respective subcommand.

E.g.

This command lists the keys available in the context of the OIDC manager.

This command lists the verification policies available in the context of the SIOP manager.

The IDP Kit can also be used as direct dependency for JVM-based applications. In this case, an existing application can be easily extended to act as an identity provider.

The following illustrates how the IDP Kit can be used via Gradle:

Repositories

maven("https://maven.walt.id/repository/waltid/")

maven("https://maven.walt.id/repository/waltid-ssi-kit/")

Dependency

implementation("id.walt:waltid-idpkit:<version>")

The code-base as well as more detailed instructions can be found at GitHub https://github.com/walt-id/waltid-idpkit

We operate the IDP Kit as a public service, in a stable and rolling deployment, for demo and trial purposes only.

Stable deployment

The stable deployment is updated manually whenever a stable release build is ready:

https://idp.walt.id

Rolling deployment

A deployment of the bleeding edge developments is updated in a rolling fashion on every successful build of the main branch of the IDP Kit project.

This deployment should not be considered stable and should not be used for demo purposes, unless you want to try out a bleeding edge feature, that is not yet available in the stable deployment.

The rolling deployment is available for demo and trial at:

https://idp.walt-test.cloud

Run IDP Kit docker container

If you want to quickly try out the latest build of the IDP Kit and connect your web application to it, you can simply run the docker container and configure your application's OIDC client library to connect to it.

To understand the necessary configuration before running the service, consult the section IDP Kit setup and configuration.

Edit the configuration files in waltid-idpkit/config according to your needs and run the container like so:

cd waltid-idpkit
docker run -p 8080:8080 -e WALTID_DATA_ROOT=/data -v $PWD:/data waltid/idpkit run

Now you may open your browser on the exposed swagger documentation to browse and try out the REST APIs:

http://localhost:8080/api/swagger

... or configure your application to read the IDP settings from the well-known OpenID configuration endpoint:

http://localhost:8080/api/oidc/.well-known/openid-configuration

🤟 Welcome

In this tutorial, we create our own instance of the IDP Kit locally and configure it to check users which want to authenticate for being an owner of a chosen NFT collection. We will register a client, connect our frontend and enable login with NFTs. The frontend builds on Next.js and will use NextAuth.js as authentication library.

NFT collections can be hosted on the following ecosystems:

• Ethereum

• Polygon

• Tezos

• Near

• Polkadot

• Flow

• Algorand

The IDP Kit uses the OIDC authentication flow, the same technology used by Sign-in with Apple, Facebook, Twitter and many more. If you want to learn more about it and how it works behind the scenes, you can have a look at our concept section as well as how the ideas are translated when using NFTs.

🗂 Modules

1. IDP Kit Setup - Build and run the project in your local environment

2. Client Registration - Retrieve clientId and clientSecret from the IDP Kit, used in the frontend

3. NFT Collection Configuration - Set NFT collection required by the users to login successfully

4. Next.js - Setup and connect frontend to IDP Kit and enable sign in with NFTs

📽️ Video Version

You can also watch the full tutorial here.

Docker

To quickly start up the IDPKit using Docker, refer to:

Docker Container

Or continue on the next section, for building and running the IDP Kit on your local development environment.

Local build

To build and run the IDP Kit on your local development environment, make sure to set up your machine with these requirements:

• JDK 16+

• NodeJS 18 with Yarn

Project structure

The IDP Kit is structured into a backend (main) and frontend project.

IDP Kit backend

The project is written in Kotlin and compiled for JVM 16+. The build project is set up using Gradle.

IDP Kit frontend

The web UI, which provides the wallet connect and cross-device credential exchange web interfaces, is written in Nuxt.js and set up as a NodeJs/Yarn project.

Backend build

To build the IDP Kit backend, use the gradle wrapper script, which automatically sets up a local installation of gradle and runs the build:

./gradlew build

Alternatively use the build and run functionality of your IDE. We use IntellJ IDEA to build, run and test the project.

Frontend build

To build the frontend, navigate into its subfolder:

cd web/waltid-idpkit-ui

Install the required dependencies, using yarn:

yarn install

Run the dev server, if you're developing:

yarn dev

Or, generate the production build output:

yarn generate

Development build configuration

To run the IDP Kit in a development environment, you need to start both the backend and the frontend services.

Check the following configuration and possibly adapt it to your needs:

Nuxt config

File: web/waltid-idpkit-ui/nuxt.config.js:

Look for the proxy section near the end of the configuration file.

Make sure the host and port mapping of the API paths, corresponds to the host and port, on which the IDP Kit backend is running.

Typically this section will look like this:

   proxy: {
        '/verifier-api/': "http://localhost:8080/",
        '/api/': "http://localhost:8080/",
        '/webjars/': "http://localhost:8080/"
    }

Configure the port on which the frontend should be started, by using the server section like this:

    server: {
        port: 5000
    }

IDP config

File: config/idp-config.json:

Let the externalUrl point to an address on which the IDP Kit frontend service is running and reachable from a browser.

E.g.:

{
  "externalUrl": "http://localhost:5000",
}

Verifier config

File: config/verifier-config.json:

Set the verifierApiUrl to a URL on which the IDP Kit backend is listening, and that is reachable from a browser.

Set the url of the walt.id wallet configuration to the web wallet, which should be used. By default, this is pointing to the wallet deployed on walt-test.cloud.

e.g.:

{
  "verifierUiUrl": "",
  "verifierApiUrl": "http://localhost:8080/api/siop/default",

  "wallets": {
    "walt.id": {
      "id": "walt.id",
      "url": "https://wallet.walt-test.cloud",
      "presentPath": "api/siop/initiatePresentation/",
      "receivePath" : "api/siop/initiateIssuance/",
      "description": "localhost wallet"
    }
  }
}

Intro

Before you start with the project setup, make sure you have the following dependencies on your local machine:

1. JDK 16 build environment

2. Gradle

Getting Started

For running the project, you have two options: Docker or Gradle.

git clone https://github.com/walt-id/waltid-idpkit.git

cd waltid-idpkit

./gradlew build install

alias idpkit="build/install/waltid-idpkit/bin/waltid-idpkit"

git clone https://github.com/walt-id/waltid-idpkit.git

cd waltid-idpkit

docker build --rm -t waltid/idpkit .

alias idpkit="docker run -p 8080:8080 -e WALTID_DATA_ROOT=/data -v $PWD:/data waltid/idpkit"

Running the IDP-Kit Frontend The frontend with which the user will interact to authenticate by doing a connect wallet.

cd web/waltid-idpkit-ui/

yarn install 

or 

npm install

yarn dev

or 

npm run dev

Run NFT-Kit JS (if ecosystem of your NFTs is not Ethereum or Polygon)

You also need to run the NFT Kit JS, if your NFT collection is not hosted on the Ethereum or Polygon network. Per default, the project will be run under "http://localhost:3000". We will need that in the NFT collection configuration.

git clone https://github.com/walt-id/waltid-nftkit.git

cd waltid-nftkit/js

npm install

 npm i --save-dev @types/bn.js

npm start

🤟 Welcome

In this tutorial, we create our own instance of the IDP Kit locally and configure it to check users which want to authenticate for being an owner of a chosen NFT collection. We will register a client and connect it to Keycloak.

NFT collections can be hosted on the following ecosystems:

• Ethereum

• Polygon

• Tezos

• Near

• Polkadot

• Flow

The IDP Kit uses the OIDC authentication flow, the same technology used by Sign-in with Apple, Facebook, Twitter and many more. If you want to learn more about it and how it works behind the scenes, you can have a look at our as well as how the ideas are translated when using .

🗂 Modules

1. - Build and run the project in your local environment

2. - Retrieve clientId and clientSecret from the IDP Kit, used by Keycloak

3. - Set NFT collection required by the users to login successfully

4. - Register IDP-Kit as external Identity Provider with Keycloak

5. - Use Keycloak in a Next.js application (optional)

📽️ Video Version

Clients and why we need one

To use the IDP Kits functionality, we need to register our frontend application as client and collect client_id and client_secret. Those credentials will be used by the frontend to make requests to the IDP Kit, which will in turn ask the user if they want to sign in and check if they are allowed to do so, based on the NFTs they hold in their wallet. After collecting the consent of the user and validating that they are allowed to log in, the IDP Kit will give the frontend a secret with which it can request information about the authenticated user the user.

Client registration

Now that we know what we need and why we need it, let's go ahead and create our first client. Depending on the situation and personal preference, there are two options available: CLI tool, API.

Intro

We need to provide the chain and the NFT collection, which the IDP Kit must check, when users are trying to log in. The values can be set in the config/idp-config.json under default_nft_token_claim

Choose the ecosystem of where your NFT collection is hosted

Now that we have finished the configuration, we need to rebuild the project for the changes to take effect, run the API and connect our client to it.

Intro

Before you start with the project setup, make sure you have the following dependencies on your local machine:

Getting Started

For running the project, you have two options: Docker or Gradle.

Running the IDP-Kit Frontend The frontend with which the user will interact to authenticate by doing a connect wallet.

Run NFT-Kit JS (if ecosystem of your NFTs is not Ethereum or Polygon)

Clients and why we need one

To use the IDP Kits functionality, we need a client and collect client_id and client_secret. Those credentials will be used by Keycloak to make requests to the IDP Kit, which will in turn ask the user if they want to sign in and check if they are allowed to do so, based on the NFTs they hold in their wallet. After collecting the consent of the user and validating that they are allowed to log in, the IDP Kit will give Keycloak a secret with which it can request information about the authenticated the user.

The exchange of information between the client, which is in our case Keycloak and the authorization server which is the IDP Kit are based on the OpenID Connect standards. I won't go into more detail here, but you can learn more about it in the concept section or watch this great illustrative video from OktaDev, which gives a great overview about OpenID Connect. To understand how the base ideas are then translated to the NFT use case, you can dive into Identity provision via NFTs

Client registration

Now that we know what we need and why we need it, let's go ahead and create our first client. Depending on the situation and personal preference, there are two options available: CLI tool, API.

idpkit config --oidc clients register -n "myFrontend" -r "http://localhost:8001/realms/NFT/broker/nft/endpoint"

idpkit config --oidc clients register -n "myFrontend" -r "https://applicationName.com" -u "client_id"

idpkit run

idpkit config --oidc clients token

curl -X POST http://localhost:8080/api/oidc/clients/register \
-H "Authorization: Bearer master_token" \
-H "Content-Type: application/json" \
-d '{"client_name": "MyApp","redirect_uris": ["http://localhost:3000/api/auth/callback/walt-id-nft"],"all_redirect_uris": false}'

curl -X PUT http://localhost:8080/api/oidc/clients/96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM \
-H "Authorization: Bearer eyJraWQiOiI2YzA2M2Y3NjBjNGM0M2VlYjNkMDNmNmQzODQ1NGU1OSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI5NmJhSWNuNVlVRDd6Mkg2OW5Qa2QxS3JpemFpeEJzM0lXY1JTX3FEQ21NIn0.RgNdqkK_o2paGvJhM95jtrEqUPTiIQVB4kZFY8QIAKypAFC2Iq6WTll_nyAM_osbSluEQGlQvwpFf4xnF4aM2JxAkeTE1SCHA3EWODIn2uDzKDFkpNOdw9xJHiIstqy2WK1x8jsi1RK_iaa6gf_3Pm0xazEekkjvRGtXn9jfoyYiUVN75EJDU_pbSju9vXNIO2nd2FIBzmyd3DWohat0Lgb1m7fv8eFWXjC-PYICrv-qLP7-cVuhNnrkmCXSIwhXcXbdjyqAB6cgFVqecUaiTCi928uIxTRsAS7_vnPCiWxnPTGCTGsE05hspbnTuubxs0oYGFOZ7adURvCkgxFsHw" \
-H "Content-Type: application/json" \
-d '{"client_secret_expires_at": 0, "all_redirect_uris": false, "registration_client_uri": "http://localhost:8080/api/oidc/clients/96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM", "redirect_uris": ["http://localhost:3000"], "client_id_issued_at": 1662617990, "client_secret": "hMAi7khf6cgZ2wRXlN89FQ1zB99654j8cyF4O3AAmk0", "client_name": "MyApp", "registration_access_token": "eyJraWQiOiI2YzA2M2Y3NjBjNGM0M2VlYjNkMDNmNmQzODQ1NGU1OSIsInR5cCI6IkpXVCIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI5NmJhSWNuNVlVRDd6Mkg2OW5Qa2QxS3JpemFpeEJzM0lXY1JTX3FEQ21NIn0.RgNdqkK_o2paGvJhM95jtrEqUPTiIQVB4kZFY8QIAKypAFC2Iq6WTll_nyAM_osbSluEQGlQvwpFf4xnF4aM2JxAkeTE1SCHA3EWODIn2uDzKDFkpNOdw9xJHiIstqy2WK1x8jsi1RK_iaa6gf_3Pm0xazEekkjvRGtXn9jfoyYiUVN75EJDU_pbSju9vXNIO2nd2FIBzmyd3DWohat0Lgb1m7fv8eFWXjC-PYICrv-qLP7-cVuhNnrkmCXSIwhXcXbdjyqAB6cgFVqecUaiTCi928uIxTRsAS7_vnPCiWxnPTGCTGsE05hspbnTuubxs0oYGFOZ7adURvCkgxFsHw", "client_id": "96baIcn5YUD7z2H69nPkd1KrizaixBs3IWcRS_qDCmM"}' \

Intro

We have prepared a Next.js example project which we can use as a starting point. It uses NextAuth.js for handling authentication and a custom provider build by walt.id to connect the IDP Kit easily with NextAuths functionality. We won't go into details of how Next.js or NextAuth.js works.

The user of the frontend application needs MetaMask or another compatible wallet to share their blockchain address, with which the IDP Kit will be able to check if the user is holder of the required NFT collection.

Create the frontend app

We will need Node.js and yarn or npm

1. Clone the project

git clone https://github.com/walt-id/waltid-nft-auth-nextjs.git

2. Install the dependencies by running yarn install or npm install

3. Update CLIENT_ID and CLIENT_SECRET based on the response returned by the client registration step in the .env.example file.

4. Rename .env.example to .env

5. In pages/api/auth/[...nextauth].ts we update the identityProviderURL parameter of the NFTProvider. We can leave the third parameter in the NFTProvider as is, if you have not changed the port on which the IDP Kit is running locally. When you switch the port or use a hosted version of the IDP Kit, you need to update the parameter to reflect the new endpoint of the IDP Kit.

6. Now the project is set up and can be run

yarn dev

//  or 

npm run dev

7. When we visit http://localhost:3000 and press the login button, the authentication is started.

We need to provide the chain and the NFT collection, which the IDP Kit must check, when users are trying to log in. The values can be set in the config/idp-config.json under default_nft_token_claim

Choose the ecosystem of where your NFT collection is hosted

"default_nft_token_claim": {
      "EVM": {
            "chain": "MUMBAI",
            "factorySmartContractAddress": "",
            "smartContractAddress": "0x3496756a84E186DC8C0d7ef91BcD393200ef5Ebc",
            "collectionPath": ""
          }
 }

"default_nft_token_claim": {
      "TEZOS": {
            "chain": "GHOSTNET",
            "factorySmartContractAddress": "",
            "smartContractAddress": "KT1Rc59ukgW32e54aUdYqVzTM9gtHrA4JDYp",
            "collectionPath": ""

          }
 }

"externalUrl": "http://localhost:8080", 
"jsProjectExternalUrl":"http://localhost:3000"

"default_nft_token_claim": {
      "NEAR": {
            "chain": "TESTNET",
            "factorySmartContractAddress": "",
            "smartContractAddress": "demo.khaled_lightency1.testnet",
            "collectionPath": ""
          }
 }

"externalUrl": "http://localhost:8080", 
"jsProjectExternalUrl":"http://localhost:3000"

"default_nft_token_claim": {
      "POLKADOT": {
            "chain": "OPAL",
            "factorySmartContractAddress": "",
            "smartContractAddress": "1062",
            "collectionPath": ""
          }
 }

"externalUrl": "http://localhost:5000", 
"jsProjectExternalUrl":"http://localhost:4000"

"default_nft_token_claim": {
     "FLOW": {
            "chain": "TESTNET",
            "factorySmartContractAddress": "",
            "smartContractAddress": "0xa9ccb9756a0ee7eb",
            "collectionPath": "/public/exampleNFTCollection"
          }
 }

"externalUrl": "http://localhost:8080", 
"jsProjectExternalUrl":"http://localhost:3000"

Now that we have finished the configuration, we need to rebuild the project for the changes to take effect, run the API and connect our client to it.

./gradlew build install

idpkit run

docker build --rm -t waltid/idpkit .

idpkit run

Since the IDP Kit is compliant with the well adopted OpenID Connect standard for identity provision, it can be easily integrated, as a federated identity provider on Keycloak.

Assuming that you already have a local instance of Keycloak running, we will continue with the configuration of our federated identity provider. In case you need to setup Keycloak first, please have a look at their documentation on how to get started.

Configuration

To start with the configuration, we log in to the KeyCloak administration console with our admin credentials and navigate to the realm, for which we want to apply the configuration.

New external Identity Provider

1. In the admin console, we select under configurations the Identity providers and select the OpenID Connect v1.0 option

2. We fill out Alias and Display Name

3. Add the Discovery endpoint, which will be in the form of:

{host}/api/oidc/.well-known/openid-configuration

We need to make sure IDP Kit is running, as Keycloak will import all the information it needs from that endpoint.

4. Provide Client ID and Client Secret which we got during the client registration step

Advanced Settings

After successfully creating the new identity provider, in the Advanced settings section when expanding the Advanced dropdown, we need to update Scopes and Prompt

1. Scopes = openid nft_token

2. Prompt = None

By updating the scopes to use nft_token, we make sure the IDP-Kit will use NFTs as a method of authentication, when the user logs in.

Check Redirect URI

Now that we've finished the setup of our Identity provider in Keycloak, we must make sure that the client we registered with the IDP-Kit has the correct redirect URL. The redirect URL should match the value found in at Redirect URI in our just created Identity Provider.

Updating IDP-Kit client

In case the redirect URL registered with our IDP-Kit client does not match, we need to make a change.

To update an existing client, we can use the clients register command provided under the OIDC scope of the CLI tool and add the -u flag to note that we want to change a client with the specified id.

idpkit config --oidc clients register -n "myFrontend" -r "http://localhost:8082/realms/NFT/broker/nft/endpoint" -u "client_id"

Parameter description

• -n - Name of the client

• -r - The redirect URL which should be used in the OIDC flow

• -u - The ID of the client we would like to update

After updating the client, we can now run the IDP-Kit and connect Keycloak to an application of our choice. We will be using Next.js and NextAuth.

Intro

Since the IDP Kit is compliant with the well adopted OpenID Connect standard for identity provision, it can be easily integrated, as a federated identity provider on Keycloak.

Assuming that you already have a local instance of Keycloak running, we will continue with the configuration of our federated identity provider. In case you need to setup Keycloak first, please have a look at their documentation on how to get started.

Configuration

To start with the configuration, we log in to the KeyCloak administration console with our admin credentials and navigate to the realm, for which we want to apply the configuration.

New external Identity Provider

1. In the admin console, we navigate to the Identity Providers section in the left menu bar and open the "Add provider..." drop-down menu and choose "OpenID Connect v1.0":

2. We fill out Alias and Display Name according to how we want the IDP Kit to be referred to in the Login UI

3. We scroll down to Import External IDP Config and enter the URL of the well-known OIDC discovery document of the IDP Kit and click import. For our IDP Kit which is running locally, this would be:

http://localhost:8080/api/oidc/.well-known/openid-configuration

We need to make sure IDP Kit is running, as Keycloak will import all the information it needs from that endpoint as soon as we press "Import".

4. Now we scroll down to Client Authentication and choose Client secret sent as basic auth as input field value. Then we provide Client ID and Client Secret which we got during the client registration step.

5. To make sure the IDP-Kit uses our NFT config settings during authentication, we need to provide openid nft_token as the value for Default Scopes and set Prompt to None

6. Now we can create the provider.

Check Redirect URI

Now that we've finished the setup of our Identity provider in Keycloak, we must make sure that the client we registered with the IDP-Kit has the correct redirect URL. The redirect URL should match the value found at Redirect URI in our just created Identity Provider.

Updating IDP-Kit client

In case the redirect URL registered with our IDP-Kit client does not match, we need to make a change.

To update an existing client, we can use the clients register command provided under the OIDC scope of the CLI tool and add the -u flag to note that we want to change a client with the specified id.

idpkit config --oidc clients register -n "myFrontend" -r "http://localhost:8082/realms/NFT/broker/nft/endpoint" -u "client_id"

Parameter description

• -n - Name of the client

• -r - The redirect URL which should be used in the OIDC flow

• -u - The ID of the client we would like to update

After updating the client, we can now run the IDP-Kit and connect Keycloak to an application of our choice. We will be using Next.js and NextAuth.

🤟 Welcome

In this tutorial, we create our own instance of the IDP Kit locally and configure it, so users can log in using their Verifiable Id Credential. We will register a client, connect our frontend and enable login with Verifiable Credentials. The frontend builds on Next.js and will use NextAuth.js as authentication library.

The IDP Kit uses the OIDC authentication flow, the same technology used by Sign-in with Apple, Facebook, Twitter and many more. If you want to learn more about it and how it works behind the scenes, you can have a look at our as well as how the ideas are translated when using .

🗂 Modules

1. - Build and run the project in your local environment

2. - Retrieve clientId and clientSecret from the IDP Kit, used in the frontend

3. - Configure scopes and claims for client

4. - Setup and connect frontend to IDP Kit and enable sign in with Verifiable Credentials

Intro

The verifiable credential data can be transformed and sent back to the client in various ways. In the IDP-Kit's default configuration (found in the file config/idp-config.json), the DID, first name, last name, gender, and birthday are mapped as claims to the profile scope while the required credential type is VerifiableId.

Intro

We have prepared a which we can use as a starting point. It uses NextAuth.js for handling authentication and a custom provider build by to connect the IDP Kit easily with NextAuths functionality. We won't go into details of how Next.js or NextAuth.js works.

Create the frontend app

We will need and or npm

1. Clone the project

2. Install the dependencies by running yarn install or npm install

3. Update CLIENT_ID and CLIENT_SECRET based on the response returned by the in the .env.example file.

4. Rename .env.example to .env

5. In pages/api/auth/[...nextauth].ts we update the identityProviderURL parameter of the SSIProvider. We can leave the third parameter in the SSIProvider as is, if you have not changed the port on which the IDP Kit is running locally. When you switch the port or use a hosted version of the IDP Kit, you need to update the parameter to reflect the new endpoint of the IDP Kit.

6. Now the project is set up and can be run

Intro

We have prepared a which we can use as a starting point. It uses NextAuth.js for handling authentication, which makes it easy for us to connect our Keycloak instance. We won't go into details of how Next.js or NextAuth.js works.

Create the frontend

1. We will clone the project and install all dependencies

2. Change directories

3. Install dependencies

Create Keycloak client

1. We log in to the KeyCloak administration console with our admin credentials and navigate to the realm, we used before to configure our external identity provider.

2. Under the Clients section, we create a new client, which we will use in our Next.js app.

3. We provide a Client ID and Name and click on Next.

4. We select Client authentication and the Standard flow and click Save.

5. In the overview of the new client we just created under the General Settings section, we update Valid redirect URIs to match our next.js application nextAuth callback URL: http://localhost:3000/api/auth/callback/keycloak

Connect Keycloak & Frontend

Now that we have the client registered with Keycloak we can add its credentials in our Next.js application.

1. Let's rename .env.example file to .env

2. We assign CLIENT_ID and CLIENT_SECRET to the values find in Settings and in the Credentials section respectively of our just created Keycloak client.

3. The ISSUER we set to the host of our Keycloak instance.

Those values will then be used by the build in NextAuth.js provider for Keycloak which can be found in pages/api/auth/[...nextauth].ts

Running the Project

Now that we have finished all configurations, we can start up our frontend.

What is next

Clients and why we need one

To use the IDP Kits functionality, we need to register our frontend application as client and collect client_id and client_secret. Those credentials will be used by the frontend to make requests to the IDP Kit, which will in turn ask the user if they want to sign in and check if they are allowed to do so, based on the Verifiable Credential in their wallet. After collecting the consent of the user and validating that they are allowed to log in, the IDP Kit will give the frontend a secret with which it can request information about the authenticated the user.

The exchange of information between the client, which is in our case the frontend application and the authorization server which is the IDP Kit are based on the OpenID Connect standards. I won't go into more detail here, but you can learn more about it in the or watch this great from OktaDev, which gives a great overview about OpenID Connect. To understand how the base ideas are then translated to the Verifiable Credential use case, you can dive into .

Client registration

Now that we know what we need and why we need it, let's go ahead and create our first client. Depending on the situation and personal preference, there are two options available: CLI tool, API.

Intro

Before you start with the project setup, make sure you have the following dependencies on your local machine:

Getting Started

For running the project, you have two options: Docker or Gradle.

Running the IDP-Kit Frontend The frontend with which the user will interact to authenticate by doing a connect wallet.

Configuring the SSI wallet used during authentication

In the verifier config (config/verifier-config.json), we can define the SSI wallet which should be used. For this example, we can use the hosted wallet by walt.id.

To setup the IDP Kit a few things may need to be considered and some configuration may be required, depending on your situation.

Data root

Configuration and data are kept in sub folders of the data root (by default the current working directory):

• config/

• data/

To override the data root, one can set the environment variable:

WALTID_DATA_ROOT

Command line interface - CLI

In the following sections you will find examples using the command line interface.

Refer to CLI | Command line interface for basic instructions of using the command line interface.

Submodule configuration

The IDP Kit consists of multiple submodules, which need to be configured according to your requirements:

• OIDC Manager

  • Provides standard OIDC API endpoints, for communication with client applications

• SIOP Manager

  • Provides presentation exchange and verification with SSI wallets via the OIDC/SIOP protocol

• NFT Manager

  • Provides communication with NFT wallets and verification of NFT collections and traits

Binding address and port

By default, the IDP Kit exposes its API endpoints bound to localhost on port 8080.

To override the default bindings, set the following environment variables:

WALTID_WALLET_BACKEND_BIND_ADDRESS

WALTID_WALLET_BACKEND_PORT

Note: these variables are inherited from Wallet Kit, which is why they have the term WALLET in it.

Command arguments

To set binding address and port, you can also use the command arguments of the run command like so:

To set the bind address to "192.168.0.1" and the port to 8081:

waltid-idpkit run -b "192.168.0.1" -p 8081

To bind to all interfaces (on the default port):

waltid-idpkit run --bind-all

NFT Kit JS

The IDP Kit needs to communicate with the NFT Kit JS to process the NFT authorization request. You need to run an NFT Kit JS instance and specify which URL is accessible.

"jsProjectExternalUrl":"http://localhost:4000",

API Keys for NFT verification

The underlying NFT Kit needs a configuration file to be able to verify NFTs for the IDP Kit. Therefore, you need to create a walt.yaml file in the root folder of the IDP Kit.

Only two values must be updated. One of the providers, depending on the network, where the NFT collection is lying and alchemy under the apiKeys section. The privateKey just holds a placeholder value and can stay as it is.

hikariDataSource:
  jdbcUrl: jdbc:sqlite:data/walt.db
  maximumPoolSize: 5
  autoCommit: false
  dataSource:
    journalMode: WAL
    fullColumnNames: false

azureKeyVaultConfig:
  baseURL:
  id:
  secret:

providers:
  ethereum: "ethereum"
  goerli: "goerli"
  polygon: "polygon"
  mumbai: "mumbai"

privateKey: "bd4cb3e507f342ee3a710370cef39dda48f17b0a158b0b8dddf000fbd5b2c2d9"


apiKeys:
  ethereumBlockExplorer: ""
  polygonBlockExplorer: ""
  alchemy: "alchemy_api_key"
  nftstorage: ""

providers: a list of URLs to RPC node provider for every network. You can get them either from Infura or Alchemy.

Examples:

• https://rinkeby.infura.io/v3/0184192d0fd9423b52322d79eca162b2

• https://polygon-mumbai.g.alchemy.com/v2/yjbYhlaH3U_vfnTiRQ3miGQS0cKwQMGh

alchemy:an API key from Alchemy.

To connect to the OIDC APIs, a client application needs to be registered and has to authenticate itself using its client_id and client_secret.

See section Client registration, for details on how to register a client and obtain the client_id and client_secret values.

Authenticated endpoints

Endpoints affected by the client authentication are

• token_endpoint

  • /api/oidc/token

• pushed_authorization_request_endpoint

  • /api/oidc/par

Authentication methods

The supported client authentication methods are published in the discovery document (token_endpoint_auth_methods_supported) on the well-known openid-configuration endpoint.

Currently supported authentication methods:

• client_secret_basic

  • the client needs to add the client_id and client_secret as Basic HTTP Authorization header, when calling the pushed authorization request or token endpoints.

In this section we look at the configuration of the OIDC Manager sub module.

If you haven't already, you may want to familiarize yourself with the basic IDP Kit Configuration, the Data Root and the Command Line Interface, in the previous sections, before moving on.

IDP configuration

The configuration of the OIDC manager can be adapted, by modifying the file

config/idp-config.json

External URL

Configure the URL via which the IDP/OIDC API will be reachable from an external source (i.e. from the client application):

{
  "externalUrl": "https://idp.walt-test.cloud",
[...]
}

Signature key for issued tokens

By default, the OIDC Manager creates an RSA key for RS256 token signatures on first startup.

To enforce a certain key or key/signature type, specify the key id in the configuration file like this:

{
  [...]
  "keyId": "715b3ebf65074f1183a48c4b7c8e311c",
  [...]
}

Go to section Keys and signatures for details on how to create keys and on supported signature types.

Open client registration

To allow unauthenticated client registration via the dynamic client registration API, specify the following configuration option:

{
  [...]
  "openClientRegistration": true,
  [...]
}

See also section Client registration for more details about registering and managing clients.

Fallback authorization mode

If the authorization mode, SIOP or NFT, can not be derived from the scopes and claims specified in the authorization request by the client application, or the request is ambiguous, the IDP Kit will choose the preferred mode based on this configuration option:

{
  [...]
  "fallbackAuthorizationMode": "SIOP",
  [...]
}

Claim configuration

To configure how the IDP Kit maps the scopes and claims from the authorization request to verifiable presentation requests for SSI, or NFT claims, one can define claim mappings and default claims in the claim configuration object. E.g.:

{
  [...]
  "claimConfig": {
    "vc_mappings": [
      {
        "scope": [ "profile" ],
        "claim": "name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.firstName $.credentialSubject.familyName"
      }
      [...]
    ],
    "nft_mappings": [
      {
        "scope": [ "profile" ],
        "claim": "name",
        "chain": "POLYGON",
        "smartContractAddress": "0x12345678901234567890",
        "trait": "name"
      }
    ],
    "default_nft_token_claim": {
      "chain": "POLYGON",
      "smartContractAddress": "0x12345678901234567890"
    },
    "default_vp_token_claim": {
      "presentation_definition": {
        "id": "1",
        "input_descriptors": [
          {
            "id": "1",
            "constraints": {
              "fields": [
                {
                  "id": "1",
                  "path": [ "$.type" ],
                  "filter": { "const":  "VerifiableId" }
                }
              ]
            }
          }
        ]
      }
    }
  }
  [...]
}

See section Claim mapping for details about this configuration object and the available options.

Configuration example

Here's a complete example for the idp-config.json:

{
  "externalUrl": "https://idp.walt-test.cloud",
  "keyId": "715b3ebf65074f1183a48c4b7c8e311c",
  "openClientRegistration": false,
  "fallbackAuthorizationMode": "SIOP",
  "claimConfig": {
    "vc_mappings": [
      {
        "scope": [ "profile" ],
        "claim": "name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.firstName $.credentialSubject.familyName"
      },
      {
        "scope": [ "profile" ],
        "claim": "family_name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.familyName"
      },
      {
        "scope": [ "profile" ],
        "claim": "given_name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.firstName"
      },
      {
        "scope": [ "profile" ],
        "claim": "gender",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.gender"
      },
      {
        "scope": [ "profile" ],
        "claim": "birthdate",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.dateOfBirth"
      },
      {
        "scope": [ "address" ],
        "claim": "address",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.currentAddress[0]"
      }
    ],
    "default_nft_token_claim": {
      "chain": "POLYGON",
      "smartContractAddress": "0x21dd9b1913d84ab295fdf19834b0b6824a5912ca"
    },
    "default_vp_token_claim": {
      "presentation_definition": {
        "id": "1",
        "input_descriptors": [
          {
            "id": "1",
            "constraints": {
              "fields": [
                {
                  "id": "1",
                  "path": [ "$.type" ],
                  "filter": { "const":  "VerifiableId" }
                }
              ]
            }
          }
        ]
      }
    }
  }
}

In order to support mapping of SSI credential data or NFT token metadata to standard OIDC scopes and claims, you have to define which credential types or NFTs are required and which property or trait in the credential/NFT data contains the claimed information.

If the required VP token claim or NFT token claim cannot be derived from the authorization request, one can configure default claims, that will be sent to the SSI or NFT wallet in this case.

Mapping Configuration

In general, we can configure the claim mappings in the IDP configuration file, in the claimConfig property, which contains an array of mapping objects for verifiable credentials: vc_mappings and NFT tokens: nft_mappings.

vc_mappings

Example:

{
  [...]
  "claimConfig": {
    "vc_mappings": [
      {
        "scope": [ "profile" ],
        "claim": "name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.firstName $.credentialSubject.familyName"
      },
      {
        "scope": [ "profile" ],
        "claim": "family_name",
        "credentialType": "VerifiableId",
        "valuePath": "$.credentialSubject.familyName"
      }
      [...]
    ]
  }
  [...]
}

Each mapping object contains the following properties:

• scope: One or multiple OIDC scope(s), this claim belongs to. E.g. profile, address, email, etc.

• claim: The name of the OIDC claim. E.g. name, given_name, family_name, email, etc.

• credentialType: The type of credential from which the claim information should be read

• valuePath: A JSON path leading to the claim value in the credential data. This supports multiple JSON paths separated by blanks, to concatenate values, like shown in the example claim name in the profile scope.

nft_mappings

Example:

{
  [...]
  "claimConfig": {
    "nft_mappings": [
      {
        "scope": [ "profile" ],
        "claim": "name",
        "chain": "POLYGON",
        "smartContractAddress": "0x12345678901234567890",
        "trait": "name"
      },
      [...]
    ]
  }
  [...]
}

Each mapping object contains the following properties:

• scope: One or multiple OIDC scope(s), this claim belongs to. E.g. profile, address, email, etc.

• claim: The name of the OIDC claim. E.g. name, given_name, family_name, email, etc.

• chain: The chain on which the NFT must be held by the user

• smartContractAddress: The address of the NFT collection, which the user must hold an NFT of

• trait: Key of the NFT metadata, which will be used to fill this particular claim value

Default claims

If the authorization request from the client application contains only the scope vp_token or nft_token, but does not specify any further scopes or claims to derive the required nft or verifiable presentation from, the IDP Kit will fall back to the default claims configured here:

default_nft_token_claim

The default claim used to fulfill an NFT token request.

Example:

{
  [...]
  "claimConfig": {
    [...]
    "default_nft_token_claim": {
      "chain": "POLYGON",
      "smartContractAddress": "0x12345678901234567890"
    }
  }
  [...]
}

The default nft token claim defines the following properties:

• chain: The chain on which the NFT must be held by the user

• smartContractAddress: The address of the NFT collection, which the user must hold an NFT of

default_vp_token_claim

The default claim used to request a verifiable presentation from the SSI wallet:

Example:

{
  [...]
  "claimConfig": {
    [...]
    "default_vp_token_claim": {
      "presentation_definition": {
        "id": "1",
        "input_descriptors": [
          {
            "id": "1",
            "constraints": {
              "fields": [
                {
                  "id": "1",
                  "path": [ "$.type" ],
                  "filter": { "const":  "VerifiableId" }
                }
              ]
            }
          }
        ]
      }
    }
  }
  [...]
}

The default vp token claim contains a presentation_definition object as specified by the DIF specification: Presentation Definition.

In this example, a filter for credentials with the type VerifiableId is definied.

The IDP Kit provides a command line interface (CLI) to register and manage clients. Furthermore, the dynamic client registration and management APIs are provided, according to the specifications in:

• OpenID Connect Dynamic Client Registration

• OAuth 2.0 Dynamic Client Registration Management Protocol [RFC7592]

Authentication for dynamic client registration API

To register a new client via the dynamic client registration API, authentication using the registration access token is required by default. The IDP Kit can be configured to allow unauthenticated client registration.

Registration access token

To get this registration access token use the command:

waltid-idpkit config --oidc clients token

This will output a valid JWT token to use with the register API endpoint, like this:

Output

[...]
Client registration master token:
eyJraWQiOiJhNGFhM2U4MT[...]nE3jfPqMQlgEhh6l0VbwhbsDjy7Q

Open client registration

To allow unauthenticated client registration requests via the REST API, set the following configuration option in the idp-config.json:

{
  [...]
  "openClientRegistration": true,
  [...]
}

Authentication for existing client management

For managing registered clients, i.e. get, update or removal of client information, via the dynamic client management API, you have to use the registration_client_uri and registration_access_token as returned by the client registration response for the specific client.

Register new client

CLI

To register a new client use the register command, like e.g.:

waltid-idpkit config --oidc clients register -n "MyApp" -r "https://myapp.com/redirect_uri"

To specify multiple redirect_uris, repeat the -r ... flag for each URI.

Use --all-redirect-uris and omit the -r ... flags, to allow all redirect URIs for this client.

Use -u <client_id> to update an existing client by its ID, instead of creating a new registration.

REST API

[POST] /api/oidc/clients/register

Post a client registration request object to this endpoint, using the registration access token described above, like shown in this simple example:

POST /api/oidc/clients/register HTTP/1.1
[...]
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9.eyJ[...]

{
  "client_name": "MyApp",
  "redirect_uris": [
    "https://myapp.com/redirect_uri"
  ],
  "all_redirect_uris": false
}

Result

In case of success, the CLI and REST API will output a client information object, corresponding to the client registration response from the OIDC spec: Client Registration Response.

Example:

{
    "client_secret_expires_at":0,
    "all_redirect_uris":false,
    "registration_client_uri":"https://[...]/api/oidc/clients/EI_9T[...]",
    "client_id_issued_at":1658239641,
    "client_secret":"884DUlIj4[...]",
    "redirect_uris":[
        "https://myapp.com/redirect_uri"
    ],
    "registration_access_token":"eyJraWQi[...]",
    "client_id":"EI_9TT[...]"
}

This example response has the following properties:

• client_secret_expires_at: Expiration timestamp of client secret, or 0 if no expiration

• all_redirect_uris: Specific to IDP Kit: allow all redirect URIs for this client if redirect_uris is empty or not set

• registration_client_uri: URI of API to get, update or delete this client information

• registration_access_token: access token for using registration_client_uri API to get, update or delete this client information

• client_id_issued_at: Timestamp of first registration of this client

• client_secret: Client secret to use for token endpoint authentication method

• client_id: Client id to use for token endpoint authentication method

• redirect_uris: Array of redirect URIs that are allowed for this client

List registered clients

To list all registered clients, type

waltid-idpkit config --oidc clients list

This will output a list of keys and client information objects for all registered clients:

Output

[...]
* EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4:
{
    "client_secret_expires_at":0,
    [...]
    "client_id":"EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4"
}
--------------------
* [...]

Each listed object corresponds to the client registration response, described in the section Register new client.

Get client information by ID

CLI

To get a client information by the client ID, use this command, specifying the ID via the -i ... command argument:

waltid-idpkit config --oidc clients get -i 6s5YcV84Tg7cZ8BM2-b6qcJiHKDTZD8YdQt-cf4eDbM

REST API

[GET] /api/oidc/clients/<client_id>

To get the client info via the dynamic client management API, make a GET call to the registration_client_uri using the registration_access_token given in the client information obtained from the initial client registration or the latest client update.

Result

The output is a client information object, that corresponds to the client registration response, described in the section Register new client.

Update client registration

CLI

To update an existing client registration use the -u ... command flag of the register command, like so:

waltid-idpkit config --oidc clients register -n "MyApp" -r "https://myapp.com/UPDATED_URI" -u EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4

REST API

[PUT] /api/oidc/clients/<client_id>

Post the updated client information, including all required parameters, to the registration_client_uri using the HTTP PUT method and the registration_access_token given in the client information obtained from the initial client registration or the latest client update.

Result

The output is a client information object, with the updated registration information, that corresponds to the client registration response, described in the section Register new client.

Remove client registration

CLI

Use the remove command to unregister an existing client registration:

waltid-idpkit config --oidc clients remove -i EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4

Example output

[...]
[main] INFO id.walt.idp.oidc.OIDCClientRegistry - Unregistering client EI_9TTRXw0C7gzKNLNfwNEMH1jChqzj-l0n4LUWxYm4
Client removed

REST API

[DELETE] /api/oidc/clients/<client_id>

To unregister the client via the dynamic client management API, make a DELETE request to the registration_client_uri using the registration_access_token given in the client information obtained from the initial client registration or the latest client update.

The result of a successful delete request, is an empty response with the HTTP response code 204 No Content.

By default, the OIDC Manager creates an RSA key for RS256 token signatures on first startup. On subsequent startups, the same key will be used again.

If you want to enforce a certain key or key type for token signatures, you may use the config command, providing the key management functions of the SSI Kit to create a key.

The following key and token signature types are currently supported:

Generate key

In the following example, I will show how to manually create an RSA key for the OIDC manager using the config command of the IDP Kit:

waltid-idpkit config --oidc key gen -a RSA

This command will generate an RSA key, save it in the key store, in the context of the OIDC manager, and prints the key ID:

Output:

[...]
[main] INFO id.walt.idp.cli.ConfigCmd - Running in context of: OIDCContext
Generating RSA key pair...
[main] DEBUG id.walt.services.keystore.HKVKeyStoreService - Storing key "715b3ebf65074f1183a48c4b7c8e311c".
Key "715b3ebf65074f1183a48c4b7c8e311c" generated.

List available keys

To list all the available keys in the OIDC Manager context, you can type:

waltid-idpkit config --oidc key list

Output:

[...]
Listing keys ...

Results:
[...]
- 1: "e8392ed7e8524b34bc4ab7609c2f6d99" (Algorithm: "RSA", provided by "SUN")
- 2: "715b3ebf65074f1183a48c4b7c8e311c" (Algorithm: "RSA", provided by "SUN")

Configure key

Now, to configure the key generated above, copy the key ID printed by the command, and paste it into the configuration file, like so:

{
  [...]
  "keyId": "715b3ebf65074f1183a48c4b7c8e311c",
  [...]
}

In this section we look at the configuration of the SIOP Manager sub module.

If you haven't already, you may want to familiarize yourself with the basic , the and the , in the previous sections, before moving on.

Verifier backend configuration

The SIOP Manager is derived from the Verifer Manager in the Verifier backend component of the .

Therefore, we require the same configuration of the verifier component as documented in the Wallet Kit documentation, in the file

config/verifier-config.json

In order to avoid duplication, please refer to the Wallet Kit documentation for details on how to configure:

Config command

In order to execute the config command in the SIOP Manager context, use the following command:

Verification policies

Refer to , in the Wallet Kit documentation, to understand how to manage SSI verification policies.

Note, that the IDP Kit requires a different config command flag than the Wallet Kit for configuring the SIOP manager:

Configuration example

Here's a complete example for the verifier-config.json:

To configure the NFT manager, a few things may need to be considered, and some configuration may be required, depending on your situation.

Ways to specify the NFT collection

The default configuration, which will be used if no claim value is present in the authorization request. It can be set in config/idp-config.json. A more detailed overview of all possible claim configurations, can be found in the section.

Possible values for the chain key in both configurations: ETHEREUM, POLYGON, TEZOS, GOERLI, MUMBAI, GHOSTNET.

Activate and specify the OPA policy verification

To activate the OPA policy verification, you may provide some configuration.

Configuration of the wallet connect page

If you don't want to use the default built-in wallet connect page, you can create a nft-config.json file and provide a custom connect page.

Choose Ecosystem

To better understand what the IDP Kit does, let's first recap on the basics of OIDC authentication flows.

For more details, visit the .

OIDC authentication flows

In a usual OIDC authentication flow, the client application makes an authentication/authorization request to an authorization server or identity provider. In this request, the client includes the scopes and/or claims, which define the pieces of information about the user required by the application.

The identity provider redirects to a login or authentication page, where the user has to authenticate and give their consent to the requested information being shared with the application.

Depending on the response type chosen by the application, the identity provider will provide an authorization code, which can be traded for an access token and ID token, or the respective tokens directly, by calling the redirection URI of the application with the respective parameters.

The application can use the access token to retrieve the user information, which was originally requested. The id token usually contains a user ID, issuer ID, expiration date, etc., which the application can use at it's own discretion.

Code flow

The application requests response_type=code in the authorization request, and receives an authorization code from the identity provider, which can be traded for access_token and id_token on the token endpoint. Using the access_token the application can retrieve the requested user information over the userInfo endpoint.

Communication with the identity provider is usually done via a backend of the client application and requires client authentication.

Implicit flow

The response_type requested by the application is id_token token, id_token or token, and the identity provider sends the requested tokens directly to the callback uri of the client application. The application can use the access_token to retrieve the requested user information over the userInfo endpoint. If only id_token was requested by the application, the user information is included in the id_token returned by the identity provider.

This flow is usually chosen if the application front-end conducts the user authorization without any backend interaction.

Hybrid flow

In a hybrid flow, the client application requests any combination of code, id_token and token response types and has the option to follow the implicit or code flow to retrieve user information according to the specific requirements.

OIDC scopes and claims

An OIDC authentication request usually contains a set of scopes and/or claims requested by the client application.

Scopes usually imply a predefined set of claims, whereas a claim is a request for a specific piece of information about the user.

Example scopes:

• profile

  • Claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, and updated_at

• email

  • Claims: email, email_verified

• address:

  • Claims: address

• phone:

  • Claims: phone_number, phone_number_verified

Example request

This example request consists of the following parameters:

• response_type: The response_type requested by the application

  • In this case an authorization code is requested.

• scope: The requested scopes defining the information requested by the application:

  • openid: default scope, that is always included in OIDC requests
• client_id: The ID of the client application, as it was registered with the identity provider

• state: Arbitrary state information of the client application, that is propagated to the authentication response on the callback/redirection URI.

• redirect_uri: Redirection or callback URI of the client application, which will be called with the authentication response (in this case: the authorization code) in the URI parameters

The IDP Kit supports retrieval and verification of NFTs from wallets.

This section will explain the principles of how OIDC authentication requests are translated into NFT requests and the options available to craft such requests.

How it works

To understand how identity provision via NFTs can be leveraged in an OIDC authentication flow, you may first want to recap on the basic principles of .

OIDC via NFTs

When using NFTs as information source, the IDP Kit will derive the required NFT collection from the authentication request and redirect to an application, where the user can connect his wallet and share their address.

After the user has shared their address, the application will send it back to the IDP Kit, where the NFT Manager will make sure that the user is the rightful owner of that shared address, by utilizing the concepts described in, and that the shared address is associated with the required NFT collection sent in the authentication request. Have a look at the page to see how this can be configured and which defaults can be set.

The verified data is then transformed into the response format requested by the application, which by default will include the account address and optionally specified metadata of the NFT.

The authorization flow visualized

Claiming nft_token

In this scenario, the client application requests the raw NFT data, without mapping to standard OIDC claims, by specifying the custom nft_token claim or defining the nft_token scope in the authorization request.

nft_token Scope

By specifying the nft_token scope in the authorization request, the client application requests the validation of the user being a holder of an NFT in the required NFT collection and the user info to be included in the response. The IDP Kit will determine the NFT request, which is sent to the NFT wallet, by the following sources in this order:

1. nft_token claim, specified by the client application as a custom claim object in the authorization request

nft_token Claim

The nft_token claim should be constructed as follows:

Authorization POST request:

When making the authorization post request, the client can specify a claim field in the body, with a value describing the NFT collection. The format will be as follows:

Authorization GET request:

When making the authorization get request, the client can specify a claim field, as shown in the example above, in a JSON object. This object will then be sent URL encoded via the query parameters.

IDP Kit receiving the request

The IDP Kit takes the request and opens a wallet connect page, where the user is prompted to connect their wallet to the page and share their address. The shared address will then be sent back to the IDP Kit, which verifies that the user is the rightful owner and holder of an NFT of the required NFT collection. After verification, the IDP Kit sends the information (account address/nft metadata) back to the client application in the nft_token property of the user info.

The application can rely on the received data, as the IDP Kit is verifying the ownership of NFT and address.

Standard OIDC scopes, claims and claim mapping

In this scenario, the client application simply makes a standard OIDC authorization request, like any other OIDC compliant identity provider would expect it. E.g. the application could request the profile scope, to receive name, given name, family name, gender, date of birth, etc. of the user from the IDP Kit.

The IDP Kit maps the required claims to suitable traits in the NFT metadata that contain the requested information, by getting access to the NFT through the shared address of the user. The gathering of the user address will be handled by a separate wallet connect page (web application), without the client taking any notice.

Once the IDP Kit has received the address of the user from the wallet connect page, got the information from the NFTs metadata and verified all of it. The IDP Kit translates the received data into the standard user info claims requested by the application and provides it on the standard user info endpoint.

To use this flow, the client application needs no additional knowledge about the underlying protocol. In most cases, a simple configuration change would suffice to make an application connect to the IDP Kit and accept NFT data for user authentication, given that OIDC is already used as an authentication layer.