@osohq/express
v0.3.2
Published
The Oso SDK with Express integration provides helper functions to facilitate hooking Oso into the Express web framework.
Downloads
9
Readme
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 settingdefaultActorId
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;
},
});
Supported Versions
- Express: 4.x