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.
We will need Node.js and yarn or npm
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 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
7. When we visit http://localhost:3000 and press the login button, the authentication is started.
Let your users authenticate in a Next.js app with NFTs.
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.
IDP Kit Setup - Build and run the project in your local environment
Client Registration - Retrieve clientId and clientSecret from the IDP Kit, used in the frontend
NFT Collection Configuration - Set NFT collection required by the users to login successfully
Next.js - Setup and connect frontend to IDP Kit and enable sign in with NFTs
You can also watch the full tutorial here.
Before you start with the project setup, make sure you have the following dependencies on your local machine:
For running the project, you have two options: Docker or Gradle.
Cloning the project
2. Changing directory
3. Open the project in your feavourite IDEA
4. Create a walt.yaml
file in the root directory of the project. Values needed are described in the configuration section.
5. Building the project
6. Creating an alias (optional)
Cloning the project
2. Changing directory
3. Open the project in your feavourite IDEA
4. Create a walt.yaml
file in the root directory of the project. Values needed are described in the configuration section.
4. Building the project
5. Creating an alias (optional)
Running the IDP-Kit Frontend The frontend with which the user will interact to authenticate by doing a connect wallet.
Change into the frontend directory
Install dependencies using node v.16
Running the project
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.
Cloning the project
2. Changing directory
3. Run the following command
4. Run the following command
3. Run project
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.
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 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
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.
To register a new client, we can use the clients register
command provided under the OIDC scope of the CLI tool.
Parameter description
-n
- Name of the client
-r
- The redirect URL which should be used in the OIDC flow
Other Options:
--all-redirect-uris
- Redirect can go to any URL specified in the OIDC flow requests
If we set a redirect URL we can make sure that no other party will be able to use our authentication flow, even if they would get access to our secrets. For our project we set the URL http://localhost:3000
as this will be the URL under which our frontend application will be hosed. Later if we were to put the application into production it would be something like https://applicationName.com
. In this case we would need to update our registerd client and reflect the new redirect URL.
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.
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
Learn more CLI tool commands and options.
In order to use the API, we need to launch it first.
To register a new client, we can make a POST request to /api/oidc/clients/register
. However, by default the registration of new clients via API, requires you to authenticate. Providing the master_token
in the header of the request makes sure the registration goes through.
To get the master_token
we can execute the clients token
command under the OIDC scope of the CLI tool.
We need to replace master_token
in the Authorization request header before executing.
Save the response somewhere, where you can later retrieve the information. Most importantly, the client_id
and client_secret
.
If we set a redirect URL we can make sure that no other party will be able to use our authentication flow, even if they would get access to our secrets. For our project we set the URL http://localhost:3000
as this will be the URL under which our frontend application will be hosed. Later if we were to put the application into production it would be something like https://applicationName.com
. In this case we would need to update our registerd client and reflect the new redirect URL.
To update a client we make a PUT request to the /api/oidc/clients/<client_id>
and provide the registration_access_token
, which we got during client registration. In order for the update to go through, we need to provide the whole response we got from the client registration step in the update request body.
Make sure before executing the request, to replace the clientid
in the request URL and the registration_access_token
Learn more API endpoints and options or visit the swagger docs.
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
We also need to configure other properties in the same file:
NFT collection configuration example:
We also need to configure other properties in the same file:
NFT collection configuration example:
We also need to configure other properties in the same file:
We also need to configure other properties in the same file:
In the "smartContractAddress":
You should provide the asset Creator Account
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.
Rebuild the project
2. Expose the API
Rebuild image
2. Expose the API