Proxy Provider: SSO for Apps That Don't Speak SSO

Not every application supports OIDC or SAML. Internal dashboards, legacy tools, self-hosted apps with basic auth — they all need protection, but integrating a proper SSO flow is often impractical or impossible.

JustIAM’s Proxy Provider solves this by sitting between your reverse proxy (Traefik, Nginx, Caddy) and the upstream application, handling authentication transparently. No code changes to the application. No custom auth middleware.

How It Works

The Proxy Provider uses the forward-auth pattern:

1. User navigates to app.example.com/dashboard
2. The reverse proxy sends a sub-request to JustIAM’s /proxy/auth endpoint
3. JustIAM checks if the user has a valid session for that hostname
4. If yes → returns 200 with identity headers. The proxy forwards the request upstream.
5. If no → returns 401 with a Location header. The proxy redirects the user to JustIAM’s login page.

After authentication, the user lands back on the original URL with a valid proxy session. On every subsequent request, JustIAM injects identity headers that the upstream app can trust:

X-Auth-User: alice
X-Auth-Email: alice@corp.com
X-Auth-Name: Alice Smith
X-Auth-Groups: engineering,ops
X-Auth-Roles: admin

The upstream application doesn’t need to know anything about OIDC. It just reads headers.

The Session Problem (and How Cookie Cleanup Solves It)

Here’s where things get interesting. Many applications behind a proxy maintain their own session state — a JSESSIONID cookie, a localStorage token, an internal auth ticket. When JustIAM revokes the proxy session (because the user was removed from a group, their access expired, or an admin triggered a revocation), the upstream app still thinks the user is authenticated.

This is a real security gap. The user’s IDP session is dead, but the downstream app doesn’t know.

JustIAM addresses this with Binding Cleanup Config:

Downstream Cookie Cleanup

Configure regex patterns for cookies the app sets. When the proxy forces re-authentication, JustIAM clears those cookies server-side (via Set-Cookie: name=; MaxAge=-1):

{
  "downstream_cookies": ["JSESSIONID\\..+", "MY_APP_SESSION"]
}

This works for HttpOnly cookies too — the ones JavaScript can’t touch. JustIAM clears them at the proxy level before the user’s browser even hits the app.

LocalStorage Cleanup

For apps that store tokens in localStorage:

{
  "downstream_storage_keys": ["oidc.user", "app.state", "refresh_token"]
}

When a re-authentication is triggered, JustIAM serves a cleanup page that removes these keys before redirecting back to the login flow.

Post-Auth Redirect

Some apps (ArgoCD, Grafana, Spring Boot) need their own login handshake after the proxy authenticates the user. The reauth_redirect_url field handles this:

{
  "reauth_redirect_url": "https://argo-cd.example.com/auth/login?return_url={path}"
}

The {path} token preserves the user’s original deep link — they end up exactly where they were trying to go.

Per-Path Access Policies

Not every URL on a hostname needs the same protection. The Proxy Provider supports access policies evaluated per-request, first match wins:

{
  "name": "Admin only",
  "priority": 50,
  "path_pattern": "/admin/**",
  "action": "authenticate",
  "require_any_group": ["ops", "platform-eng"]
}

Health checks pass through without authentication. Admin paths require specific group membership. Everything else requires login but no specific group.

Domain Roles

For finer-grained access, Domain Roles let you create hostname-scoped roles and assign groups to them:

1. Create a role administrator on app.example.com
2. Assign the platform-eng group to that role
3. Reference it in a policy: require_app_mapping: ["administrator"]

This separates “can access the app” from “what level of access within the app” — useful when the upstream app reads the X-Auth-Roles header for its own authorization logic.

Real-World Example: Protecting ArgoCD

ArgoCD supports OIDC natively, but its SSO integration can be finicky — callback URL quirks, group claim formatting, session invalidation gaps. Using the Proxy Provider is often simpler:

1. Add the hostname binding:

curl -X POST .../proxy-providers/{id}/bindings \
  -d '{"hostname": "argo-cd.example.com", "default_action": "authenticate"}'

2. Configure cleanup (ArgoCD stores its own token):

curl -X PATCH .../proxy-providers/{id}/bindings/{binding_id} \
  -d '{
    "downstream_cookies": ["argocd\\.token"],
    "reauth_redirect_url": "https://argo-cd.example.com/auth/login?return_url={path}"
  }'

3. Configure Traefik forward-auth middleware:

http:
  middlewares:
    justiam-auth:
      forwardAuth:
        address: "http://justiam:8080/proxy/auth"
        trustForwardHeader: true
        authResponseHeaders:
          - X-Auth-User
          - X-Auth-Email
          - X-Auth-Groups
          - X-Auth-Roles

4. Done. Users hit ArgoCD, get redirected to JustIAM for login (with MFA if configured), and land back in ArgoCD with proper identity headers. When their group membership changes, the proxy session is automatically revoked and they re-authenticate with fresh claims.

Automatic Session Revocation

This is the killer feature for security teams: proxy sessions are revoked automatically when access changes.

If a user is removed from a group that’s required by an access policy, their next request to that hostname triggers a full re-authentication. Combined with cookie cleanup, this means the downstream app also loses its session state.

No stale sessions. No “the user was removed 3 hours ago but still has access.” The revocation propagates to the application layer within seconds.

When to Use the Proxy Provider vs. Native OIDC

The My Apps Portal

Proxy-protected hostnames can optionally appear in the user’s My Apps portal alongside native OIDC/SAML applications. Configure a display name, icon, and launch URL — users get a single dashboard for all their tools regardless of the underlying protocol.

The Proxy Provider bridges the gap between “we want SSO everywhere” and “half our apps don’t support it.” It’s not a replacement for native OIDC integration — but for the apps where that’s impractical, it provides the same security guarantees with zero application changes.

Full documentation →