DEV Community: Ebrahim Hoseiny Fadae

Using Docker Compose setup scripts like a PRO

Ebrahim Hoseiny Fadae — Wed, 25 Jun 2025 12:26:08 +0000

Why we need setup scripts?

Reducing time to clean-start the project.
Minimizing the feedback loop.
Self-documented setup scripts.
Facilitate team collaboration.
More automations in CICD pipelines.
Deterministic and version controlled environments.

Does docker have built-in support for setup scripts?

Docker has introduced some features to support this, but they aren't yet powerful enough for more advanced use cases. To achieve more, we define something called Setup Service.

Built-in Docker Compose setup scripts

This feature requires Docker Compose 2.30.0 and later.

Post-start:

According to Docker Compose docs:

Defines a sequence of lifecycle hooks to run after a container has started. The exact timing of when the command is run is not guaranteed.

services:
  test:
    post_start:
      - command: ./do_something_on_startup.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

If the post_start script fails, the container will terminate with the same exit code.

Pre-stop:

According to Docker Compose docs:

Defines a sequence of lifecycle hooks to run before the container is stopped. These hooks won't run if the container stops by itself or is terminated suddenly.

services:
  test:
    pre_stop:
      - command: ./do_something_on_stop.sh
        user: root
        privileged: true
        environment:
          - FOO=BAR

Limitations

The lifecycle hooks are useful in many scenarios, but they also have some limitations.

Not always, everything we need is in the same container. Sometimes we need different set of tools, the docker cli or even different OS.
If the script needs anything more than some simple shell commands with no extra dependencies, the container is coupled with its setup script, potentially increasing the size and maintenance cost.
We can't apply resource limitation only to setup script.
This feature is currently new, but it won’t be an issue in the future.

References:

Using lifecycle hooks with Compose

Isolated Setup Services

The migrate service contains all the logics for initiating the database. It will restart on failure. Also Docker Compose watch mode is used to make sure this script will be executed every time the database schemas are updated.

services:
    migrate:
        build:
            dockerfile: Dockerfile.migrate # Script execution environment
        command: ./migrate.sh
        deploy:
            restart_policy: # Tune it based on fail rate of the script
                condition: on-failure
                delay: 5s
                max_attempts: 5
                window: 120s
        resources: # Usually, setup requires more resource
            limits:
                memory: 128mb
        develop:
            watch:
                - action: rebuild
                  path: src/db # Change it based on your folder structure
        depends_on:
            postgresql: # Make sure postgresql has healthcheck instruction
                condition: service_healthy

If the script can't finish successfully, the whole project will shutdown only if the main service of the project depends of the migrate service.

Limitations:

There’s no equivalent to a pre_stop script.

Setup scripts are services themselves, so you can use post_start and pre_stop instructions in them! If you’re creative, you can do some really cool things with them :)

Docker-dependent Setup Services

Sometimes we need access to host's docker cli to execute a command.

services:
    setup:
        image: docker:28.1-cli # It is better to matched with host's docker
        environment:
            - COMPOSE_PROJECT_NAME=$COMPOSE_PROJECT_NAME # Required
        command: docker compose exec postgresql ./setup.sh
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - ./docker-compose.yml:/docker-compose.yml
        depends_on:
            postgresql: # Make sure postgresql has healthcheck instruction
                condition: service_healthy
        deploy:
            restart_policy: # Tune it based on fail rate of the script
                condition: on-failure
                delay: 5s
                max_attempts: 5
                window: 120s
        resources:
            limits:
                memory: 256mb

Conclusion

Automation is the remedy for the curse of complexity. We can automate setup scripts in order to hide the complexity of setting up. While Docker provides powerful tools for this, there’s still room for improvement in supporting these workflows more natively.

Part IV: Configuring OpenID Security Settings in Node.js

Ebrahim Hoseiny Fadae — Fri, 17 Jun 2022 08:02:18 +0000

Introduction

In this tutorial, we will focus on configuring the security aspects of OIDC (OpenID Connect 1.0). Follow along as we guide you through the necessary steps to ensure a secure OIDC setup in panava/node-oidc-provider. Let's get started with configuring the security aspects of OIDC.

Key configuration

To ensure secure token validation, signing, and cookie encryption, we need to provide two types of keys: a jwk formatted key and a secure string for cookie encryption. While there are numerous jwk generator tools available, please note that the sample value provided below should not be used in production environments.

Update configs

./oidc/src/configs/configuration.ts

import { Configuration } from "oidc-provider";

export const configuration: Configuration = {
  jwks: {
    keys: [
      {
        kty: "RSA",
        n: "jw3bixcae4ktBdXYcKeK5J7pmsXvQdvuOB8yv_q426tsMDlTZ1jj9CgYEZF_SCfzwQ5pcogLD-WY-LYJtt8zfjU_mWZZWcbR1QcMIWhLsSdi2OSlksIewMiv5CzvDBzs6h9sU0yr6yY6SYmT89jXU-D0MqSakDR0x0tyVUonGAWiVGJYINCCEbonoqFYAXjKdrNCCIliXiWQS6rajkEEXj0I2uQr4L1S80mSWWvDfFmFw4yC7V9nOGf1OPotscLCpT7vzlhHCuh3rY12bTEceZeARQ9G9aWQMBhQZPIPBvLdTRl5smFByFJ_FWs2yXXdHXFRo2L8UgwV2D4qVlgUXw",
        e: "AQAB",
        d: "PodKHUPd-X1-RnywfJ1fIosrhNFbwSfGupU4c529y5bkVTfZcuTxzrjvvE4imoGMFCiegsdgPnSXJq87E8oAEfxobj7Ec29qLHlGHhweabLTjAZ1MO7UzmNqLoxNeLfz_mn5yXdL9h7hf185Ym63wBwl4TT9smabXLlnokwlRmQXL-FWN5P50X60XgPG9hbv5BGPCrfbNNkLzae3fVeTfAZUYw-rwfrKN_HVUz78lo3cNhE2AVMnIF2CeZeH1xrUC81MWGJi7W1R1MtMTUObdqCpqLMtoWSojF3UT0pOMCiMeEt25EGpMiRVNy8HQD-z92uBEh8n2DYWb8Fou1Wa0Q",
        p: "23oJTOlWauw_fQJxBmwkfzPL_j9p_Fjtf_ThESn4ZpCkl2Y5cKSqc70bBP3SkgKRWWIt8QunkmkSHDmVzu0_UQu7YgCxqwwR8TvK8uCgNw8umtE_2w2fvf8l_863TEg4btz87kMtk01vWRUcqQxlBvd-bTmL8FDm0iblkskSpbs",
        q: "ptwhZzh1TkXFiglDz04_dC6s-Ek_qRxTtUSdhaRr7UDzpa_mEEd41m3kgmjgIlK-FgDpf66N4OWHQow76PVtRUAQSZDSPo4k8TNs5AY_oyzIBAWBnakfs8L368Vo4O3RZJ4wiMqnphTRGiM6rLOev74uTILcVnPgDZLbAm2Gb60",
        dp: "QDjIienpcKYqucDCI_f3AgW9Fmul7sJy1LNqPGSEnDaNAwRVoIF-oxld06sWN8VqlLYm7VbUtQHr27h5_q_rjCKbtUSwuHVytp0heMqD9ziJEaJTRh0JdkY370-k0Tx8zuv5UxrzNhw9jdqgpVLMKSq4outo6Gwz7qCVIsuVmks",
        dq: "FHPNAFryPfrdYLMMBcAAlRwXhYNs8yyOshxL9pKVzAn3E2sBFyO7kwT7SmTSfEKKHCZWeJkLuPJJZwXLXh2fHCrjFDFVI-fGbW4xPa3qZPTbO2r1XT7arO0L-HFFDrT3wo6FQm8cp4XLr5l72qlVnwkPob80hMBFSUSj5aNJJC0",
        qi: "MJJ6KTrCdq1gEgH-MpDF4DeXhE_dlB1P2am3juUR8ieZmohWbruBo6vmA_9Fm_lUs6V3qZ7gjbszguQZwcIFnvXceOBMH35_8TQLM3IrnNTJJTyWslrH3rdLAsIPk_x0cgIJ_gC0BHiQ9TfW8mKjGAK0JRv-V8XXnT4ZFQrlmQI",
      },
    ],
  },
  cookies: {
    keys: ["subzero"],
  },
};

TTL config

We have to tell the authorization server what is the lifetime of every token. Usually, we are good to go with defaults.

Update configs

./oidc/src/configs/configuration.ts

export const configuration: Configuration = {
  ttl: {
    AccessToken: function AccessTokenTTL(ctx, token, client) {
      if (token.resourceServer) {
        return token.resourceServer.accessTokenTTL || 60 * 60; // 1 hour in seconds
      }
      return 60 * 60; // 1 hour in seconds
    },
    AuthorizationCode: 600 /* 10 minutes in seconds */,
    BackchannelAuthenticationRequest:
      function BackchannelAuthenticationRequestTTL(ctx, request, client) {
        if (ctx && ctx.oidc && ctx.oidc.params?.requested_expiry) {
          return Math.min(10 * 60, ctx.oidc.params?.requested_expiry as number); // 10 minutes in seconds or requested_expiry, whichever is shorter
        }
        return 10 * 60; // 10 minutes in seconds
      },
    ClientCredentials: function ClientCredentialsTTL(ctx, token, client) {
      if (token.resourceServer) {
        return token.resourceServer.accessTokenTTL || 10 * 60; // 10 minutes in seconds
      }
      return 10 * 60; // 10 minutes in seconds
    },
    DeviceCode: 600 /* 10 minutes in seconds */,
    Grant: 1209600 /* 14 days in seconds */,
    IdToken: 3600 /* 1 hour in seconds */,
    Interaction: 3600 /* 1 hour in seconds */,
    RefreshToken: function RefreshTokenTTL(ctx, token, client) {
      if (
        ctx &&
        ctx.oidc.entities.RotatedRefreshToken &&
        client.applicationType === "web" &&
        client.tokenEndpointAuthMethod === "none" &&
        !token.isSenderConstrained()
      ) {
        // Non-Sender Constrained SPA RefreshTokens do not have infinite expiration through rotation
        return ctx.oidc.entities.RotatedRefreshToken.remainingTTL;
      }
      return 14 * 24 * 60 * 60; // 14 days in seconds
    },
    Session: 1209600 /* 14 days in seconds */,
  },
};

Summary

Last part but not the least. We looked how we can change some default configurations to increase security. Keep in mind there are a lot of security considerations that fall beyond the scope of this article.

Final words

I hope the article has been helpful. Please help me to improve it by sending me feedback.

Part III: Adding Resource Server Authorization to OpenID with Node.js

Ebrahim Hoseiny Fadae — Fri, 17 Jun 2022 07:42:31 +0000

Introduction

In this article, we will continue building upon our OIDC (OpenID Connect 1.0) implementation with Node.js to add resource server authorization. Resource server authorization ensures that only authorized clients can access protected resources. We will create a separate client specifically for the resource server, which will have restricted access and cannot issue new tokens.

Let's start

We call every entity or action that is accessible through a URI a resource. Authorization server only grants access for resource owner with valid scopes.

Update configuration

We will create a separate client for resource server. This client is a restricted client which only can access resources. We can't issue new token with this client. Also we can remove it to revoke every user access to resources. We have enabled introspection feature which able us to validate a token. resourceIndicators is were we define oure resource server.

./oidc/src/configs/configuration.ts

export const configuration: Configuration = {
  clients: [
    {
      client_id: "api",
      client_secret: "night-wolf",
      redirect_uris: [],
      response_types: [],
      grant_types: ["client_credentials"],
      scope: "openid email profile phone address",
    },
  ],
  features: {
    introspection: {
      enabled: true,
      allowedPolicy(ctx, client, token) {
        if (
          client.introspectionEndpointAuthMethod === "none" &&
          token.clientId !== ctx.oidc.client?.clientId
        ) {
          return false;
        }
        return true;
      },
    },
    resourceIndicators: {
      defaultResource(ctx) {
        return Array.isArray(ctx.oidc.params?.resource)
          ? ctx.oidc.params?.resource[0]
          : ctx.oidc.params?.resource;
      },
      getResourceServerInfo(ctx, resourceIndicator, client) {
        return {
          scope: "api:read offline_access",
        };
      },
    },
  },
};

Add API service

To run the API server follow these steps. We will set up everything under ./api directory.

1. Add dependencies

$ yarn add koa
$ yarn add @types/koa -D

2. Add controller

We will create a mocked service. It will return PI number and we treat it as top secret information!

./api/src/controllers/api.controller.ts

import { Middleware } from "koa";

export default (): { [key: string]: Middleware } => ({
  pi: async (ctx) => {
    ctx.status = 200;
    ctx.message = Math.PI.toString();
  },
});

3. Add middlewares

We reached the magical part! Here we check if the user has access to the resource. Then we will pass session information to the next controller in the chain.

./api/src/middlewares/auth.middleware.ts

import { Middleware } from "koa";
import fetch from "node-fetch";

export const authenticate: Middleware = async (ctx, next) => {
  const body = new URLSearchParams();
  if (!ctx.request.headers.authorization) return ctx.throw(401);
  body.append(
    "token",
    ctx.request.headers.authorization.replace(/^Bearer /, "")
  );
  body.append("client_id", process.env.CLIENT_ID as string);
  body.append("client_secret", process.env.CLIENT_SECRET as string);
  const url = `${process.env.AUTH_ISSUER}/token/introspection`;
  const response = await fetch(url, {
    method: "POST",
    headers: {
      ["Content-Type"]: "application/x-www-form-urlencoded",
    },
    body: body,
  });
  if (response.status !== 200) ctx.throw(401);
  const json = await response.json();
  const { active, aud } = json;
  // Resource URI and audience (aud) must be equal
  if (active && aud.trim() === ctx.request.href.split("?")[0]) {
    ctx.state.session = json;
    await next();
  } else {
    ctx.throw(401);
  }
};

// Check if scope is valid
export const authorize =
  (...scopes: string[]): Middleware =>
  async (ctx, next) => {
    if (
      ctx.state.session &&
      scopes.every((scope) => ctx.state.session.scope.includes(scope))
    ) {
      await next();
    } else {
      ctx.throw(401);
    }
  };

4. Add router

Here we bind the router to the controller. Also, we give the required scopes for ./pi controller.

./api/src/routes/api.router.ts

import Router from "koa-router";
import apiController from "../controllers/api.controller";
import { authenticate, authorize } from "../middlewares/auth.middleware";

export default () => {
  const router = new Router();

  const { pi } = apiController();

  router.get("/pi", authenticate, authorize("api:read"), pi);

  return router;
};

./api/src/routes/index.ts

import Router from "koa-router";
import appRouter from "./api.router";

export default () => {
  const router = new Router();

  router.use(appRouter().routes());

  return router;
};

5. Start the server

Server startup script

./api/src/index.ts

import cors from "@koa/cors";
import dotenv from "dotenv";
import Koa from "koa";
import path from "path";
import router from "./routes";

dotenv.config({ path: path.resolve("api/.env") });

const app = new Koa();

app.use(cors());
app.use(router().routes());

app.listen(process.env.PORT, () => {
  console.log(
    `api listening on port ${process.env.PORT}, check http://localhost:${process.env.PORT}`
  );
});

Add service page in app

As the final piece, we create a consumer app under ./app directory which accesses API server to access PI resource.

Add html file

./app/src/views/pi.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body class="app">
    <div class="login-card">
      <h1><%= title %></h1>
      <form autocomplete="off">
        <label>Token</label>
        <input id="token" required name="token" placeholder="Token" />
        <p id="pi" style="margin-top: 0">Value: -</p>

        <button type="button" class="login login-submit" onclick="onClick()">
          Fetch
        </button>
      </form>
    </div>
  </body>
  <script>
    async function onClick() {
      try {
        const response = await fetch("<%= apiUrl %>/pi", {
          headers: {
            ["Authorization"]: `Bearer ${
              document.getElementById("token").value
            }`,
          },
        });
        if (response.status === 401) {
          return alert("You are not authorized to access PI.");
        } else if (response.status !== 200) {
          return alert(" Failed to fetch PI.");
        }
        const pi = await response.text();
        document.getElementById("pi").innerText = `Value: ${pi}`;
      } catch (error) {
        alert("Error encountered.");
      }
    }
  </script>
</html>

Add controllers

./app/src/controllers/app.controller.ts

export default (): { [key: string]: Middleware } => ({
  pi: async (ctx) => {
    return ctx.render("pi", { title: "PI", apiUrl: process.env.API_URL });
  },
});

Add router

./app/src/routes/app.router.ts

export default () => {
  const router = new Router();

  const { pi } = appController();

  router.get("/pi", pi);

  return router;
};

Summary

In this section, we created a resource server with PI number as a restricted resource. Then we integrated this with our authorization server to grant user access. To see the result we created a minimal web app to view everything in action.

Part II: Persisting OpenID Server Data on MongoDB with Node.js

Ebrahim Hoseiny Fadae — Thu, 10 Mar 2022 12:41:08 +0000

Introduction

In this article, we'll explore how to integrate MongoDB with an OIDC (OpenID Connect 1.0) authentication server. We'll be using the panava/node-oidc-provider library for implementing the OIDC server and the Mongoose for connecting to MongoDB.

Let's start

Assuming you have followed the previous articles, you only need to add the necessary database dependencies.

$ yarn add mongoose@6.0.5 -T

Connect to MongoDB

For connecting to the MongoDB instance we only need to call connect from the mongoose library.

./oidc/src/db/mongodb/connection.ts

import mongoose from "mongoose";

export default async () => {
  const URI = process.env.MONGODB_URI ?? "";
  try {
    return await mongoose.connect(URI, {});
  } catch (error) {
    console.error(error);
  }
};

Add Base model

Now that we have our database connected, we need to design our models to store the data. The first option that comes to mind is that we create a model for every entity that we have (.e.g AccessToken, Session, AuthorizationCode, .etc).
But we are not doing this because of the reasons, I will mention:

You don't want to search every collection for an entity. (Most of the time you have an id and don't know where it belongs)
Global constraints are harder to implement (.e.g grantId must be unique across every authentication flow).
Repetitive logic (Handle expiration for every collection)
Engaging with the logic that you will barely use directly. (Actually, oidc uses the detail not you)
The oidc library eases the process and it gives us a payload object and wants a payload object back. The oidc mention these entities as model.

We will create an object which holds our payload and we call it BaseModel.

./oidc/src/db/mongodb/models/BaseModel.ts

import mongoose, { Schema } from "mongoose";

const BaseModelSchema = new Schema({
  key: { type: String, required: true },
  payload: { type: Object, required: true },
  expiresAt: { type: Date, required: true },
});

/**
 * key must be unique for every model
 */
BaseModelSchema.index(
  { key: 1, "payload.kind": 1 },
  {
    unique: true,
  }
);

/**
 * uid must be unique for every model == Session
 */
BaseModelSchema.index(
  { "payload.uid": 1 },
  {
    unique: true,
    partialFilterExpression: { "payload.kind": "Session" },
  }
);

/**
 * grantId must be unique for every authentication request model
 */
BaseModelSchema.index(
  { "payload.grantId": 1 },
  {
    unique: true,
    partialFilterExpression: {
      "payload.kind": {
        $in: [
          "AccessToken",
          "AuthorizationCode",
          "RefreshToken",
          "DeviceCode",
          "BackchannelAuthenticationRequest",
        ],
      },
    },
  }
);

/**
 * userCode must be unique for every model == DeviceCode
 */
BaseModelSchema.index(
  { "payload.userCode": 1 },
  {
    unique: true,
    partialFilterExpression: { "payload.kind": "DeviceCode" },
  }
);

/**
 * says that document must be removed on expiresAt with 0 delay (expireAfterSeconds: 0)
 */
BaseModelSchema.index(
  { expiresAt: 1 },
  {
    expireAfterSeconds: 0,
  }
);

export const BaseModel = mongoose.model("BaseModel", BaseModelSchema);

Write an adapter

Now we must tell oidc to use our BaseModel, but how?

Since panva/node-oidc-provider doesn't have an interface to derive it and implement our adapter (It's written in pure JS); we must provide required methods through an object or a class. To do this we use adapters/memory_adapter.js as a reference class and implement our adapter logic.

./oidc/src/adapters/mongodb.ts

import { BaseModel } from "../db/mongodb/models/BaseModel";

export class MongoDbAdapter {
  model: string;

  /**
   *
   * Creates an instance of MongoDbAdapter for an oidc-provider model.
   *
   * @constructor
   * @param {string} name Name of the oidc-provider model. One of "Grant, "Session", "AccessToken",
   * "AuthorizationCode", "RefreshToken", "ClientCredentials", "Client", "InitialAccessToken",
   * "RegistrationAccessToken", "DeviceCode", "Interaction", "ReplayDetection",
   * "BackchannelAuthenticationRequest", or "PushedAuthorizationRequest"
   *
   */
  constructor(name: string) {
    this.model = name;
  }

  /**
   *
   * Update or Create an instance of an oidc-provider model.
   *
   * @return {Promise} Promise fulfilled when the operation succeeded. Rejected with error when
   * encountered.
   * @param {string} id Identifier that oidc-provider will use to reference this model instance for
   * future operations.
   * @param {object} payload Object with all properties intended for storage.
   * @param {number} expiresIn Number of seconds intended for this model to be stored.
   *
   */
  async upsert(id: string, payload: any, expiresIn: number): Promise<any> {
    return await BaseModel.updateOne(
      {
        key: id,
      },
      { payload, expiresAt: new Date(Date.now() + expiresIn * 1000) },
      { upsert: true }
    );
  }

  /**
   *
   * Return previously stored instance of an oidc-provider model.
   *
   * @return {Promise} Promise fulfilled with what was previously stored for the id (when found and
   * not dropped yet due to expiration) or falsy value when not found anymore. Rejected with error
   * when encountered.
   * @param {string} id Identifier of oidc-provider model
   *
   */
  async find(id: string): Promise<any> {
    const doc: any = await BaseModel.findOne({
      key: id,
      "payload.kind": this.model,
    });
    return doc?.payload;
  }

  /**
   *
   * Return previously stored instance of DeviceCode by the end-user entered user code. You only
   * need this method for the deviceFlow feature
   *
   * @return {Promise} Promise fulfilled with the stored device code object (when found and not
   * dropped yet due to expiration) or falsy value when not found anymore. Rejected with error
   * when encountered.
   * @param {string} userCode the user_code value associated with a DeviceCode instance
   *
   */
  async findByUserCode(userCode: string): Promise<any> {
    const doc: any = await BaseModel.findOne({
      "payload.kind": "DeviceCode",
      "payload.userCode": userCode,
    });
    return doc?.payload;
  }

  /**
   *
   * Return previously stored instance of Session by its uid reference property.
   *
   * @return {Promise} Promise fulfilled with the stored session object (when found and not
   * dropped yet due to expiration) or falsy value when not found anymore. Rejected with error
   * when encountered.
   * @param {string} uid the uid value associated with a Session instance
   *
   */
  async findByUid(uid: string): Promise<any> {
    const doc: any = await BaseModel.findOne({
      "payload.kind": "Session",
      "payload.uid": uid,
    });
    return doc?.payload;
  }

  /**
   *
   * Mark a stored oidc-provider model as consumed (not yet expired though!). Future finds for this
   * id should be fulfilled with an object containing additional property named "consumed" with a
   * truthy value (timestamp, date, boolean, etc).
   *
   * @return {Promise} Promise fulfilled when the operation succeeded. Rejected with error when
   * encountered.
   * @param {string} id Identifier of oidc-provider model
   *
   */
  async consume(id: string): Promise<any> {
    return BaseModel.updateOne(
      {
        key: id,
        "payload.kind": this.model,
      },
      { consumed: Date.now() / 1000 }
    );
  }

  /**
   *
   * Destroy/Drop/Remove a stored oidc-provider model. Future finds for this id should be fulfilled
   * with falsy values.
   *
   * @return {Promise} Promise fulfilled when the operation succeeded. Rejected with error when
   * encountered.
   * @param {string} id Identifier of oidc-provider model
   *
   */
  async destroy(id: string): Promise<any> {
    return BaseModel.deleteOne({
      key: id,
      "payload.kind": this.model,
    });
  }

  /**
   *
   * Destroy/Drop/Remove a stored oidc-provider model by its grantId property reference. Future
   * finds for all tokens having this grantId value should be fulfilled with falsy values.
   *
   * @return {Promise} Promise fulfilled when the operation succeeded. Rejected with error when
   * encountered.
   * @param {string} grantId the grantId value associated with a this model's instance
   *
   */
  async revokeByGrantId(grantId: string): Promise<any> {
    return BaseModel.deleteMany({
      "payload.grantId": grantId,
    });
  }
}

Add adapter to configs

This is a simplified config object. You have to add the adapter to your full configuration object.

./oidc/src/configs/configuration.ts

import { MongoDbAdapter } from "../adapters/mongodb";

export const configuration: Configuration = {
  adapter: MongoDbAdapter,
};

Get into details

Up to this point we implemented our persistent OpenID server, but we never mentioned our most important entity.

Where is user account?

OpenID Connect protocol doesn't say anything about how you should store your user account or how must registration flow be; These are all up to you. And here is were we are diving into details. Here is where model properties are directly used in our system.

Add user account

First we will create a very simple user account model. For simplification i didn't used any security approach for storing password. It's just a plain text.

./oidc/src/db/mongodb/models/Account.ts

import mongoose, { Schema } from "mongoose";

const AccountSchema = new Schema({
  username: {
    type: String,
    unique: true,
  },
  password: String,
  email: {
    type: String,
    unique: true,
  },
  emailVerified: {
    type: Boolean,
    default: false,
  },
});

export const Account = mongoose.model("Account", AccountSchema);

Update findAccount() in configuration

./oidc/src/configs/configuration.ts

  async findAccount(ctx, id) {
    const account = await accountService.get(id);
    return (
      account && {
        accountId: id,
        async claims(use /* id_token, userinfo */, scope, claims) {
          if (!scope) return undefined;
          const openid = { sub: id };
          const email = {
            email: account.email,
            email_verified: account.emailVerified,
          };
          return {
            ...(scope.includes("openid") && openid),
            ...(scope.includes("email") && email),
          };
        },
      }
    );
  },

Add user repository service

Replace this file everywhere that we used account.service.ts.

./oidc/src/services/account-persistent.service.ts

import { Account } from "../db/models/Account";

export const get = async (key: string) => Account.findOne({ username: key });
export const set = async (key: string, value: any) => Account.insertOne({ username: key }, { ...value });

Add register controller

Append this to auth controller.

./oidc/src/controllers/auth.controller.ts

  async function register(ctx) {
    const body = ctx.request.body;
    if(await accountService.get(body.username)) ctx.throw(400); 
    await accountService.set(body.username, {
      username: body.username,
      password: body.password,
    });
    ctx.message = "User successfully created.";
  },

And this to auth router.

router.post("/users", bodyParser, register);

Probably we don't want to let everybody register a user in our system. For protecting against that we must use client credential authentication. We will do this in later tutorials.

Add register page to the app

After implementing back-end logic we must update our app server to handle registration.

./app/src/controllers/app.controller.ts

import { Middleware } from "koa";

export default (): { [key: string]: Middleware } => ({
  registerForm: async (ctx) => {
    return ctx.render("register", {
      title: "Register User",
      authServerUrl: process.env.AUTH_ISSUER,
    });
  },
});

Add router

./app/src/routes/app.router.ts

export default () => {
  const router = new Router();

  const { registerForm } = appController();

  router.get("/register", registerForm);

  return router;
};

Add register page

./app/src/views/register.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body class="app">
    <div class="login-card">
      <h1><%= title %></h1>
      <form
        autocomplete="off"
        action="<%= authServerUrl %>/users"
        method="post"
      >
        <label>Username</label>
        <input required type="text" name="username" placeholder="username" />
        <label>Password</label>
        <input
          required
          type="password"
          name="password"
          placeholder="and password"
        />

        <button type="submit" class="login login-submit">Register</button>
      </form>
    </div>
  </body>
</html>

What data we are sending?

username
password

Summary

In this part, we learned how to persist our data in an OpenID server. We saw that we have to implement user registration by ourselves which is both a good and a bad thing. Good because of the flexibility and bad because of the design mistakes we probably make. In the next part, we will create a resource server to try out our authorization server.

Part I: Developing Simple OpenID Authorization Server with Node.js & Typescript

Ebrahim Hoseiny Fadae — Fri, 18 Feb 2022 15:58:35 +0000

Introduction

In this tutorial, we will explore how to build an authorization server using the panava/node-oidc-provider library, which is built on top of the koajs/koa framework. This library simplifies the implementation of an authorization server while providing customization options based on our requirements.

Source Code

Completed source code on ebrahimmfadae/openid-connect-app

Let's start

The project has the following directory structure.

openid-connect-app/
  public/
  app/
    src/
      controllers/
      routes/
      views/
  oidc/
    src/
      adapters/
      configs/
      controllers/
      db/
      middlewares/
      routes/
      services/
      views/

Config npm

To begin, navigate to your project directory and run the following command in the terminal.

:~/openid-connect-app$ npm init -y

Make sure that a package.json file is created in the project folder.

For simplicity we will use $ instead of :~/openid-connect-app$ through the rest of the tutorial.

Config Typescript

Next, install the required TypeScript dependencies by running the following commands.

$ yarn add typescript@4.3.5 ts-node@10.2.0 -T
$ yarn add @types/node@16.4.14 -DT

Create a tsconfig.json file with this content.

{
  "compilerOptions": {
    "target": "es2020",
    "module": "commonjs",
    "allowJs": true,
    "strict": true,
    "noImplicitAny": false,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Add npm scripts

We can run scripts with npm run or yarn run command.

{
  "start:oidc": "ts-node oidc/src",
  "start:app": "ts-node app/src"
}

Environment Variables

Various environment variables are required for the server. Please refer to the docker-compose.yml file in the GitHub repository for a complete list.

Add authorization server dependencies

Install the necessary dependencies for the authorization server by running the following commands.

$ yarn add oidc-provider@7.12.0 koa@2.13.1 -T
$ yarn add @types/oidc-provider@7.6.0 @types/koa@2.13.4 -DT

Create OIDC Provider

./oidc/src/configs/provider.ts

import { Provider, Configuration } from "oidc-provider";

export const oidc = (issuer: string, configuration: Configuration) => {
  return new Provider(issuer, configuration);
};

The Provider class encapsulates every functionality that we need for implementing an authorization server. It takes two arguments. First is an issuer and the second is configuration object.

The issuer is the the base URL of the authorization server which in our case is http://localhost:3000. Once we deployed our source code to the production server we must change it to the server's public address. The issuer will be used at different places, So it's important that we provide a correct value.

OIDC configuration file

./oidc/src/configs/configuration.ts

import { Configuration } from "oidc-provider";

export const configuration: Configuration = {
  async findAccount(_, id) {
    return {
      accountId: id,
      async claims(_, scope) {
        return { sub: id };
      },
    };
  },
  clients: [
    {
      client_id: "app",
      client_secret: "scorpion",
      redirect_uris: ["http://localhost:3005/cb"],
      grant_types: ["authorization_code"],
      scope: "openid",
    },
  ],
  pkce: { required: () => false, methods: ["S256"] },
};

The simplest way we could config our oidc server is to add one single client and a way to tell Provider how it can find an account. We simplify it more by mocking the account fetching operation and returning an account with a passed id regardless of its value.

The redirect_uris holds the addresses that the client can redirect to. It must be a public address. http://localhost:3005 is the public address of our app.

The pkce is a mechanism for improving token exchange security but requires more effort to implement. I will say how to use it in a separate tutorial.

OIDC server index

./oidc/src/index.ts

import Koa from "koa";
import mount from "koa-mount";
import render from "koa-ejs";
import koaStatic from "koa-static";
import { oidc } from "./configs/provider";
import { configuration } from "./configs/configuration";

const provider = oidc(process.env.OIDC_ISSUER as string, configuration);

const start = async () => {
  const app = new Koa();
  render(app, {
    cache: false,
    viewExt: "ejs",
    layout: false,
    root: path.resolve("oidc/src/views"),
  });
  const provider = oidc(process.env.OIDC_ISSUER as string, configuration);
  app.use(koaStatic(path.resolve("public")));
  app.use(mount(provider.app));
  app.listen(process.env.PORT, () =>
    console.log(`oidc-provider listening on port ${process.env.PORT}`);
  );
};

void start();

First we will create a Koa instance and a Provider. Actually provider.app is a complete koa application on its own, But things are more manageable if we plug it into our own koa app. In order to do this we going to use koa-mount.

By running this command you can start authorization server.

$ yarn run start:oidc

OIDC client

We need a frontend client to interact with authorization server. For this purpose we are going to use koa and EJS in combination. mde/ejs is a template engine. It gives us the ability to write HTML files with more flexibility.

Our HTML pages are all using public/main.css as main style. You can find it in GitHub repository (Here).

There is a HTML part that is repeated in almost every file and we are going to use a feature of EJS to reduce the boilerplate. We will separate that piece and then include it wherever needed.

./app/views/components/head.ejs

<head>
  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
  <meta charset="utf-8" />
  <meta
    name="viewport"
    content="width=device-width, initial-scale=1, shrink-to-fit=no"
  />
  <title><%= title %></title>
  <link href="/main.css" rel="stylesheet" type="text/css" />
</head>

Every time you see:

<%- include('components/head'); -%>

That's the MAGIC!

Add dependencies

$ yarn add koa-ejs@4.3.0 koa-static@5.0.0 -T
$ yarn add @types/koa-ejs@4.2.4 @types/koa-static@4.0.2 -DT

Login Page

If you haven't logged in already, you will first be redirected to login screen and it asks you to enter your credentials and then you will be redirected to consent page. For now every username and password is valid; Because we mocked user fetching. Later in the series we will replace this part with real user authentication.

Add login page

./oidc/src/views/login.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body>
    <div class="login-card">
      <h1><%= title %></h1>
      <form
        autocomplete="off"
        action="/interaction/<%= uid %>/login"
        method="post"
      >
        <label>Username</label>
        <input
          required
          type="text"
          name="username"
          placeholder="Enter any login"
          value="sample"
        />
        <label>Password</label>
        <input
          required
          type="password"
          name="password"
          placeholder="and password"
          value="pass"
        />

        <button type="submit" class="login login-submit">Sign-in</button>
      </form>
      <div class="login-help">
        <a href="/interaction/<%= uid %>/abort">[ Cancel ]</a>
      </div>
    </div>
    <%- include('components/footer'); -%>
  </body>
</html>

What data we are sending?

username
password

Add consent page

consent is the final step of authorization when you will hit the authorize button in order to give grant to a client for issuing refresh token for your user.

./oidc/src/views/consent.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body>
    <div class="login-card">
      <h1><%= title %></h1>
      <form
        autocomplete="off"
        action="/interaction/<%= uid %>/confirm"
        method="post"
      >
        <p>
          Do you allow <strong><%= clientId %></strong> to access your account
          information? (<strong><%= scope %></strong>)
        </p>
        <button type="submit" class="login login-submit">Authorize</button>
      </form>
    </div>
    <%- include('components/footer'); -%>
  </body>
</html>

Add auth controllers

./oidc/src/controllers/auth.controller.ts

import { Middleware } from "koa";
import { Provider } from "oidc-provider";
import * as accountService from "../services/account.service";

function debug(obj: any) {
  return Object.entries(obj)
    .map(
      (ent: [string, any]) =>
        `<strong>${ent[0]}</strong>: ${JSON.stringify(ent[1])}`
    )
    .join("<br>");
}

export default (oidc: Provider): { [key: string]: Middleware } => ({
  interaction: async (ctx) => {}, // 1 (See below)
  login: async (ctx) => {}, // 2 (See below)
  abortInteraction: async (ctx) => {}, // 3 (See below)
  confirmInteraction: async (ctx) => {}, // 4 (See below)
});

When a user requests for authorization it will be redirected to /interaction route with some specific information. interaction controller captures these information to login user or ask it for consent.

// 1
async function interaction(ctx) {
  const { uid, prompt, params, session } = (await oidc.interactionDetails(
    ctx.req,
    ctx.res
  )) as any;

  if (prompt.name === "login") {
    return ctx.render("login", {
      uid,
      details: prompt.details,
      params,
      session: session ? debug(session) : undefined,
      title: "Sign-In",
      dbg: {
        params: debug(params),
        prompt: debug(prompt),
      },
    });
  } else if (prompt.name === "consent") {
    return ctx.render("consent", {
      uid,
      title: "Authorize",
      clientId: params.client_id,
      scope: params.scope.replace(/ /g, ", "),
      session: session ? debug(session) : undefined,
      dbg: {
        params: debug(params),
        prompt: debug(prompt),
      },
    });
  } else {
    ctx.throw(501, "Not implemented.");
  }
}

On the login page user will send its login credentials to /login route. login controller will handle the request. If credentials are valid user will be redirected to consent page.

// 2
async function login(ctx) {
  const {
    prompt: { name },
  } = await oidc.interactionDetails(ctx.req, ctx.res);
  if (name === "login") {
    const account = await accountService.get(ctx.request.body.username);
    let result: any;
    if (account?.password === ctx.request.body.password) {
      result = {
        login: {
          accountId: ctx.request.body.username,
        },
      };
    } else {
      result = {
        error: "access_denied",
        error_description: "Username or password is incorrect.",
      };
    }
    return oidc.interactionFinished(ctx.req, ctx.res, result, {
      mergeWithLastSubmission: false,
    });
  }
}

If user hits the cancel button on grant page, This endpoint will be called.

// 3
async function abortInteraction(ctx) {
  const result = {
    error: "access_denied",
    error_description: "End-User aborted interaction",
  };
  await oidc.interactionFinished(ctx.req, ctx.res, result, {
    mergeWithLastSubmission: false,
  });
}

If the user hit authorize button on grant page, This controller will be called.

// 4
async function confirmInteraction (ctx) {
    const interactionDetails = await oidc.interactionDetails(ctx.req, ctx.res);
    const {
      prompt: { name, details },
      params,
      session: { accountId },
    } = interactionDetails as any;

    if (name === "consent") {
      const grant = interactionDetails.grantId
        ? await oidc.Grant.find(interactionDetails.grantId)
        : new oidc.Grant({
            accountId,
            clientId: params.client_id as string,
          });

      if (grant) {
        if (details.missingOIDCScope) {
          grant.addOIDCScope(details.missingOIDCScope.join(" "));
        }
        if (details.missingOIDCClaims) {
          grant.addOIDCClaims(details.missingOIDCClaims);
        }
        if (details.missingResourceScopes) {
          for (const [indicator, scopes] of Object.entries(
            details.missingResourceScopes
          )) {
            grant.addResourceScope(indicator, (scopes as any).join(" "));
          }
        }

        const grantId = await grant.save();

        const result = { consent: { grantId } };
        await oidc.interactionFinished(ctx.req, ctx.res, result, {
          mergeWithLastSubmission: true,
        });
      }
    } else {
      ctx.throw(400, "Interaction prompt type must be `consent`.");
    }
  },

Add auth router

./oidc/src/routes/auth.router.ts

import koaBody from "koa-body";
import Router from "koa-router";
import { Provider } from "oidc-provider";
import authController from "../controllers/auth.controller";
import { authenticate } from "../middlewares/auth.middleware";
import { noCache } from "../middlewares/no-cache.middleware";

const bodyParser = koaBody();

export default (oidc: Provider) => {
  const router = new Router();

  const { abortInteraction, confirmInteraction, interaction, login } =
    authController(oidc);

  router.post("/interaction/:uid/login", noCache, bodyParser, login);
  router.post("/interaction/:uid/confirm", noCache, confirmInteraction);
  router.get("/interaction/:uid/abort", noCache, abortInteraction);
  router.get("/interaction/:uid", noCache, interaction);

  return router;
};

Update configs

./oidc/src/configs/configuration.ts

export const configuration: Configuration = {
  // ...
  features: {
    devInteractions: { enabled: false },
  },
};

Add user claims

Here we defined scope and claims in configuration object.

./oidc/src/configs/configuration.ts

import * as accountService from "../services/account.service";

export const configuration: Configuration = {
  async findAccount(ctx, id) {
    const account = { emailVerified: true, email: "ebrahimmfadae@gmail.com" };
    return (
      account && {
        accountId: id,
        async claims(_, scope) {
          if (!scope) return undefined;
          const openid = { sub: id };
          const email = {
            email: account.email,
            email_verified: account.emailVerified,
          };
          const accountInfo = {};
          if (scope.includes("openid")) Object.assign(accountInfo, openid);
          if (scope.includes("email")) Object.assign(accountInfo, email);
          return accountInfo;
        },
      }
    );
  },
  clients: [
    {
      client_id: "app",
      client_secret: "scorpion",
      redirect_uris: ["http://localhost:3005/cb"],
      grant_types: ["authorization_code"],
      scope: "openid email profile phone address offline_access",
    },
  ],
  claims: {
    address: ["address"],
    email: ["email", "email_verified"],
    phone: ["phone_number", "phone_number_verified"],
    profile: [
      "birthdate",
      "family_name",
      "gender",
      "given_name",
      "locale",
      "middle_name",
      "name",
      "nickname",
      "picture",
      "preferred_username",
      "profile",
      "updated_at",
      "website",
      "zoneinfo",
    ],
  },
};

Frontend startup script

In order for server to be able to read static resources like public/main.css we need to use koa-static.

./app/index.ts

import Koa from "koa";
import render from "koa-ejs";
import koaStatic from "koa-static";
import path from "path";
import routes from "./routes";

const app = new Koa();
render(app, {
  cache: false,
  viewExt: "ejs",
  layout: false,
  root: path.resolve("app/src/views"),
});

app.use(koaStatic(path.resolve("public")));
app.use(routes().routes());

app.listen(process.env.PORT, () =>
  console.log(`sample-app listening on port ${process.env.PORT}`)
);

You run front-end server with this command.

$ yarn run start:app

Design main page

All pages will have a simple html structure; So main page is just a form with some essential inputs. This page is our sample-app.

./app/src/views/sample-app.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body class="app">
    <div class="login-card">
      <h1><%= title %></h1>
      <form action="<%= authServerUrl %>/auth" method="post">
        <label>Client Id</label>
        <input required name="client_id" value="<%= clientId %>" />
        <label>Response Type</label>
        <input required name="response_type" value="code" />
        <label>Redirect URI</label>
        <input required name="redirect_uri" value="<%= appUrl %>/cb" />
        <label>Scope</label>
        <input required name="scope" value="openid" />

        <button type="submit" class="login login-submit">Grant Access</button>
      </form>
    </div>
  </body>
</html>

What data we are sending?

client_id of our app in authorization server.
response_type, Which here is code because we want a code for completing authorization_code flow.
redirect_uri is the address that auth server will navigate us to after completing the grant request (whether on success or fail). And because we want to navigate back to app we set this to appUrl.
scope, The scopes that the user will be granted to access.

App router

Here we config our server routes. Currently there is no route except index.

./app/routes/app.router.ts

import Router from "koa-router";
import appController from "../controllers/app.controller";

export default () => {
  const router = new Router();
  const { sampleApp } = appController();
  router.get("/", sampleApp);
  return router;
};

./app/routes/index.ts

import Router from "koa-router";
import appRouter from "../routes/app.router";

export default () => {
  const router = new Router();
  router.use(appRouter().routes());
  return router;
};

Load sample-app page

EJS is just a template engine. It can't serve itself. We must add a controller to koa to make it do this for us.

./app/controllers/app.controller.ts

import { Middleware } from "koa";

export default (): { [key: string]: Middleware } => ({
  sampleApp: async (ctx) => {
    return ctx.render("sample-app", {
      title: "Sample App",
      authServerUrl: process.env.PUBLIC_OIDC_ISSUER,
      appUrl: process.env.PUBLIC_APP_URL,
      clientId: "app",
    });
  },
});

Issue Token

Now that we have implemented our authorization server and our app we are going to add ability to issue a token for granted user. All we have done is tended to reach this step.

Add issue token page

./app/src/views/token.ejs

<!DOCTYPE html>
<html>
  <%- include('components/head'); -%>
  <body class="app">
    <div class="login-card">
      <h1><%= title %></h1>
      <form
        autocomplete="off"
        action="<%= authServerUrl %>/token"
        method="post"
      >
        <label>Client Id</label>
        <input required name="client_id" value="<%= clientId %>" />
        <label>Client Secret</label>
        <input required name="client_secret" value="<%= clientSecret %>" />
        <label>Grant Type</label>
        <input required name="grant_type" value="authorization_code" />
        <label>Code</label>
        <input required name="code" value="<%= code %>" />
        <label>Redirect URI</label>
        <input required name="redirect_uri" value="<%= appUrl %>/cb" />
        <label>Scope</label>
        <input required name="scope" value="openid" />

        <button type="submit" class="login login-submit">Issue Token</button>
      </form>
    </div>
  </body>
</html>

What new data we are sending?

client_secret of our app in authorization server.
grant_type, Which here is authorization_code.
code that we received on authorization step.

Add app controller

Authorization server redirects user to callback address with error or success statuses. If user approve access a code is passed to callback route as query param. Otherwise if user rejects grant request, an error parameter is passed to query. According to these parameters we complete authorization flow.

Here for sake of learning we designed a form to manually get a token. In a real life scenario you probably want to automatically request issue token and then redirect to the desired app page.

./app/src/controllers/app.controller.ts

export default (): { [key: string]: Middleware } => ({
  callback: async (ctx) => {
    if ("error" in ctx.query) {
      ctx.throw(401, `${ctx.query.error}: ${ctx.query.error_description}`);
    } else {
      return ctx.render("token", {
        code: ctx.query.code,
        title: "App Callback",
        authServerUrl: process.env.PUBLIC_OIDC_ISSUER,
        appUrl: process.env.PUBLIC_APP_URL,
        clientId: process.env.CLIENT_ID,
        clientSecret: process.env.CLIENT_SECRET,
      });
    }
  },
});

Add app router

./app/src/routes/app.router.ts

export default () => {
  const router = new Router();

  const { callback } = appController();

  router.get("/cb", callback);

  return router;
};

Run all

Use this command to run all services. Then visit http://localhost:3000 and follow the authentication flow.

$ yarn compose:up oidc app api

Summary

We have implemented an authorization server and an app to communicate with it. We have no user registration, but don't worry we will add it in when we implemented MongoDB as persistent database.

Series: Implementing OpenID with Node.js, TypeScript, and MongoDB - A Step-by-Step Guide

Ebrahim Hoseiny Fadae — Thu, 17 Feb 2022 17:38:21 +0000

Introduction

In this tutorial series, we will explore how to implement OpenID with Node.js, TypeScript, and MongoDB. The focus of this guide is to provide a comprehensive, step-by-step approach to building an OIDC (OpenID Connect 1.0) authorization server along with a web application and an API service. Through this tutorial we are going to use panava/node-oidc-provider library, which is an OpenID Certified™ OAuth 2.0 Authorization Server implementation for Node.js.

Source Code

You can find the complete source code for this tutorial series at ebrahimmfadae/openid-connect-app on GitHub.

Requirements

To follow along with this tutorial series, you should have a good understanding of JavaScript and be familiar with the concepts of OpenID or OAuth 2.0. Additionally, basic knowledge of CSS, HTML, TypeScript, and Docker will be beneficial.

Setup

Before getting started, ensure that you have the following versions installed:

$ node -v
v18.17.1

$ yarn -v
v3.6.3

$ docker --version
Docker version 20.10.7, build f0df350

$ docker-compose --version
Docker Compose version v2.15.1

Goals

Create an authorization server based on OpenID protocol.
Create an web application that acts as a client for authorization server.
Create an API (resource server) to demonstrate accessing restricted resources by authenticated users.

USAGE WARNING!

Please note that the code provided in this tutorial series should not be used in production without ensuring proper security measures and suitability for your specific use case.

Ask for help or give feedback

If you need any assistance or have feedback to share, you can reach out to me through the following channels:

UPDATE #1 - 8 October 2022

Please note that the panava/node-oidc-provider repository has disabled its issue section, which raises concerns about the project's maintenance. Additionally, critical bugs have been observed that require delving into the source code for resolution. While the repository may still serve the purpose of learning the OIDC protocol, caution is advised when using it.