Express.js SDK

If you haven’t already got a Kinde account, register for free here (no credit card required). Registering gives you a Kinde domain, which you need to get started, e.g. yourapp.kinde.com.

This topic assumes you are building with ExpressJS and have the relevant express packages already installed.

You can view Kinde’s Express JS docs and Express JS starter kit in GitHub.

Set up your app

Link to this section

Add Kinde ExpressJS SDK as a dependency

Link to this section

Node version 18.x.x or newer.

npm

npm i @kinde-oss/kinde-node-express

yarn

yarn add @kinde-oss/kinde-node-express

pnpm

pnpm add @kinde-oss/kinde-node-express

Integrate with your app

Link to this section

You’ll need to import our Kinde helpers into your project. We recommend you do this in the entry point of your application, typically index.js or app.js

const express = require("express");
const {setupKinde, protectRoute, getUser, GrantType} = require("@kinde-oss/kinde-node-express");

const app = express();

const config = {
  clientId: "<YOUR_CLIENT_ID>",
  issuerBaseUrl: "https://<YOUR_SUBDOMAIN>.kinde.com",
  siteUrl: "http://localhost:3000",
  secret: "<YOUR_CLIENT_SECRET>",
  redirectUrl: "http://localhost:3000",
  scope: "openid profile email",
  grantType: GrantType.AUTHORIZATION_CODE, //or CLIENT_CREDENTIALS or PKCE
  unAuthorisedUrl: "http://localhost:3000/unauthorised",
  postLogoutRedirectUrl: "http://localhost:3000"
};

setupKinde(config, app);

1. In Kinde, go to Settings > Applications > [Your app] > View details.
2. Replace the placeholders in the code block above with the the values from the App Keys section.
3. Replace http://localhost:3000 with the url of wherever your app is running.

Environments

Link to this section

As part of your development process, we highly recommend you create a development environment within your Kinde account. In this case, you’d use the Environment subdomain and app key values in the code block above.

Set your callback and logout URLs

Link to this section

Kinde will redirect your user to authenticate. They’ll be redirected back to your Express app after signing in or signing up.

To authenticate your app, you need to specify which URL Kinde should redirect your user.

1. In Kinde, go to Settings > Applications > [Your app] > View details.
2. Set the Allowed callback URLs (redirect URIs) to the URL of your app. This is where your application is served. For local development this could be http://localhost:3000. This is required for your users to sign in to your app successfully. This should match the redirectUrl you set in the config in the previous step.
3. Set the URLs they’ll be redirected to after signing out, by adding Allowed logout redirect URLs to your JavaScript applications logout page. For local development this could be http://localhost:3000. This should match the siteUrl you set in the config in the previous step.
4. Select Save.

Note: http://localhost:3000 is an example of a commonly used local development URL. It should be replaced with the URL where your app is running.

Sign in / register

Link to this section

Kinde provides sign in / register methods that are easy to implement. Here’s an example of adding buttons to your HTML:

<div id="logged_out_view">
  <a href="/login">Sign in</a>
  <a href="/register">Register</a>
</div>

Clicking either of these buttons redirects your user to Kinde, where they authenticate before being redirected back to your site.

Handle redirect

Link to this section

Once your user is redirected back to your site from Kinde, you can set a callback to take place. The callback automatically passes in the user object and any application state you set prior to the redirect.

app.get("/", (req, res) => {
  if (req.session && req.session.kindeAccessToken) {
    res.send("You are authenticated!");
  } else {
    res.send("You are not");
  }
});

Protecting routes

Link to this section

The protectRoute middleware included in the SDK allows you to tell Express which routes are for authorized users only.

app.get("/admin", protectRoute, (req, res) => {
  res.send("Welcome to the admin area");
});

You can pass an unAuthorisedUrl into the setupKinde configuration object which will to tell Kinde where you would like the user to be redirected in the case of protectRoute identifying the user is not yet authenticated.

Access the user object

Link to this section

The getUser middleware included in the SDK allows you to add the user object to the request.

app.get("/admin", protectRoute, getUser, (req, res) => {
  console.log(req.user);
  res.send(`Hello, ${req.user.given_name}`);
});

Sign out

Link to this section

This is implemented in much the same way as signing in or registering. The Kinde SDK already comes with a /logout method.

<a href="/logout">Sign out</a>

Test sign up

Link to this section

Register your first user by signing up yourself. You’ll see your newly registered user on the Users page of the relevant organization in Kinde.

Verify JWT

Link to this section

This SDK also contains a library for verifying JWTs signed by Kinde. used as a layer of protect API endpoints. Initialize the library as follows:

const {jwtVerify} = require("@kinde-oss/kinde-node-express");

const verifier = jwtVerify("https://<your_kinde_subdomain>.kinde.com");

Replace <your_kinde_subdomain> above with the subdomain you registered on Kinde. The step above caches your JWKS for Kinde in your Express application.

Protect endpoints

Link to this section

If you add the verifier middleware to an endpoint it will validate the token. If valid the users Kinde id is added to the request, otherwise a 403 error is thrown.

app.get("/some-route", verifier, (req, res) => {
  console.log(req.user); // {id: kp:the-users-kinde-id}
});

Kinde Management API

Link to this section

To use the Kinde management API please see @kinde/management-api-js

SDK API Reference - setupKinde

Link to this section

clientId

Link to this section

The unique ID of your application in Kinde.

Type: string

Required: Yes

issuerBaseUrl

Link to this section

Either your Kinde URL or your custom domain. e.g https://yourapp.kinde.com

Type: string

Required: Yes

redirectUrl

Link to this section

The URL that the user will be returned to after authentication.

Type: string

Required: Yes

secret

Link to this section

The unique Client secret of your application in Kinde

Type: string

Required: Yes

siteUrl

Link to this section

Where your user will be redirected when they sign out.

Type: string

Required: Yes

unAuthorisedUrl

Link to this section

The URL the user will be redirected to if protectRoute finds the user is not authenticated.

Type: string

Required: No

Reach out to support@kinde.com if you need help getting Kinde connected.