Five routes cover the full OIDC flow — login, callback, session, refresh, and logout.
// GET /login — redirect user to OIDC provider
app.get('/login', auth.login);
// auth.login is a pre-bound Express handler.
// It generates PKCE params, stores state, and redirects.
OAauth is an auth infrastructure layer for Node.js applications. It handles the full OIDC flow — PKCE generation, token exchange, session lifecycle, and JWT verification — so your application never touches raw credentials.
Tokens are verified locally via JWKS by default. This means zero network latency on protected routes. No gateway call happens per request unless you set localVerify: false.
How it works
When a user logs in, your server redirects them to the OIDC provider via auth.login. After the provider authenticates the user, it redirects back to your /callback route. The SDK exchanges the authorization code for tokens, creates an opaque session (stored in the SDK gateway), and returns an access token and refresh token to your application.
Your frontend holds the short-lived access token in memory. The refresh token lives in an httpOnly cookie, invisible to JavaScript. When the access token expires, your frontend calls /refresh and gets a new pair — silently, without the user noticing.
An Express request handler. Wire it directly as a route callback — no wrapper needed.
GET/login
When a user hits this route, the SDK generates a PKCE code verifier and challenge, stores state in a short-lived cookie, and redirects the user to the OIDC provider's authorization endpoint. No configuration beyond the initial AuthClient setup is required.
javascript
app.get('/login', auth.login);
handleCallbackAndCreateSession()
Exchanges the authorization code for tokens and creates a session in the SDK gateway. Returns the access token, refresh token, and user profile.
Short-lived JWT. Pass as Authorization: Bearer <token>. Expires in 15 minutes.
refreshToken
string
Opaque long-lived token. Store in an httpOnly cookie. Used to rotate access tokens.
user
object
OIDC user claims: { sub, email, name, roles }
auth.protect()
Middleware factory that validates the access token on each request and populates req.user. Tokens are verified locally by default — no network call required.
javascript
// Require authentication
app.get('/me', auth.protect(), (req, res) => {
res.json(req.user); // { sub, email, name, roles }
});
// Optional — req.user is null for unauthenticated requests
app.get('/feed', auth.protect({ optional: true }), handler);
// Apply to an entire router
router.use(auth.protect());
Option
Type
Default
Description
optional
boolean
false
When true, unauthenticated requests pass through with req.user = null instead of returning 401.
requireRole()
Middleware that checks whether req.user.roles includes the required role. Must be composed after auth.protect().
javascript
// Single role
app.delete(
'/admin/users/:id',
auth.protect(),
auth.requireRole('admin'),
deleteUser
);
// Multiple roles — user must have at least one
auth.requireRole(['admin', 'moderator'])
refreshRoute()
A pre-built Express route handler that reads the refresh token from an httpOnly cookie (or request body), rotates the token pair, and sets the new cookie.
POST/refresh
javascript
// Default — reads from cookie named 'refreshToken'
app.post('/refresh', auth.refreshRoute());
// Custom cookie name
app.post('/refresh', auth.refreshRoute({ cookieName: 'rt' }));
logoutRoute()
A pre-built handler that revokes the current session in the SDK gateway and clears the refresh token cookie.
POST/logout
javascript
app.post('/logout', auth.logoutRoute());
getSessions()
Fetches all active sessions for a given user from the SDK gateway. Useful for building a "logged-in devices" UI.