Session & Token Management

Every authenticated action in an internal developer portal rides on a token, so how those tokens are issued, scoped, refreshed, and revoked is the difference between a compromised session lasting minutes and lasting weeks. This guide is for platform engineers who need short-lived, revocable sessions and API tokens across a portal’s browser and service-to-service surfaces, sitting at the heart of Authentication, RBAC & Security Governance.

Token lifecycle from issuance to revocation An identity provider issues a short-lived access token and a refresh token; the portal validates the access token, silently refreshes it, and can revoke the session at the identity provider. Identity provider issues tokens Access token short-lived JWT Portal validates aud · iss · exp Refresh token silent renewal Revoke kill session Portal API action allowed
Short access tokens plus refresh tokens give both a small compromise window and a seamless user experience; revocation ends a session regardless of token expiry.

Session and token design is a set of trade-offs between security and friction. Long-lived tokens are convenient but extend the blast radius of a leak; stateless JWTs are fast to validate but hard to revoke before expiry; opaque tokens revoke instantly but add an introspection round-trip. This guide resolves those trade-offs with short-lived access tokens, refresh-based silent renewal, and a revocation path, all consistent with how tokens are consumed in your OIDC & SSO Configuration and scoped by your Role-Based Access Control Setup.

Prerequisites & Environment Baseline

Establish the token contract before writing validation code: which issuer signs tokens, what audience the portal accepts, how long access tokens live, and where refresh state resides. A portal that accepts a token with the wrong audience is a cross-service replay waiting to happen.

Token contract baseline A trusted issuer, an accepted audience, a defined access-token lifetime, and refresh state make sessions manageable. trusted issuer accepted audience access TTL defined refresh state Token contract defined
A strictly-checked audience claim is the single control that prevents a token minted for one service being replayed against the portal.
  • Identity provider issuing OIDC tokens with a stable iss and a per-portal aud, its JWKS endpoint reachable for signature verification.
  • Access-token lifetime decided — 15 minutes to 1 hour is typical — short enough to bound a leak, long enough to avoid constant refreshes.
  • A session store (Redis) for refresh-token state and a server-side revocation list, so a session can be ended before its access token expires.
# Requires jq; confirm the token's audience matches the portal
echo "${ACCESS_TOKEN}" | cut -d. -f2 | base64 -d 2>/dev/null | jq '{aud, iss, exp}'

Step-by-Step Configuration & Plugin Architecture

Configure three things in sequence: stateless validation of the access token on every request, silent refresh before expiry so users are not logged out mid-task, and a revocation check for sensitive actions. The design detail for each lives in the how-tos linked below.

Three session-management controls Stateless access-token validation, silent refresh before expiry, and a revocation check on sensitive actions. Validate access token stateless, JWKS Silent refresh before expiry Revocation check sensitive actions
Checking a revocation list only on sensitive actions keeps most requests stateless while still allowing an instant session kill where it matters.

Validate the access token statelessly against the identity provider’s public keys on every request, rejecting anything with a wrong aud, iss, or an expired exp. The full session configuration — cookie flags, refresh cadence — is covered in Configuring Short-Lived JWT Sessions.

# app-config.yaml
# Requires Backstage >= 1.20.0
auth:
  session:
    secret: ${SESSION_SECRET}
  providers:
    oidc:
      production:
        metadataUrl: ${OIDC_METADATA_URL}
        clientId: ${OIDC_CLIENT_ID}
        clientSecret: ${OIDC_CLIENT_SECRET}
        prompt: auto

For machine identities — CI, service accounts — issue narrowly-scoped API tokens with their own rotation and revocation, as detailed in Revoking and Rotating Portal API Tokens.

Validation & Health Checks

Verify the three properties that make sessions safe: a valid token is accepted, an expired one is rejected, and a revoked session is denied even before its access token would expire.

Session validation checks A valid token is accepted, an expired token is rejected, and a revoked session is denied. Valid → 200 accepted Expired → 401 rejected Revoked → 401 before expiry
The revoked-before-expiry check is the one stateless JWT validation cannot do alone — it proves the revocation list is consulted.
# Requires curl
# 1. A valid token is accepted
curl -s -o /dev/null -w "%{http_code}\n" ${PORTAL_API_URL}/api/catalog/entities \
  -H "Authorization: Bearer ${VALID_TOKEN}"
# Expected: 200

# 2. An expired token is rejected
curl -s -o /dev/null -w "%{http_code}\n" ${PORTAL_API_URL}/api/catalog/entities \
  -H "Authorization: Bearer ${EXPIRED_TOKEN}"
# Expected: 401

Maintenance & Lifecycle Management

Sessions and tokens need ongoing rotation and monitoring. Rotate the session signing secret on a schedule, keep the JWKS cache TTL bounded so identity-provider key rotation never breaks logins, and alert on refresh-failure spikes that signal an identity-provider problem.

Session and token maintenance Rotate the signing secret, bound the JWKS cache, and alert on refresh-failure spikes. Rotate secret overlap window Bound JWKS cache TTL 300s Alert on refresh failure spikes
A refresh-failure spike is usually the first visible symptom of an identity-provider key rotation the portal's JWKS cache did not pick up.
  • Signing-secret rotation with an overlap window so tokens signed under the previous secret remain valid until they expire.
  • JWKS cache TTL of a few minutes with fallback verification, so an identity-provider key rotation never causes a login outage.
  • Refresh monitoring: alert when refresh failures rise, which usually means the identity provider changed keys or the refresh token was invalidated upstream.

Common Pitfalls & Mitigation Strategies

The session failures divide into validation gaps (skipped audience, no revocation) and lifecycle gaps (long-lived tokens, no rotation). The map pairs each with its fix.

Session pitfalls by class Skipped audience and no revocation are validation gaps; long-lived tokens and no rotation are lifecycle gaps. Validation gaps skipped aud no revocation → strict aud + list Lifecycle gaps long-lived tokens no rotation → short TTL + rotate
Strict audience checking and short-lived tokens close the two failure classes that cause most session-security incidents.
  • Skipping audience validation. Fix: reject any token whose aud is not exactly the portal’s client id.
  • No way to revoke before expiry. Fix: maintain a server-side revocation list checked on sensitive actions and on refresh.
  • Long-lived access tokens. Fix: keep access tokens short (≤1h) and rely on refresh tokens for continuity.
  • Static, un-rotated signing secrets. Fix: rotate on a schedule with an overlap window so no valid session breaks.

Frequently Asked Questions

Stateless JWTs or opaque tokens for the portal?

Use stateless JWTs for the common read path — they validate in microseconds with no network call — and add a revocation-list check on the sensitive write path where instant revocation matters. This hybrid keeps the portal fast while still allowing you to end a compromised session immediately, rather than choosing between speed and revocability.

How short should the access-token lifetime be?

Short enough that a leaked token is useless quickly, long enough that refreshes are not constant — fifteen minutes to one hour covers most portals. Pair it with a refresh token so the user is never interrupted; the access-token TTL bounds the leak, and silent refresh preserves the experience.

How do machine tokens differ from user sessions?

Machine tokens have no interactive refresh, so they are issued with a longer but bounded lifetime, scoped to exactly the actions the automation needs, and rotated on a schedule with a revocation path. Never reuse a user session token for automation, and never give a machine token broader scope than its single job requires.