README
¶
access-roster
One small OpenID provider for your infrastructure, configured from a Helm chart, with no database and no users of its own.
It reads the groups your people already have in the corporate directory and puts them in a token. Kubernetes, AWS, ArgoCD, Kargo and every console behind your gateway trust that one token. CI jobs and workloads get the same treatment from the identity token they already hold. The whole policy is one file in git, and a console shows you who holds what and why.
Nothing here authenticates anyone. Sign-in, passwords, MFA and device policy stay with Google Workspace or Entra. This verifies the result, knows the directory, and applies the policy.
The niche
Every mature identity provider can do this. None of them is built for it, and the difference is what you run to get it.
| dex | Keycloak, Zitadel, Authentik | Okta, Auth0, Entra ID | access-roster | |
|---|---|---|---|---|
| runs on | a ConfigMap | a database, an operator, a login UI you theme | someone else's cloud | a ConfigMap |
| users | none, federates | its own user store, plus federation | its own user store | none, federates |
| groups in the token | only if the upstream IdP sends them — Google does not | after you write a mapper or a login hook per IdP | after you configure a sync | read from the directory, always |
| several corporate IdPs, one issuer | yes | yes | yes | yes |
| one policy file for people and machines | no policy at all | no; roles per client, in the UI or the database | no; per-app assignments | yes, in git — and GitHub teams in the same file |
| CI and workloads without a stored secret | connectors only for people | machine users, with secrets | machine users, with secrets | token exchange from GitHub's or the cluster's own token |
| audience gating for cloud roles | no | via custom mappers | via app assignments | a requires list per client |
| who is in this group and why, at a glance | no | the admin UI, eventually | the admin UI | the directory console |
| operational footprint | tiny | large, and you own it | none, and you rent it | tiny |
dex is the right shape and stops one step short: it has no idea what groups anyone is in unless the upstream provider says, and Google never says. The heavy providers can be made to do all of it, at the cost of running an identity product to use about a fifth of one. access-roster is dex with a directory reader and a policy file.
What you get
As a person. Sign in once, at one page, with your corporate account.
Every console behind the gateway opens without another login. kubectl
works on every cluster you are granted, through kubelogin. accessctl
gives you AWS credentials for testing, ECR and the rest, with a browser
confirmation and no long-lived key. Sign out once and it ends everywhere.
As a machine. A GitHub Actions job presents the identity token it already has and receives one for AWS or a cluster, under a rule that names the repository and the ref. A workload in any cluster does the same with its ServiceAccount token. No secret is stored anywhere, and the rule sits in the same file as the human ones.
As the operator. One chart. The policy is values. The console shows every person, every directory group, every internal group, every rule that grants one, and every open session. A leaver disappears from the directory and, within the freshness window, from everything downstream.
Many in, many out, one point in the middle
| Fans in | Fans out |
|---|---|
| corporate directories: several Google Workspaces, Entra next — each a workspace with its own credential and its own served domains | Kubernetes clusters: each trusts the one issuer as its identity provider |
| GitHub Actions: one federated issuer, an owner allow-list | AWS accounts: each trusts the one issuer as an OIDC provider |
| every cluster's own ServiceAccount tokens: one row per cluster naming its key set | GitHub organisations: one controller App each, bindings in the same policy |
| consoles and applications: one client row each |
Adding one of anything is one row and one trust registration. The issuer URL, the policy file and the console never multiply.
Built today: one service, three Google Workspaces on one cluster,
four clients, workloads on any cluster proving themselves by that
cluster's published key set, a GitHub Action that needs nothing of ours
downloaded into a job, and accessctl for a laptop. Designed and
ticketed, not yet built: the second directory connector, and the GitHub
controller across organisations.
architecture.md says which
is which, per row.
The shape
flowchart LR
idp["Corporate directory<br/>Google Workspace, Entra"]
gh["GitHub Actions"]
k8s["Any cluster's<br/>ServiceAccount tokens"]
subgraph ar["access-roster"]
iss["the issuer<br/>reads the directory · applies the policy · mints tokens<br/>serves the login page and the console"]
end
proxy["access-proxy<br/>one per console with no OIDC of its own"]
apps["Kubernetes · AWS · ArgoCD · Kargo · consoles"]
idp -- "sign-in, and directory reads" --> iss
gh -- "token exchange" --> iss
k8s -- "token exchange" --> iss
iss --> proxy --> apps
iss -- "trusted by" --> apps
One service and one Valkey. A login makes no network call except to the corporate directory. The proxy is upstream oauth2-proxy in a chart, for applications that cannot run an OpenID flow themselves; anything that can, such as ArgoCD or Kargo, talks to the issuer directly.
Status. Running on one cluster with three Google Workspaces connected, three relying parties on the issuer, and the OpenID Foundation Config profile passing. CHANGELOG.md says what exists at each version, and the documents below describe what is built.
Read next
| You want to | Read |
|---|---|
| understand the ideas behind it | docs/why.md, then docs/design/trust.md |
| see every piece and how they connect | docs/architecture.md |
| learn the ten words used precisely | docs/concepts.md |
| write the policy | docs/reference/policy.md |
| deploy it | docs/reference/configuration.md, then docs/operations/connect-runbook.md |
| put a console behind the gateway | docs/connect/console-app.md |
| connect a cluster, an AWS account, a GitHub organisation, ArgoCD, Kargo, a workflow | docs/connect/ |
| run the conformance suite | docs/operations/conformance.md |
| build a service that accepts both people and workloads | docs/connect/service-to-service.md |
What ships
| Artifact | For |
|---|---|
access-issuer service and chart |
the installation, once. One process: the directory, the policy, the OpenID provider, the login page and the console |
access-proxy chart |
every console with no OpenID flow of its own |
Go module github.com/truvity/access-roster |
services and consoles in Go: verify a bearer, read the caller's groups |
TypeScript package access-roster |
console UIs: useIdentity() over /.access/whoami |
accessctl |
people on laptops: kubeconfigs and AWS credentials |
GitHub Action truvity/access-roster@v1 |
workflows: one exchange, then a kubeconfig and AWS profiles |
| the policy | one file, one schema, both services |
Developing
devbox shell (or direnv), then just check. See
CONTRIBUTING.md.
License
MIT.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package backend is the contract a directory backend implements: read-only access to one tenant's accounts, groups and domains, plus the credential handling that gets there.
|
Package backend is the contract a directory backend implements: read-only access to one tenant's accounts, groups and domains, plus the credential handling that gets there. |
|
fake
Package fake is a directory backend held in memory, with a scriptable failure for every operation.
|
Package fake is a directory backend held in memory, with a scriptable failure for every operation. |
|
google
Package google reads a Google Workspace through the Admin SDK.
|
Package google reads a Google Workspace through the Admin SDK. |
|
cmd
|
|
|
acceptance
command
Command acceptance exercises directory-roster against a real Kubernetes API server.
|
Command acceptance exercises directory-roster against a real Kubernetes API server. |
|
access-issuer
command
Command access-issuer runs access-roster.
|
Command access-issuer runs access-roster. |
|
accessctl
command
Command accessctl is what a person on a laptop runs.
|
Command accessctl is what a person on a laptop runs. |
|
directory-roster
command
Command directory-roster runs the directory hub.
|
Command directory-roster runs the directory hub. |
|
Package frontend embeds the built console, so that the hub is one binary with no static-file deployment beside it and the SPA is same-origin with the API it calls.
|
Package frontend embeds the built console, so that the hub is one binary with no static-file deployment beside it and the SPA is same-origin with the API it calls. |
|
gen
|
|
|
accessissuer/v1/accessissuerv1connect
Package accessissuer.v1 is what the issuer answers ABOUT itself, as opposed to the OpenID surface it answers protocol on.
|
Package accessissuer.v1 is what the issuer answers ABOUT itself, as opposed to the OpenID surface it answers protocol on. |
|
directory/v1/directoryv1connect
Package directory.v1 is the directory contract: liveness and flat group membership for the corporate directories an installation owns.
|
Package directory.v1 is the directory contract: liveness and flat group membership for the corporate directories an installation owns. |
|
directoryroster/v1/directoryrosterv1connect
Package directoryroster.v1 is the operator contract of the hub: the workspaces it holds credentials for, its settings, and access to the hub itself.
|
Package directoryroster.v1 is the operator contract of the hub: the workspaces it holds credentials for, its settings, and access to the hub itself. |
|
Package identity turns a token somebody else issued into the caller a listener acts on.
|
Package identity turns a token somebody else issued into the caller a listener acts on. |
|
internal
|
|
|
access
Package access decides who is at the console and what they may do.
|
Package access decides who is at the console and what they may do. |
|
app
Package app assembles the directory hub from its configuration: the stores, the snapshot cache, the backends, the policy, the connectors, the recovery path and the three listeners.
|
Package app assembles the directory hub from its configuration: the stores, the snapshot cache, the backends, the policy, the connectors, the recovery path and the three listeners. |
|
connector
Package connector turns a directory's own sign-in screen into a workspace the hub can read.
|
Package connector turns a directory's own sign-in screen into a workspace the hub can read. |
|
demo
Package demo builds the demonstration tenants the prototype runs on: fixture accounts and groups held in memory, no credential and no network, so that every use-case can be walked through before a real directory is connected.
|
Package demo builds the demonstration tenants the prototype runs on: fixture accounts and groups held in memory, no credential and no network, so that every use-case can be walked through before a real directory is connected. |
|
emailaddr
Package emailaddr splits addresses the way the hub routes them: by the domain after the last '@', lower-cased.
|
Package emailaddr splits addresses the way the hub routes them: by the domain after the last '@', lower-cased. |
|
health
Package health serves the two probes, and keeps them different.
|
Package health serves the two probes, and keeps them different. |
|
hub
Package hub is the directory hub: the workspaces it holds credentials for, the snapshots it keeps of them, the routing from an email address to the workspace that serves it, and the freshness policy that decides whether a read is answered from a snapshot or from the backend.
|
Package hub is the directory hub: the workspaces it holds credentials for, the snapshots it keeps of them, the routing from an email address to the workspace that serves it, and the freshness policy that decides whether a read is answered from a snapshot or from the backend. |
|
hubclient
Package hubclient asks the directory hub about a person.
|
Package hubclient asks the directory hub about a person. |
|
hublocal
Package hublocal asks the directory about a person by CALLING it.
|
Package hublocal asks the directory about a person by CALLING it. |
|
issuer
Package issuer is the token service: it verifies proofs produced elsewhere, applies the shared policy, and issues tokens.
|
Package issuer is the token service: it verifies proofs produced elsewhere, applies the shared policy, and issues tokens. |
|
issuerapp
Package issuerapp assembles the token service from its configuration: the policy, the door to the hub, the signing key, the verifiers that turn somebody else's token into a proof, and the OpenID surface over all of it.
|
Package issuerapp assembles the token service from its configuration: the policy, the door to the hub, the signing key, the verifiers that turn somebody else's token into a proof, and the OpenID surface over all of it. |
|
kube
Package kube keeps what a console changes in the hub's own namespace, as plain Kubernetes objects.
|
Package kube keeps what a console changes in the hub's own namespace, as plain Kubernetes objects. |
|
logsafe
Package logsafe makes a value safe to write into a log line.
|
Package logsafe makes a value safe to write into a log line. |
|
rosterapp
Package rosterapp assembles the whole of access-roster as ONE process: the directory connectors, the snapshot and its refresher, the policy, the OpenID provider, the login page and the console.
|
Package rosterapp assembles the whole of access-roster as ONE process: the directory connectors, the snapshot and its refresher, the policy, the OpenID provider, the login page and the console. |
|
server
Package server maps the hub onto its two listeners: DirectoryService for consumers on the API port, and the operator services plus the console on the console port.
|
Package server maps the hub onto its two listeners: DirectoryService for consumers on the API port, and the operator services plus the console on the console port. |
|
settings
Package settings keeps the two things an operator can change from the console: the OAuth client used for admin consent and for sign-in, and the memberships added there.
|
Package settings keeps the two things an operator can change from the console: the OAuth client used for admin consent and for sign-in, and the memberships added there. |
|
valkey
Package valkey keeps the hub's snapshots where every replica can see the same one.
|
Package valkey keeps the hub's snapshots where every replica can see the same one. |
|
verify
Package verify turns a token somebody else issued into a proof this installation will act on.
|
Package verify turns a token somebody else issued into a proof this installation will act on. |
|
version
Package version carries the build's identity, so that an operator looking at a console can say which build they are looking at without asking a cluster.
|
Package version carries the build's identity, so that an operator looking at a console can say which build they are looking at without asking a cluster. |
|
Package policy is the schema both services load: five tables that answer four questions and no others — who is in which internal group, what a group adds to a token, how long a token lives, and which client may be issued one.
|
Package policy is the schema both services load: five tables that answer four questions and no others — who is in which internal group, what a group adds to a token, how long a token lives, and which client may be issued one. |
|
Package tokens trades one token for another, and writes the two shapes a credential helper has to speak.
|
Package tokens trades one token for another, and writes the two shapes a credential helper has to speak. |