README
¶
access-roster
Identity for infrastructure, self-contained. Two services and the batteries around them, so that an installation with several corporate directories can put people and machines in front of clusters, cloud accounts, consoles and code hosts — under one rule: nothing here authenticates anyone. Sign-in stays with the corporate identity providers; this repository verifies the result, knows the directory, and applies the policy.
Status: design under review; nothing runs yet. Documentation first, services second. The directory hub is built first; the issuer and the batteries follow.
Start with why this exists, then the helicopter view of every integration, then the architecture.
The batteries
Grouped by kind of artifact. The full table with status and who uses what is in docs/integrations.md.
| Kind | Battery | Use it when |
|---|---|---|
| Service + chart | directory-roster — the directory hub: holds every directory credential, snapshots every tenant, answers is this account live and who is in this group with an authoritative flag | you have corporate directories and anything that must react to leavers and groups |
| Service + chart | access-issuer — the token service: verifies a corporate sign-in, a CI token or a workload token, asks the hub, applies the policy, issues tokens | clusters, cloud accounts, a CD system or consoles must trust one issuer |
| Helm chart | access-proxy — oauth2-proxy and its wiring in front of one console: login against the issuer, sessions, forwarded bearer, two postures, self-registered client | you put a web UI behind the gateway |
| Go module | github.com/truvity/access-roster — identity with net/http, fiber v3, gRPC and connect adapters; authz; directory; tokens; policy |
you write a service or a console in Go |
| TypeScript package | access-roster — useIdentity() and <UserBadge/> over the standard /.access/whoami |
you write a console UI |
| CLI | accessctl — login, setup (kubeconfig contexts and AWS profiles for everything you are granted), aws as a credential process, kube-token, whoami; people only |
a person needs kubectl or cloud credentials |
| GitHub Action | truvity/access-roster@v1 — shell only: exchanges the job's token at the issuer, writes a kubeconfig and AWS profiles; ECR, CodeArtifact and the rest run on top with AWS's own tooling |
a workflow deploys, pushes or installs |
| File format | the policy — groups, claims, lifetimes, clients, memberships; one schema for both services, versioned, tested | always |
I want to…
| Goal | Read |
|---|---|
| connect a corporate directory (Google Workspace) | operations/connect-runbook.md |
| put a console behind the gateway | connect/console-app.md |
let people kubectl into a cluster |
connect/kubernetes-cluster.md |
| give people and jobs cloud credentials without SSO | connect/aws-account.md |
| let a workflow deploy with no stored secret | connect/github-actions.md |
| push to ECR or install from CodeArtifact, on a laptop or in a job | connect/registries-and-artifacts.md |
| sign in to ArgoCD or Kargo with the issuer | connect/argocd.md, connect/kargo.md |
| expose a business surface to employees for testing | connect/business-surface.md |
| keep GitHub teams equal to directory groups | github-roster, a consumer of the hub |
| write the policy | reference/policy.md |
| add a backend, a proof kind, a matcher, an adapter | development/extending.md |
| move off an identity provider you run for infrastructure | operations/migration-from-an-idp.md |
How it fits together, in one paragraph
An operator connects a workspace by clicking through the directory's
admin consent, or by uploading a service-account key. The hub discovers
the tenant's domains, snapshots its accounts and groups every fifteen
minutes, and answers every read from that snapshot, saying which snapshot
and whether the domain is authoritative right now. The issuer never reads
a directory: at every login it asks the hub, applies the policy, and mints
a token whose groups name the roles relying parties already read and
whose audiences carry the decisions a cloud trust policy can see. A
console sits behind access-proxy and reads the forwarded bearer through
the Go or TypeScript library; a cluster trusts the issuer and a client id;
a cloud account trusts the issuer and an audience; a workflow exchanges
its own token; a person runs accessctl. Anything that goes wrong on the
directory side degrades to "not authoritative", never to "gone".
Documentation
| Read | For |
|---|---|
| docs/why.md | motivation, principles, what it is not |
| docs/integrations.md | the helicopter view: fourteen integration points, case by case — parties, trust, flow, what you configure, what you get |
| docs/concepts.md | the ten words used precisely |
| docs/architecture.md | context, containers, the hub's components, who owns what, use cases, failure semantics |
| docs/design/ | one design per battery: hub, issuer, proxy, libraries, CLI and action |
| docs/reference/ | contracts, the policy, values of each chart, the Go module, the TypeScript package, the CLI |
| docs/connect/ | one guide per kind of relying party |
| docs/operations/ | day one, the connect runbook, the runbook, migrations |
| docs/development/ | testing, extension points |
Developing
devbox shell (or direnv), then just check. See
CONTRIBUTING.md for the layout, the conventions, the
console build order and the demonstration mode, and where the next
phase starts.
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 the token service.
|
Command access-issuer runs the token service. |
|
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
|
|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
Click to show internal directories.
Click to hide internal directories.