Adding Authentication¶

You can put a sign-in wall in front of any HTTP service so only authenticated users reach it — without writing login code yourself. Requests are authenticated by oauth2-proxy before they ever reach your app; your app just reads who the user is.

Turn on authentication¶

1. Make sure the external domain your service uses has an oauth2-proxy URL configured. This is an admin setup — if it isn't set, ask your environment administrator (see External Domains — Authentication).
2. Enable the Require auth checkbox on your HTTP service when creating or editing the container.

That's it — unauthenticated visitors are now redirected to sign in. The rest of this page is about reading the signed-in user's identity in your app, in three ways:

1. Server-side apps — read the identity headers NGINX adds to each proxied request.
2. Apps that need the raw token / extra claims — read and (optionally) verify the access token.
3. Static / "serverless" frontends — call oauth2-proxy's /oauth2/userinfo endpoint from the browser.

Identity headers (server-side)¶

Every authenticated request arrives at your backend with a stable set of headers describing the signed-in user. The names are always the same, so your app can rely on them:

Reading them is trivial — they are ordinary request headers. Example in Node/Express:

app.get('/', (req, res) => {
  const user = {
    id: req.get('X-User'),
    username: req.get('X-Preferred-Username'),
    email: req.get('X-Email'),
    groups: (req.get('X-Groups') || '').split(',').filter(Boolean),
  };
  res.json({ user });
});

Reading and verifying the access token¶

If you need more than the identity headers above — for example to call another API on the user's behalf, or to read custom claims — use the access token from the X-Access-Token header. (If that header isn't present, access-token passthrough isn't enabled for your domain; ask your administrator.)

Whether that token is a JWT depends on your identity provider:

• Providers that issue JWT access tokens (Keycloak, Microsoft Entra ID, Auth0, etc.) — you can decode and verify it.
• Providers that issue opaque tokens (e.g. plain Google OAuth) — the token is not a JWT; treat it as a bearer string and validate it by calling the provider's introspection/userinfo endpoint instead.

Decode (no verification)¶

A JWT is three base64url segments (header.payload.signature). Decoding the payload gives you the claims, but decoding is not verification — never make an authorization decision on a decoded-but-unverified token that came from an untrusted source.

function decodeJwtPayload(token) {
  const payload = token.split('.')[1];
  const json = Buffer.from(payload, 'base64url').toString('utf8');
  return JSON.parse(json);
}

Verify (recommended)¶

Verify the signature against your IdP's public keys (JWKS) and check the standard claims (iss, aud, exp). Use a maintained library rather than hand-rolling this.

import { createRemoteJWKSet, jwtVerify } from 'jose';

// Your IdP's JWKS endpoint, e.g. from its OIDC discovery document
// (<issuer>/.well-known/openid-configuration -> "jwks_uri").
const JWKS = createRemoteJWKSet(new URL(process.env.OIDC_JWKS_URI));

async function verifyAccessToken(token) {
  const { payload } = await jwtVerify(token, JWKS, {
    issuer: process.env.OIDC_ISSUER,      // expected "iss"
    audience: process.env.OIDC_AUDIENCE,  // expected "aud" (your client/app id)
  });
  return payload; // verified claims
}

Static / "serverless" frontends: /oauth2/userinfo¶

A single-page app, static site, or any frontend with no backend of its own cannot read the identity headers (those are added between NGINX and a backend, not visible to the browser). Instead, oauth2-proxy exposes a JSON endpoint on the app's own origin:

GET https://app.example.com/oauth2/userinfo

Because /oauth2/* is served on your app's own hostname, the browser sends the session cookie automatically — just include credentials:

const res = await fetch('/oauth2/userinfo', { credentials: 'include' });
if (res.status === 401) {
  // Not signed in — send the user through sign-in, then back here.
  window.location.href =
    '/oauth2/sign_in?rd=' + encodeURIComponent(window.location.href);
} else {
  const user = await res.json();
  // { user, email, groups, preferredUsername, additionalClaims }
  console.log(user.preferredUsername, user.email, user.groups);
}

The response is JSON with this shape:

{
  "user": "a1b2c3d4",
  "email": "jane@example.com",
  "groups": ["developers", "admins"],
  "preferredUsername": "jane",
  "additionalClaims": {}
}

Helpful oauth2-proxy endpoints from the browser¶