@osohq/express NPM

Oso SDK with Express integration

The Oso SDK with Express integration provides helper functions to facilitate hooking Oso into the Express web framework.

Please Note: The SDK is currently released as a developer preview. Do not use this SDK for production workloads.

Install

npm install --save @osohq/express
yarn add @osohq/express

Usage

The Oso SDK should be initialized as early as possible in the main entry module. The Oso SDK can be hooked into Express as a centralized middleware or as a route middleware using the enforce function.

import { init } from '@osohq/express';
import express from 'express';

const oso = init({
    apiKey: 'YOUR_API_KEY',
    // ...
})

const enforcement = {
  action: 'view',
  resourceType: 'Org',
  resourceId: '123',
};

// Centralized enforcement
app.use(oso.enforce(enforcement));

// Per-route enforcement
app.get('/', oso.enforce(enforcement), (_req, _res) => {
  // ...
});

app.listen(5678);

After the Oso SDK is initialized, you may access it by calling globalOso():

import { globalOso } from '@osohq/node';

oso = globalOso();

The Oso SDK may be further configured by setting relevant fields in the ConfigOptions object passed on init.

Integration Options

By default,

Actor ID is a hardcoded value of _. You may override the Actor ID using the setting defaultActorId when initializing the Oso SDK.
Action is inferred from the HTTP method. If you have a different set of permissions from the defaults, you may override the mapped value by setting defaultAction when initializing the Oso SDK.
HTTP 404 is returned on authorization failure. You may specify a custom error handler by setting defaultErrorHandler when initializing the Oso SDK.

User Identification

You may provide a function to determine the Actor Id by setting defaultActorId when initializing the Oso SDK.

import { init } from '@osohq/express';
import { Request } from 'express';

init({
  apiKey: 'YOUR_API_KEY',
  // Hardcode the actor Id to `admin`
  defaultActorId: (_req: Request) => 'admin',
});

Action Identification

You may provide a function to determine the action by setting defaultAction when initializing the Oso SDK.

import { init } from '@osohq/express';
import { Request } from 'express';

init({
  apiKey: 'YOUR_API_KEY',
  // Hardcode the action to `view`
  defaultAction: (_req: Request) => 'view',
});

Custom Error Handling

You can provide a function to determine the response on authorization failure.

import { init } from '@osohq/express';
import { Response, NextFunction } from 'express';

init({
  apiKey: 'YOUR_API_KEY',
  // Return HTTP 418 on authorization failure
  defaultErrorHandler: (res: Response, _next: NextFunction) => {
    res.send(418).send("I'm a teapot");
    return;
  },
});