Authentication & SSO

StrataBI runs inside your own AWS account, and access to it is governed by an identity layer you control. StrataBI does not implement a login screen or store credentials. Instead, you put your own authenticating layer in front of the app, and StrataBI recognizes the already-authenticated user from a trusted request header.

The model: bring your own auth

You run an authenticating proxy or gateway in front of StrataBI — an application load balancer with Cognito, oauth2-proxy, an API gateway, or your corporate SSO. That layer authenticates the user and forwards a trusted identity header. StrataBI reads the header to recognize the user and (optionally) authorize them, then serves the request. The app itself never sees a password.

your IdP / SSO  ──►  authenticating proxy  ──►  StrataBI
                     (ALB+Cognito, oauth2-proxy,        │
                      API gateway, SSO)                 │
                              trusted identity header ──┘

Auth modes

The gate is controlled by the STRATABI_AUTH_MODE environment variable:

Configuration variables:

• STRATABI_AUTH_MODE — none | header | cognito.
• STRATABI_AUTH_HEADER — (mode header) the exact header to read. If unset, common

proxy headers are tried: X-Forwarded-User, X-Auth-Request-Email, X-Auth-Request-User, X-User, X-Email.

• STRATABI_AUTH_ALLOWED_GROUPS — optional comma-separated allow-list of groups. Empty

means any authenticated user is allowed; set it to restrict access to named groups.

• STRATABI_AUTH_GROUPS_CLAIM — (mode cognito) the JWT claim holding groups

(default cognito:groups).

The /healthz path is always open so load-balancer health checks succeed regardless of mode.

Mode header — any proxy

Run oauth2-proxy, an SSO sidecar, or an API gateway that authenticates the user and sets a header. Point StrataBI at it:

STRATABI_AUTH_MODE=header
STRATABI_AUTH_HEADER=X-Auth-Request-Email
STRATABI_AUTH_ALLOWED_GROUPS=analysts,platform   # optional

Any request without the header (or outside the allowed groups) is rejected with 401.

Mode cognito — ALB + Cognito (optional, turnkey)

If you'd rather not run your own proxy, the Terraform module ships an optional Cognito seam, off by default. Set enable_cognito = true to provision a user pool, app client, and hosted domain, then attach an authenticate-cognito action to your HTTPS listener. The listener requires a signed-in session and injects the OIDC JWT that StrataBI reads:

auth_mode      = "cognito"
enable_cognito = true

The Cognito user pool can itself federate to your existing identity provider — OIDC (Okta, Microsoft Entra ID, Google Workspace, Ping) or SAML 2.0 — so users authenticate against the directory you already operate. Single sign-on, MFA, conditional access, and account lifecycle remain governed by your IdP.

From identity to authorization

Two layers of authorization are available and independent:

1. Group allow-list (STRATABI_AUTH_ALLOWED_GROUPS) — a coarse gate at the door:

only listed groups get in at all.

1. Roles & access control — once a user is in, group or role claims map into

StrataBI roles that determine what they can see and do. See Roles & access control.

Common mistakes

• Exposing the app directly. With a mode other than none, the app must sit behind

the proxy on a private network. A publicly reachable app trusts a forgeable header.

• Wrong header name. In header mode, confirm the exact header your proxy emits and

set STRATABI_AUTH_HEADER to match, or rely on the built-in defaults.

• Empty allow-list expecting a deny. An empty STRATABI_AUTH_ALLOWED_GROUPS allows

any authenticated user. To restrict, name the groups explicitly.

• Groups claim mismatch. In cognito mode, if your JWT carries groups under a

different claim, set STRATABI_AUTH_GROUPS_CLAIM.