🤟 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 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 by Keycloak

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

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

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

📽️ Video Version

You can also watch the full tutorial here.

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

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

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 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 NFT 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

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.

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.

The user of the frontend application needs or another 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

We will need and or npm

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.

Now we can log in as long as we hold an NFT of the collection we specified in the .

What is next

You made it, you've built login with NFTs with Keycloak and Next.js! Share your progress in our channel or on , then we can celebrate together 🤟

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.