Skip to content

docs(alb): correct and expand ALB authentication and identity docs - #174

Open
dlotterman wants to merge 2 commits into
mainfrom
docs/alb-auth-identity
Open

dlotterman wants to merge 2 commits into
mainfrom
docs/alb-auth-identity

Conversation

@dlotterman

Copy link
Copy Markdown
Contributor

Corrects the ALB authentication pages and documents what the ALB's SecurityPolicy already supports beyond Basic Auth, Google, and Auth0. Examples were validated with server-side dry-runs, and most were tested live on throwaway load balancers.

Corrections

  • Google OIDC isn't limited to "anyone with a Google account". Add a jwt block that reads the ID-token cookie (cookieNames.idToken + extractFrom.cookies) and an authorization rule on the hd claim to allow only your Workspace domain, or on email for named people. Others can still sign in with Google but get 403 at the edge. See "Restrict who can sign in" in oidc-google.mdx.
  • Auth0 page: removed the warning that jwt + oidc in one policy causes a 500 (it works, including with Google as the issuer), and the advice to remove the WAF when OIDC fails.
  • datumctl alb auth set attaches to the Gateway. A route-level policy (even CORS-only) replaces it for that route, and alb describe still reports Basic Auth as enabled.
  • alb describe doesn't show hand-written policies or added routes.
  • A route takes one SecurityPolicy; a second is rejected as Conflicted.
  • Basic Auth forwards the Authorization header, password included, to the origin. Per-user passwords and forwardUsernameHeader are now documented.

New pages

API keys, JWT, OIDC with any provider, authorization rules, CORS, and per-path authentication. The overview now lists what isn't available: client certificates (mTLS), extAuth, retries to the identity provider, location rules, and auth metrics.

OIDC logoutPath, passThroughAuthHeader (a valid bearer token skips sign-in), and denyRedirect (401 instead of a redirect for JSON requests) were tested live. refreshToken is described from Envoy Gateway's reference.

Needs a check before merge

  • Restricting real Google sign-ins end to end. The policy loads with Google as the issuer, and the claim rules were tested with Keycloak standing in for Google, but no real Google account has signed in through it.
  • Auth0-specific guidance. It wasn't tested against an Auth0 tenant.
  • oidc.mdx tells readers to host their identity provider outside Datum, because an issuer behind a Datum ALB failed about half of token exchanges in testing. Engineering may want to confirm before this is public.

Platform bugs found (documented as known issues)

  • alb auth unset / alb delete leave the ALB_NAME-basic-auth Secret behind without its gateway-sync label but with the gateway-resource-replicator finalizer, so deleting it hangs in Terminating.
  • alb delete leaves hand-added HTTPRoutes orphaned.

Should merge cleanly with #173, which touches docs.json and the ALB overview pages.

Fix wrong or incomplete auth information, verified live against the
ALB on 2026-11-18:
- Google OIDC can be limited to a Workspace domain or listed people
  with a jwt block on the ID token cookie plus authorization rules;
  it is not "anyone with a Google account" only.
- oidc + jwt in one policy works; drop the Auth0 warning that it
  causes a 500, and the advice to remove the WAF.
- datumctl alb auth set attaches to the Gateway; a route-level policy
  silently replaces it while alb describe still reports it enabled.
- alb describe doesn't show hand-written policies or added routes.
- One SecurityPolicy per route; a second is rejected as Conflicted.
- Basic Auth forwards the Authorization header (with password) to the
  origin; forwardUsernameHeader and per-user passwords are supported.

Add pages for API keys, JWT, generic OIDC (any provider), authorization
rules, CORS, and per-path authentication, and list what isn't
available (mTLS, extAuth, provider retries, GeoIP, auth metrics).
@dlotterman
dlotterman requested a review from a team as a code owner November 18, 2026 20:47
@mintlify

mintlify Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
Datum 🟢 Ready View Preview Nov 18, 2026, 8:47 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

This branch was successfully deployed

1 active deployment
staging — f8d05ce2 Deployed Nov 18, 2026 by mintlify[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant