Identity, SSO & RBAC
Admin guide
Greenlight authenticates every user through your identity provider. Sign-in uses OpenID Connect with Entra ID, Okta, or Google Workspace; SAML 2.0 and SCIM provisioning are coming soon. With Entra ID and Okta, Greenlight roles are mapped from customer-managed group membership; Google Workspace roles are managed directly in the Greenlight dashboard (Google ID tokens carry no group claim).
Greenlight does not store a password, a recovery secret, or a second-factor configuration for any user. The IdP is the only authority on whether a session can begin — MFA, conditional access, and step-up flows are the IdP’s responsibility and apply without any Greenlight-specific configuration. If a user is disabled in the IdP, access ends when their Greenlight session expires or is revoked; SCIM-based immediate deprovisioning arrives with SCIM support.
Protocol support
Section titled “Protocol support”| Protocol | Notes |
|---|---|
| OpenID Connect | Supported today for Entra ID, Okta, and Google Workspace. |
| SAML 2.0 | Coming soon for IdPs or enterprise standards that require SAML. |
| SCIM 2.0 | Coming soon for automatic user and group provisioning. |
Wire it up
Section titled “Wire it up”- In Entra ID, create an Enterprise application for Greenlight. Pick “Integrate any other application you don’t find in the gallery.”
- Configure OIDC by registering Greenlight as a confidential client. Add the Greenlight redirect URL the install wizard provides.
- In Token configuration, add a groups claim so the groups you want mapped to Greenlight roles ride in the sign-in token. Greenlight reads roles from that claim — it does not call Microsoft Graph to look groups up.
- Verify the group claims Greenlight receives before mapping groups to roles.
Full walkthrough: Microsoft Entra ID setup.
- In Okta, create an OIDC Web Application.
- Set the sign-in redirect URI from Greenlight’s first-run wizard.
- Add the groups claim to the ID token.
- Assign the groups that should have Greenlight access.
- Verify the group claims Greenlight receives before mapping groups to roles.
Full walkthrough: Okta setup.
- Configure Greenlight as an OIDC client in Google Cloud for the Workspace domain.
- Add the redirect URI from Greenlight’s first-run wizard.
- Set the Workspace domain so sign-in is restricted to your org.
Google ID tokens carry no groups claim, so Greenlight does not map Google groups to roles. For Google Workspace orgs, roles are managed in the dashboard — assign Builder, Admin, and Org Owner on the Users page after a person signs in. Everyone who signs in starts as a Builder; the Workspace domain restriction is the only sign-in gate.
Full walkthrough: Google Workspace setup.
The three roles
Section titled “The three roles”Greenlight has three roles, strictly nested — each includes everything the one below it can do, so a user mapped into several groups holds the strongest mapped role. Anyone who signs in through your IdP gets the Builder role automatically; the elevated roles come from group mappings, re-evaluated at every sign-in.
| Role | What they can do | Maps to typical IdP group |
|---|---|---|
Builder (user) | The default role for everyone with Greenlight access. Builders create apps; the user who creates an app automatically owns it and can add co-owners. Owners manage their app’s environment variables, request integrations, edit app-scope Knowledge, and ask to pause or resume their own app. | None needed by default — everyone who signs in gets this role. Optionally map group(s) here to limit who can use Greenlight at all. |
Admin (admin) | Manage integrations and credentials, edit org-scope Knowledge, review agent proposals, view the audit log, kill or restore any app, and override the policy check (with audit). The day-to-day IT role. | The IT operations team. |
Org Owner (org_admin) | Everything an Admin can do, plus: edit the policy bundle, install or upgrade Greenlight, change IdP group mappings, and add or remove other Admins and Org Owners. | The small group (often 1–3 people) who installed Greenlight. |
Roles are evaluated on every API call and MCP tool invocation. App access at the edge goes through /auth/check, whose decision is cached briefly — about 60 seconds — so removing a group or role takes effect within that window. When immediate revocation is needed, a force-re-auth invalidates the cached decision at once.
Deployed apps sit behind the same SSO and are open by default: every signed-in user in your org can open any app until its owner (or an Admin) binds IdP groups to it, restricting it to those groups. The app’s owner and co-owners, and Admins and Org Owners, always retain access — that guarantee is enforced in code, not configuration.
Log in as (impersonation)
Section titled “Log in as (impersonation)”An Org Owner can log in as an Admin or Builder from Users & RBAC to see the dashboard exactly as that colleague does — the same navigation, app scoping, and permissions — without creating a test account. Pick a user, confirm, and you’re viewing under their role; a banner stays on screen naming who you’re viewing as, and Stop impersonating returns you to your own session in one click.
Two things to know: you can only impersonate active Admins and Builders (never another Org Owner), and every action you take while impersonating is recorded in the audit log under your own identity, tagged with who you were viewing as. It’s a read-and-verify tool for RBAC, fully accountable — not a way to act anonymously.
App ownership
Section titled “App ownership”App ownership is not a role and isn’t mapped from the IdP. When a user creates an app, they automatically become its owner. Ownership gives them:
- Edit access to the app’s environment variables.
- The ability to request new integrations for the app.
- Edit access to the app’s app-scope Knowledge.
- The ability to ask for the app to be suspended or restored (killing it is an Admin action).
- The ability to promote other Builders to co-owners, from the app’s detail page.
Ownership is per-app. A Builder who owns three apps can manage those three apps but cannot do anything an Admin can do.
Group-to-role mapping
Section titled “Group-to-role mapping”Once SSO is working, the Users, groups, RBAC page in the dashboard captures the mapping from IdP groups to Greenlight roles. Group → role is the source of truth: each row maps one IdP group to one Greenlight role, and a user in groups mapped to several roles holds the strongest one. The user rows are optional and double as a sign-in restriction — with none, everyone who signs in through your IdP is a Builder; with one or more, only members of a mapped group can sign in at all. Role → user is a derived view showing who currently holds each role — useful for compliance reviews and for sanity-checking after a group rename.
Group-to-role mapping applies to Entra ID and Okta. The group identifier must match what your IdP’s group claim emits: Entra ID group object IDs, or for Okta the values of your authorization server’s groups claim (usually group names). The form’s help text shows the format for your provider.
Google Workspace has no group claim, so it is not group-mapped: assign each person’s role directly on the Users page. A role you set there persists across sign-ins (it is not overwritten by any mapping).
Adding a mapping is two fields and a save: pick the IdP group, pick the role, save. The mapping is audited and takes effect for each user at their next sign-in — when mappings exist, the IdP is authoritative and each user’s role is recomputed from their groups every time they sign in, so a manual role edit lasts only until then. Removing a mapping is the same workflow — users who held the role only through that mapping lose it at their next sign-in; users who held it through other mappings retain it. The audit log captures the actor, the group, the role, and the time, so “how did user X get role Y” is answerable without reconstructing IdP history.
A typical mid-size rollout needs two rows:
| IdP group | Role | Reasoning |
|---|---|---|
| Greenlight Owners (1–3 people) | org_admin | The install owners and long-term operators. |
| IT Operations | admin | The team that handles integration requests, Knowledge curation, and incidents. |
Everyone else is a Builder automatically. Add user rows only to limit Greenlight to specific groups (for example, a staged rollout to one department). Keep it simple — additional mappings rarely add value and they complicate compliance reviews.
Agent identity
Section titled “Agent identity”A coding agent that talks to Greenlight is authenticated as a specific user. The agent acquires this binding the same way a human does — through the IdP’s standard OAuth device or authorization flow. There is no separate “agent user” account; every agent session is bound to a real person.
This is what makes the audit trail useful. When the audit log records actor.type = agent, it also records actor_id — the person the agent was acting for. The agent cannot escalate beyond what that person can do. Failed attempts to complete that OAuth binding — expired or replayed codes, PKCE mismatches, a deactivated user — write auth.authorize.failed / auth.token_exchange.failed with a stable reason, the same way failed dashboard SSO attempts do.
The same principle covers the one place an agent needs browser access: verifying a deployed app visually. An agent’s browser tooling can’t complete an interactive IdP sign-in (MFA and conditional access are designed to prevent exactly that), so the agent requests a single-use preview URL for an app its user owns. Opening it exchanges the embedded token — once, within five minutes — for a short session confined to that one app’s hostname, acting as the same real user. Minting and exchange are both audited, the session honors every revocation path (group changes, session revocation, kill switch), and SSO enforcement at the ingress is never bypassed.
Workload identity
Section titled “Workload identity”Workload identity is the credential apps use when they call the data broker. It is minted by the cluster’s identity provider per pod, signed by the cloud’s own KMS, rotated automatically, and never persisted to the Greenlight control plane. When the broker authenticates an inbound request, it verifies the workload identity against the cluster identity provider, looks up which Greenlight app that workload belongs to, and uses that mapping to find the right upstream credentials. No part of this chain is a static service-account JSON the app would read at startup.
Verify SSO
Section titled “Verify SSO”The dashboard’s installation health page includes an “SSO round-trip” probe that signs into the IdP and back to Greenlight, then verifies the resulting session has the expected claims. Run it after every IdP-side change.