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.
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 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
Let your users authenticate in a Next.js app with a Verifiable Credential.
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 concept section as well as how the ideas are translated when using Verifiable Credentials.
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
Verifiable Credential Configuration - Configure scopes and claims for client
Next.js - Setup and connect frontend to IDP Kit and enable sign in with Verifiable Credentials
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.
Learn more about claim mapping
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 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 Verifiable Credential use case, you can dive into Identity provision via SSI.
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.
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
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.