@ovotech/identity-auth v2.2.0

Identity Auth

Reusable auth library for OVO node services using the identity platform for authentication.

Supports service to service authentication and client to server authentication.

Exposes an authClient that can be used in your middleware, additionaly provides a fastify middleware handler.

Server to server auth

Example usage to secure an endpoint

import { identityAuth } from '@ovotech/identity-auth/lib/server-to-server';
import fastify from 'fastify';
import { IncomingMessage, Server, ServerResponse } from 'http';

const { middleware } = identityAuth({
  identityBaseUrl: 'https://auth.id-uat.ovotech.org.uk',
  roleKey: 'homemoves-moves-service', // your service name here
});

const app: fastify.FastifyInstance<
  Server,
  IncomingMessage,
  ServerResponse
> = fastify({});

app.get(
  '/secured',
  {
    preValidation: middleware.fastify({ requiredRoles: ['move-in'] }), // your required roles here
    schema: {
      headers: {
        type: 'object',
        properties: {
          authorization: {
            type: 'string',
          },
        },
      },
    },
  },
  () => Promise.resolve('authenticated')
);

Auth client

Interface:

type AuthClient = {
  authenticateToken: (jwtToken: string) => Promise<Either<AuthError, Authed>>;
};

Usage

import { identityAuth } from '@ovotech/identity-auth/lib/server-to-server';

const authclient = identityAuth(config).client({ requiredRoles: ['move-in'] });

authclient.authenticateToken('eyJhbGciOiJSUzI1NiI...');

Client to server auth

Interface:

type AuthClient = {
  authenticateToken: ({ requiredPermissions: Array<string> }, jwtToken: string) => Promise<Either<AuthError, Authed>>;
};

Usage

import { identityAuth } from '@ovotech/identity-auth/lib/client-to-server';

const authclient = identityAuth({
  identityBaseUrl: 'https://auth.id-uat.ovotech.org.uk',
}).client;

const requiredPermissions = ['orion-exp::account::account-id-123'];

authclient.authenticateToken({ requiredPermissions }, 'eyJhbGciOiJSUzI1NiI...');

Client to server and server to server auth combined

Auth is supported for both client-to-server and server-to-server together.

Both mechanisims are supported together, so that clients and servers can be permitted access to the same resource.

Interface:

type AuthClient = {
  authenticateToken: (accessRequirements: AccessRequirements, jwtToken: string) => Promise<Either<AuthError, Authed>>;
};

type Authed = { channel: 'server' | 'client' };

type AccessRequirements = {
  forClient?: ClientAccessRequirements;
  forServer?: ServerAccessRequirements;
};

type ClientAccessRequirements = {
  requiredPermissions: Array<string>;
};

type ServerAccessRequirements = {
  roleRequirements: Array<RoleRequirement>;
};

type RoleRequirement = {
  roleKey: string;
  requiredRoles: Array<string>;
};

Usage

import { identityAuth } from '@ovotech/identity-auth/lib';

const authclient = identityAuth({
  identityBaseUrl: 'https://auth.id-uat.ovotech.org.uk',
}).client;

const requiredPermissions = ['orion-exp::account::account-id-123'];
const roleRequirements = [{
  roleKey: 'homemoves-moves-service',
  requiredRoles: ['move-in']
}];
const accessRequirements: AccessRequirements = { 
  forClient: { requiredPermissions }, 
  forServer: { roleRequirements } 
};

authclient.authenticateToken(accessRequirements, 'eyJhbGciOiJSUzI1NiI...');

Integration tests

These currently use a homemoves service and the UAT identity service. To check your own service authentication:

replace `roleKey: 'homemoves-moves-service'` and `requiredRoles: ['move-in']` with your own

and export your UAT client secret

export IDENTITY_CLIENT_SECRET=<your-secret-here>

run

npm run test:integration

Notes

Note that currently this is the first iteration and is likely to change to become more usable by other teams.

PRs welcome :)