Skip to main content

4 posts tagged with "engineering"

View All Tags

· 8 min read
Aswin V

We have already covered SAML at a high level from both user and application provider points of view.

In this post, we'll dive into the technicalities of SAML, OAuth 2.0 and OpenID Connect and how these come together to serve as building blocks for Jackson SSO.


SAML was designed for traditional web applications in the early 2000s. The goal was to provide a seamless user experience for applications by federating authentication to an IdP. As a result, applications no longer had to maintain identities for users. All they had to do was to redirect the browser to the IdP which would then authenticate the user and return an assertion about the logged-in user. This assertion in effect was a token, asserting to the app that the user authenticated at the IdP and the assertion is valid for the set period contained within it.

While SAML gave us a solution to the problem of SSO or federated identity, it does not address the issue of authorization.

The need for authorization arose with the dawn of Single Page Apps (SPA) and native platforms such as mobile. More and more logic started moving from backend to frontend and an ecosystem of apps that could talk to one another (via HTTP(S)) sprung up. For eg:- You could reserve movie tickets and send invitations to your Facebook friends. This meant that applications started acting on behalf of the end-user, requesting data (friend list) from other services (Facebook). One way we could solve it was by sharing our credentials (for services) with the app. Nothing could be more dangerous than this, because now the application can virtually do anything the user could do. This paved the path for standards like OAuth that provides us with a mechanism to grant controlled and limited access to resources on behalf of the user.

OAuth 2.0

The OAuth 2.0 Authorization framework enables a third-party application/client to obtain limited access to an HTTP service on behalf of the resource owner (or user). In the final step of this process, the client receives a short-lived access token that can be used to access the protected resources.

The flow starts with the app redirecting the user agent to an intermediary Authorization server (AS). The AS authenticates the user and obtains permission from the user to access resources. Once that's done, AS redirects back to the client with an Authorization code. The Authorization code is a grant or a credential representing the user's authorization to be used by the client. In the final step, the client uses this code to obtain an access token. This flow otherwise called Authorization Code grant is one of 4 grant types that are supported. For sake of simplicity, we can omit the others for now.

The above-mentioned flow offers a few benefits:

  • The user only authenticates with the authorization server and the credentials are never shared with the app.
  • The access token is not transmitted* via the user agent but directly to the client via an HTTP request.
  • The Client can be authenticated by the authorization server by using a client secret.

* It's worth mentioning the fact that another grant type 'implicit grant' does return an access token via the user agent in the redirect URL fragment

Using OAuth 2.0 for authentication

Since authentication usually occurs before issuing the access token, it is usually assumed that possession of an access token is proof that authentication happened. The access token is then used to query the Identity API to obtain user details.

However, this does not fully serve as proof of authentication and has several pitfalls:

  • The access token is opaque to the client and its intended audience is the protected resource server.
  • There is no way to know if the user is still around because information about the authentication event is not exposed.
  • In situations where clients get an access token directly in the return URL (implicit grant), there is a high chance that an attacker can inject their malicious token. This can be mitigated by using the Authorization code flow as the token is retrieved from the token endpoint directly.
  • OAuth does not define a standard set of fields for the Identity API. For eg:- While one IdP could use user_id for the user identifier, the same could be subject in another one. This requires different handling on the client side from one IdP to another.

A new standard called 'OpenID Connect' which builds on top of OAuth 2.0 brings new artifacts like ID tokens that can serve as reliable proof of authentication and also standardizes things like scope and claims.

OpenID Connect (OIDC)

OpenID Connect 1.0 is a simple identity layer on top of the OAuth 2.0 protocol. It supports 3 flows of which Authorization code and implicit flow are similar to the ones defined in OAuth 2.0. The notable difference here is the return of an ID Token in JWT format (JSON Web Token). The claims in the ID Token help the client reliably confirm the identity of the user. The audience(aud) claim will be set to the client id which means the ID token is intended to be consumed by the client alone. Conforming to the OAuth 2.0 spec, an access token is still returned which can be used to obtain information about the user from the "userinfo" endpoint. OIDC also standardizes the claims in the ID Token as well as the "userinfo" response.

Assembling the SSO puzzle

Now that we have all the pieces of the SSO puzzle, bringing it together in Jackson would look something like the one below.

img alt

Allow me to explain.

We need to support two kinds of SSO Identity Providers - SAML and OIDC. For the sake of discussion, consider the scenario of two apps where one (CRM) needs to log in with Azure AD via SAML and another (HRM) needs to log in with Google Workspace via OIDC.

Setup SSO Connection

The preliminary step (marked by the green arrow above) is to add the SSO Connection to Jackson. For SAML IdP, this would mean saving the XML metadata from the IdP. The metadata would contain the SSO URL to send the SAML request to plus the public key to verify the SAML assertion signature. In the case of OIDC IdP, we need the discovery URL and client credentials (clientID and clientSecret of the registered app). The discovery URL can be used to query metadata about IdP such as authorization and token endpoints while the client credentials will be used to authenticate the Jackson client orchestrating the OIDC flow.

Login flow

Jackson supports both OAuth 2.0 as well OpenID flows. The OAuth 2.0 flow is made secure by supporting Authorization Code flow with PKCE. By including the scope openid in the client request Jackson will switch to OpenID flow.

The login process follows the below steps:

  1. The Client (Browser app) initiates the login by redirecting to Jackson's authorize endpoint. Jackson will parse the tenant/product in the request and use it to redirect the user to the configured IdP.
  2. Step 2 varies based on the Identity Provider type. For SAML IdP, Jackson would construct the SAML request, sign it and send it to IdP. The IdP validates the request and authenticates the user. For OIDC IdP, Jackson constructs an OpenID Connect request and redirects the user to the OIDC Provider authorization endpoint.
  3. Once the user is logged in successfully, the IdP redirects back to Jackson. For SAML, the response contains the user profile. In the case of OIDC, the response contains the authorization code that is used by Jackson to obtain the token and user profile from the OIDC IdP. Jackson generates a short-lived authorization code and stores the user profile against it.
  4. The authorization code generated in the previous step is sent to the client app.
  5. The client exchanges the code for the token and uses it to query the userInfo endpoint of Jackson to get the complete user profile. In the case of OpenID flow, ID Token is returned by Jackson and contains the basic user profile.

Final thoughts

So in a nutshell, Jackson acts as a proxy between the client app and the IdP doing the heavy lifting of orchestrating SAML/OIDC flows with the configured IdPs. This way you can quickly scale your app auth to any number of providers allowing you to focus on your core product.

· 4 min read
Kiran K

This article will walk you through everything you should know about SCIM and Directory Sync.

What is SCIM?

System for Cross-domain Identity Management (SCIM) is an open standard that allows for the automation of user provisioning (Directory Sync).

SCIM facilitates user identity data communication between Identity Providers (Okta, OneLogin, etc.) and Service Providers (Enterprise SaaS apps).

Why should you care about SCIM?

Many companies manually onboard and offboard users, which consumes many IT resources and time.

User lifecycle management (ULM) begins when employees start their job and continue until they leave the company. ULM is all about provisioning and de-provisioning users when they join an organization.

For IT departments, this means creating an account for the new employees in the cloud apps they need to use after starting their job. Also, IT departments must ensure that when those employees leave, they revoke access to those accounts.

Smaller organizations might address these procedures manually, but the process can become error-prone and time-consuming when done at scale. This is where the SCIM and Directory Sync come to the organization's rescue.

What is Directory Sync?

Directory sync helps organizations automate the provisioning and de-provisioning of their users.

As a result, it streamlines the user lifecycle management process by saving valuable organizational hours, creating a single truth source of the user identity data, and facilitating them to keep the data secure.

How does the Directory Sync work?

Directory sync allows programmatic access to the user identity data via a standard protocol (SCIM).

Directory sync implementation typically involves a client and a server. A client is an identity provider (IDP) with a directory of user identities. A service provider (SP) is an enterprise SaaS app that needs a subset of data from those identities.

When you make changes to the user identities, the changes are automatically synced to the SP according to the SCIM protocol. SP can now process these data according to the way they want.

Some common user identity changes include adding new users to the organization, updating existing users, removing users from the organization, adding users to groups, etc.

Technically, SCIM is a set of APIs that allows you to manipulate the users and group objects and expose these data as JSON through the REST endpoints.

How to add Directory Sync to your SaaS app?

Building Directory sync implementation yourself can be tedious and time-consuming for any engineering team.

Below are some questions the engineering team should answer before starting building Directory sync.

  • How do we support multiple identity providers?
  • How much effort should the team put into support & maintenance?
  • Do we have developers with good knowledge of SCIM and its security?
  • Is it worth building the Directory sync ourselves?

In short, building Directory sync yourself is not a good idea. It requires a lot of tedious engineering work and ongoing maintenance.

The best alternative is an open-source dedicated Directory Sync implementation provider like SAML Jackson from BoxyHQ.

Directory Sync from BoxyHQ

BoxyHQ can help enterprises to add Directory Sync to any SaaS app with just a few lines of code.

Enterprise SaaS apps can provide a Webhook endpoint to SAML Jackson, and Jackson will notify the Webhook every time a change occurs in the user identity data within the IDP.


In short, Jackson hides all the complexities involved with Directory Sync implementation and makes your integration easier.

BoxyHQ's Directory Sync implementation supports identity providers such as Okta, OneLogin, Azure AD, and JumpCloud. We're looking forward to adding more identity providers in future releases.

Here are a few critical aspects that make BoxyHQ's Directory Sync implementation stand out.

  • An open-source solution.
  • Allows you to keep control of your data.
  • Support multiple identity providers.
  • Allows you to listen to six critical SCIM events.

Final Thoughts

Directory Sync is a valuable investment for every organization seeking efficiency and security in their user lifecycle management system.

If you are interested in becoming enterprise-ready without the hassle, then let's chat! You can book a free consultation call and talk with our CEO about how we can help. So let's start the journey together.

· 9 min read
Kiran K

In this article, you'll learn how add SAML SSO login to an Express.js app. You'll use SAML Jackson with Auth0 to authenticate users and protect routes.

You can also access the full code at the GitHub repository.

Let’s get started!


To follow along with this article, you’ll need the following:

  • Node.js installed on your computer
  • Basic knowledge about Node.js and Express.js

Setting up the database

For our article, we’ll create a free Postgres database on Heroku instead of setting up a local Postgres server.

  • Go to Heroku signup page, then create an account.
  • Go to Apps and click Create new app.
  • Give your app a name, and click the Create app button.
  • Go to the Resources tab.
  • Choose the Heroku Postgres from the Add-ons search box, and click Submit Order Form.
  • Click the Heroku Postgres and select Settings tab.
  • Click the View Credentials button and copy URI.

Now you have created a free PostgreSQL database and copied the database connection URI. We'll need the connection URI later.

Configure the Identity Provider

We'll use the Auth0 as our identity provider. An Identity Provider (IdP) is a service that manage user accounts for your app.

  • First, go to the Auth0 signup page, then create an account.
  • Go to Dashboard > Applications > Applications.
  • Click the Create Application button.
  • Give your new application a name.
  • Choose Regular Web Applications as an application type and the click Create.
  • Go to the app you created, then click the Addons tab.
  • In the SAML2 Web App box, click the slider to enable the Addon.
  • Go to the Usage tab and download the Identity Provider Metadata.
  • Go to the Settings tab and make below changes.
  • Add http://localhost:3000/sso/acs as your Application Callback URL that receives the SAML response.
  • Paste the following JSON for Settings, then click Enable button.
"audience": "",
"mappings": {
"id": "",
"email": "",
"firstName": "",
"lastName": ""

audience is just an identifier to validate the SAML audience. More info.

Auth0 provides database connections to authenticate users with an email/username and password. These credentials are securely stored in the Auth0 user store.

Let's create one so that our users can register or login.

Now we've everything ready, let's move to the next step.

Getting started

Launch a terminal and clone the GitHub repo:

git clone
cd express-saml

Now, install the dependencies:

npm install

Add the environment variables:

cp .env.example .env

Update the DATABASE_URL variable with your Heroku Postgres database connection URI.

Append ?sslmode=no-verify to your database connection URI otherwise Heroku won't allow you to link to the database. This is a Heroku specific configuration.

For example postgres://

About the Express app

This is a simple express.js app created using express-generator. You can use any express.js app if you want.

Our express.js app has only 2 routes.

  • GET / render a home page
  • GET /dashboard render a dashboard

So, what's the plan? We'll add SAML SSO login (via Auth0) to our express.js app so that only authenticated users can access the /dashboard.

Install SAML Jackson

Run the following command to install the latest version of the SAML Jackson.

npm i --save @boxyhq/saml-jackson

Once you installed Jackson, let's initialize it.

Add the following code to the routes/index.js.

// routes/index.js


let apiController;
let oauthController;

const jacksonOptions = {
externalUrl: process.env.APP_URL,
samlAudience: process.env.SAML_AUDIENCE,
samlPath: '/sso/acs',
db: {
engine: 'sql',
type: 'postgres',
url: process.env.DATABASE_URL,

(async function init() {
const jackson = await require('@boxyhq/saml-jackson').controllers(jacksonOptions);

apiController = jackson.apiController;
oauthController = jackson.oauthController;

Setting up Express.js routes

Add SAML Metadata

The first route you'll create is the GET /config one. This route will display a form with following fields:

  • Metadata: Enter the XML Metadata content you've downloaded from IdP.
  • Tenant: Jackson supports a multi-tenant architecture, this is a unique identifier you set from your side that relates back to your customer's tenant. This is normally an email, domain, an account id, or user-id.
  • Product: Jackson support multiple products, this is a unique identifier you set from your side that relates back to the product your customer is using.
// routes/index.js

router.get('/config', async (req, res) => {

Add a view to display the form.

<!-- views/config.ejs -->

<!DOCTYPE html>
<title>SAML Config</title>
<link rel="stylesheet" href="/stylesheets/style.css" />
<h1>SAML Config</h1>
<p>Add SAML Metadata.</p>
<form action="/config" method="POST">
<div class="form-group">
<label for="tenant">Tenant</label>
class="form-control col-md-6"
<div class="form-group">
<label for="product">Product</label>
class="form-control col-md-6"
<div class="form-group">
<label for="rawMetadata">Metadata (Raw XML)</label>
class="form-control col-md-6"
<button type="submit" class="btn btn-primary">Submit</button>

Now let's add another route POST /config that will store the form data by calling the SAML Jackson config API.

This step is the equivalent of setting an OAuth 2.0 app and generating a client ID and client secret that will be used in the login flow.

// routes/index.js'/config', async (req, res, next) => {
const { rawMetadata, tenant, product } = req.body;

const defaultRedirectUrl = 'http://localhost:3000/sso/callback';
const redirectUrl = '["http://localhost:3000/*"]';

try {
await apiController.config({

} catch (err) {

There are a few important things to note in the code above.

defaultRedirectUrl holds the redirect URL to use in the IdP login flow. Jackson will call this URL after completing an IdP login flow.

redirectUrl holds an array containing a list of allowed redirect URLs. Jackson will disallow any redirects that are not on this list.

Next, let's start the express app. The app starts a server and listens on port 3000 (by default) for connections.

npm start

Now, let's visit http://localhost:3000/config, you should see the page with a form.

SAML Config

Here you can add the metadata you've downloaded from Auth0. Fill out the form with a Tenant, Product, and paste the metadata XML content as it is.

I'll use '' for tenant and 'crm' for product.

The response returns a JSON with client_id and client_secret that can be stored against your tenant and product for a more secure OAuth 2.0 flow.

If you do not want to store the client_id and client_secret you can alternatively use client_id=tenant=<tenantID>&product=<productID> and any arbitrary value for client_secret when setting up the OAuth 2.0 flow.

Redirect the users to IdP

Now you have added the SAML metadata, you'll need a route to redirect the users to IdP to start the SAML authentication.

Let's add a new route GET /sso/authorize.

Don't forget to change the values of the tenant and product in the code.

// routes/index.js

router.get('/sso/authorize', async (req, res, next) => {
try {
const tenant = '';
const product = 'crm';

const body = {
response_type: 'code',
client_id: `tenant=${tenant}&product=${product}`,
redirect_uri: 'http://localhost:3000/sso/callback',
state: 'a-random-state-value',

const { redirect_url } = await oauthController.authorize(body);

} catch (err) {

oauthController.authorize() will returns a redirect_url. You should redirect the users to this redirect_url to start the IdP authentication flow.

Handle the SAML Response from IdP

This route becomes the Assertion Consumer Service (ACS) URL of your app. The ACS URL tells your IdP where to POST its SAML Response after authenticating a user.

The SAML Response contains 2 fields: SAMLResponse and RelayState.

// routes/index.js'/sso/acs', async (req, res, next) => {
try {
const { SAMLResponse, RelayState } = req.body;

const body = {

const { redirect_url } = await oauthController.samlResponse(body);

} catch (err) {

Call to the method oauthController.samlResponse() will returns a redirect_url. You should redirect the users to this redirect_url. The query parameters will include the code and state parameters.

Code exchange

Now exchange the code for a token. The token is required to access the user profile.

Let's create a new route GET /sso/callback to handle the callback.

// routes/index.js

router.get('/sso/callback', async (req, res, next) => {
const { code } = req.query;

const tenant = '';
const product = 'crm';

const body = {
client_id: `tenant=${tenant}&product=${product}`,
client_secret: 'client_secret',

try {
// Get the access token
const { access_token } = await oauthController.token(body);

// Get the user information
const profile = await oauthController.userInfo(access_token);

// Add the profile to the express session
req.session.profile = profile;

} catch (err) {

In the above code, replace the value for tenant and product with yours.

Protect the dashboard

Now is the time to fix our GET /dashboard route so that only authenticated users can access it.

Let's fix it by adding a condition to check if the profile exists in the session.

If profile is undefined, redirect the users back to the / otherwise display the profile on the dashboard.

Replace the GET /dashboard route with the below code.

// routes/index.js

router.get('/dashboard', function (req, res, next) {
const { profile } = req.session;

if (profile === undefined) {
return res.redirect('/');

// Pass the profile to the view
res.render('dashboard', {

Replace the views/dashboard.ejs view with the below code.

<!-- views/dashboard.ejs -->

<!DOCTYPE html>
<link rel="stylesheet" href="/stylesheets/style.css" />
<p>Only authenticated users should access this page.</p>

<p>Id - <%= %></p>
<p>Email - <%= %></p>

From the command line, let's restart the express app then visit the authorize the URL http://localhost:3000/sso/authorize.

If you've configured everything okay, it should redirect you to the Auth0 authentication page, then click on the Sign up link and register there

If the authentication is successful, the app will redirect you to the dashboard and display the id, email of the user.



Congratulations, you should now have a functioning SAML SSO integrated with your express.js app using the SAML Jackson and Auth0.


To learn more about SAML Jackson, take a look at the following resources:

Your feedback and contributions are welcome!

· 3 min read
Utkarsh Mehta

One of our products, Hermes is an audit logs service. Currently, Hermes is in the prototype phase and uses a Go REST API server to ingest audit logs and send them to Loki.

We were trying out different databases, ingesters & tools to see which are best suited for Hermes and should be able to scale with high traffic without losing a single audit log & which can search through high amount data efficiently.

Title Image

We decided to benchmark different combinations of ingesters (Vector, Fluentd, Fluent-Bit, etc.) and storage & query tools (Mongodb, Clickhouse, Elasticsearch, etc.).

The first round of benchmarks will be lightweight and extensive benchmarks will follow later once we pick the right tools for Hermes.

Hardware Configuration

The following tests and benchmarks have been performed on a MacBook Pro (14-inch, 2021) with Apple M1 Pro and 16 GB RAM, the tools to be tested were dockerized with docker desktop running with 4 GB Memory, 4 CPUs & 1 GB Swap.

Fluent Bit is a super-fast, lightweight, highly scalable logging and metrics processor and forwarder. It is the preferred choice for cloud and containerized environments. Source: fluent-bit website Clickhouse is the fastest OLAP database on earth. ClickHouse works 100–1000x faster than traditional approaches. Companies like Uber, Cloudflare, Spotify, and eBay use Clickhouse. Source: Clickhouse website

So few pointers before we go ahead,

  1. Fluent-bit is fast at ingesting logs/data, processing them, and sending them to a destination.

  2. Clickhouse is efficient at handling and querying data.

  3. Fluent-bit does not support Clickhouse by default.

  4. The fluent-bit ecosystem lets users write their plugins in Golang and add additional support required.

  5. For faster querying in Clickhouse, an efficient table schema with indexes, compression, etc. should be established.

Clickhouse plugin for fluent-bit

I developed a fluent-bit output plugin for Clickhouse.

Fluent-Bit config

Fluent-bit Configuration

This config makes fluent-bit ingest data via HTTP server listening on port 8888 and sends the data to Clickhouse with configuration stated.

Clickhouse config

I ramped up the number of concurrent requests/queries by modifying the config.xml. After multiple tests, I finalized the following config.

Clickhouse Configuration

Load testing tool

I developed a load testing tool with Node.js that can be used to benchmark REST API-based endpoints of Fluent-bit.

API Benchmarking

Another tool to load test is the querying part of Clickhouse.

Clickhouse Load Testing

The results

These results are dependent on the ram allocated to the Docker engine, in my case, it's(4 GiBs).


Ingester results


Queryer result



  1. Fluent-bit can handle loads up to 2000 req/sec but in the case of bigger batches, the speed goes down drastically. (200 X 10) & (300 X 10)

  2. In the case of long-term light batches, Fluent-bit performs consistently. (10 X 1000)

  3. Fluent-bit performs at average speeds in the case of average loads (50 X 50).


  1. Clickhouse shows the best req/sec performance with an average load (50 X 50).

  2. Also, Clickhouse's performance was pretty satisfactory for all the different variations of records in DB. (1.1 mils, 50k, 25k, 10k, 2k & 1k).

  3. Clickhouse was able to manage short-term high loads and long-term light loads efficiently. (100 X 10) and (10 X 5000).

We will be posting more blogs regarding benchmarks, tools, etc., as we go on to build Hermes and many other dev tools. Please leave comments below.

Thank you!