iam

Identity and access management abstraction for applications.

Getting started:

This package is an Identity and Access Management abstraction built on top of Keycloak.

It provides a simplified interface for handling authentication and authorization in both backend and frontend applications.

Installation:

Install the package via npm. It supports both server and client side usage.

npm install @lndr/iam

Development setup:

The IAM application on top of which this package is built is Keycloak. For more information on Keycloak, see the official documentation.

In the repository of this package you can find a docker-compose.yml to quickly spin up a Keycloak instance for development purposes only. Just run:

docker-compose up -d

All data is stored in the keycloak/data folder, which is mounted to the Keycloak instance.

Usage:

When using this package, it is strongly recommended to import the @lndr/iam/server or @lndr/iam/client in its own module for configuring it and then import that where you want to use it. The examples are based on this approach.

Server side:

Define the IAM module for a token based authentication/authorization approach:

// src/iam.ts
import { JwtProvider } from '@lndr/iam/server';

const iam = new JwtProvider({
    url: 'http://localhost:8080',
    realm: 'my-realm',
    clientId: 'my-client'
});

export default iam;

Then you can use it in your backend as follows:

// src/index.ts
import express from 'express';
import iam from './iam';

iam.initialize().then(() => {
    const app = express();

    app.get('/protected', iam.auth(), (req, res) => {
        // This route is now protected
    });
});

You can also opt for a session based authentication/authorization approach:

// src/iam.ts
import { SessionProvider } from '@lndr/iam/server';
import session from 'express-session';

const store = new session.MemoryStore();

const iam = new SessionProvider({
    url: 'http://localhost:8080',
    realm: 'my-realm',
    clientId: 'my-client',
    store
});

export const middlewares = [
    session({
        store,
        secret: 'my-secret',
        resave: false,
        saveUninitialized: true,
    }),
    ...iam.initialize(),
];

export default iam;

Then you can use it in your backend with the slight difference that it comes with a couple of middlewares to attach to your requests:

// src/index.ts
import express from 'express';
import iam, { middlewares } from './iam';

const app = express();

app.use(...middlewares);

app.get('/protected', iam.auth(), (req, res) => {
    // This route is now protected
});

Client side:

On the application you will follow a similar pattern:

// src/iam.ts
import { JwtProvider } from '@lndr/iam/client';

const iam = new JwtProvider({
    url: 'http://localhost:8080',
    realm: 'my-realm',
    clientId: 'my-client'
});

export default iam;

And then you can use it in your frontend as follows:

// src/App.tsx
import React, { useState, useEffect } from 'react';
import iam from './iam';

export default function App() {
    const [allowed, setAllowed] = useState(false);

    useEffect(() => {
        iam.initialize().then(setAllowed);
    }, []);

    if (!allowed) return <div>Loading...</div>;

    /**
     * When making requests for the backend, add the
     * token `Bearer ${await iam.token.toString()}` to
     * the 'Authorization' headers of your request.
     */
    return <div>Authenticated</div>;
}

Notice

This project, iam, makes use of the Keycloak packages published under the Apache License 2.0.

This package itself is licensed under the MIT license.

Disclaimer: This project is provided “as is”, without warranty of any kind. The author assumes no responsibility for how this package is used.