VERISCO Shield Integrate

SDK mode

Nothing sits in front of your application. It performs the sign-in itself and enforces in-process, fed by VERISCO every 30 seconds.

When to use it#

You cannot put anything in front of your application, and it runs on Express or Connect. Your DNS and your servers do not change. You need outbound HTTPS on port 443 to VERISCO, and nothing inbound.

Read this before choosing

Enforcement is inside your application here. Your code applies it, so your code can fail to: remove the middleware and nothing outside your process is refusing anyone. In gateway and connector mode the enforcement is outside your application and cannot be undone by a deploy.

Install#

Shell

npm install https://your-verisco-host/api/v1/sdk/node

Mount#

server.js

const verisco = require('@verisco/verisco-middleware/oidc');

app.use(verisco.oidc({
  issuer: process.env.VERISCO_ISSUER,
  clientId: process.env.VERISCO_CLIENT_ID,
  clientSecret: process.env.VERISCO_CLIENT_SECRET,
}));

app.get('/private', verisco.protect(), (req, res) => res.json(req.user));

It mounts /verisco/login, /verisco/callback and /verisco/logout in your application, at the same paths the gateway serves them at, and sets req.user to the same shape. protect() and your sign-out links are the same in every mode.

Options#

Option	Required	Meaning
`issuer`	Yes	Your realm's issuer, `https://your-verisco-host/auth/realms/<tenant-id>`.
`clientId`	Yes	`<tenant-id>-user`.
`clientSecret`	Yes	Your client secret. The same secret authenticates your application to the enforcement feed.
`appUrl`	No	Your application's own public address, used to build the redirect URI.
`baseUrl`	No	VERISCO's public address. Derived from the issuer when absent.
`drift`	No	Compare the network and browser on every request (session binding). Off by default.
`instanceId`	No	A name for this instance on your console.
`onError`	No	Called when the feed cannot be reached. Logs a warning by default.

Your issuer, client id and client secret are on your integration page in the console. Keep the secret in your environment, not in your repository.

What is different in SDK mode#

There is no public key to download and no X-Verisco-Claims header. Your application is the sign-in client and reads its own session.

	Gateway and connector	SDK
A change in your console reaches you	Within 5 seconds	Within 30 seconds
If VERISCO is unreachable	Your application is unreachable	Your application keeps working on what it last heard
Roles	Read from your user row and signed into the assertion	The role your directory returns, in the ID token
The user's own page, `/verisco/me`	Available	Not available
WordPress plugin	Available	Not available
Any language	Yes	Node, with Express or Connect

It fails open, deliberately#

If VERISCO is unreachable, the middleware keeps its last known state and applies whatever it missed on the next successful poll. A VERISCO outage does not take your application down. The cost is a window in which a revocation has not reached you yet. Your console shows when each of your instances last called in, so a stale one is visible.

Session binding needs your proxy trust#

With drift: true the middleware compares each request's address with the one the session started on. If your application sits behind a load balancer and reports the balancer's address instead of the user's, every session looks like it moved. Configure your framework's proxy trust first:

JavaScript

app.set('trust proxy', 1);

Frameworks#

SDK mode is offered for Express and Connect. Fastify, Next.js, NestJS, Koa and Hapi are not offered SDK mode yet. If you pick it with one of those, onboarding moves you to connector mode and says so, because the connector needs nothing from your framework. See Framework support.

The enforcement feed#

The middleware polls GET /api/v1/enforcement/state and reports what it enforced to POST /api/v1/enforcement/events. You do not call either yourself. Their shapes are in the API reference.

Something missing or wrong on this page? Tell us and we will fix it.