Reference

OAuthClient spec

Namespaced; short name oac. The namespace is the owning team.

Annotations

An application already owned by another team is never adopted; the request stays NameConflict.

Status

kubectl get oauthclients shows columns READY, TYPE, CLIENT ID, SECRET PATH, AGE.

Condition reasons

Naming rules

Policy file

requests/.policy.yaml, owned by the identity team.

teamPattern: "^team-[a-z0-9-]+$"      # regex every team directory must match
allowedRedirectHosts:                 # exact hosts, or "*.domain" for subdomains; empty allows any
  - "*.sororlab.dev"
  - localhost
  - 127.0.0.1
grantApprovals:                       # grant → label required on the PR (changed requests only)
  client_credentials: security-approved
annotationApprovals:                  # annotation → label required on the PR
  courier.sororlab.dev/adopt: identity-approved

Unknown keys are rejected.

courier validate

go run ./cmd/courier validate [flags] [requests-dir]

Exit codes: 0 valid, 1 problems found, 2 usage or load error. In GitHub Actions each problem is also printed as a file annotation.

Rules applied

• Files at <dir>/<team>/<name>.yaml; hidden files and non-YAML files are ignored
• Only courier.sororlab.dev/v1alpha1 OAuthClient objects; unknown fields rejected
• metadata.namespace equals the team directory; metadata.name equals the file name; no duplicates
• The same client rules the controller enforces (owner group, grants, redirects, name length)
• Policy: team pattern, redirect hosts, approval labels

Controller settings

Vault layout

kv/                                        # KV v2
└── teams/<team>/oauth-clients/<team>-<name>
      client_id               # always
      client_secret           # confidential clients only
      client_type             # public | confidential
      grant_types             # space-separated
      scopes                  # space-separated
      issuer
      authorization_endpoint
      token_endpoint
      jwks_uri
      userinfo_endpoint
      owner_group
      idp                     # adapter instance
      managed_by              # courier-controller
      state                   # pending | active

Auth mounts: oidc/ (role human), jwt/ (role machine), kubernetes/ (role courier). Audit device file/ at /vault/audit/audit.log.

Vault policies

path "kv/data/teams/team-alpha/*" {
  capabilities = ["read"]
}
path "kv/metadata/teams/team-alpha/*" {
  capabilities = ["read", "list"]
}
path "kv/metadata/teams/team-alpha" {
  capabilities = ["list"]
}

# write, never read
path "kv/data/teams/+/oauth-clients/*" {
  capabilities = ["create", "update", "patch"]
}
path "kv/metadata/teams/+/oauth-clients/*" {
  capabilities = ["delete"]
}

Identity groups: for every IdP group G, external group G (alias G on oidc/) and G-jwt (alias G on jwt/), both with policy G.

Objects Courier creates in the IdP

Built-in scopes map to Authentik's managed mappings (openid, email, profile, offline_access). Other scopes need an entry in the adapter's scope mapping configuration, for example groups → oauth-groups.

ArgoCD objects

Team access

Chart values (deploy/team-access/values.yaml): team (required), serviceAccountName, vault.server, vault.kvMount, vault.authMount.

ExternalSecret key for a request: teams/<team>/oauth-clients/<team>-<name> (without the kv/ mount). With dataFrom.extract, the Secret has one key per vault field.

Python sample API

Module samples/python/courier_credentials.py, requires hvac==2.4.0.

Environment: VAULT_ADDR, COURIER_VAULT_AUTH, VAULT_TOKEN, COURIER_JWT, COURIER_JWT_FILE, COURIER_SA_TOKEN_FILE, VAULT_ROLE, VAULT_NAMESPACE.

Controller image

Backstage

Template courier-oauth-client

Steps: fetch:template into requests/<team>/, then publish:github:pull-request on branch request/<team>-<name>. Output links: the pull request and the request guide.

Client entity (<name>.catalog.yml)

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: <team>-<name>
  annotations:
    backstage.io/kubernetes-namespace: <team>
    backstage.io/kubernetes-label-selector: courier.sororlab.dev/client=<name>
    courier.sororlab.dev/secret-path: kv/teams/<team>/oauth-clients/<team>-<name>
spec:
  type: oauth-client
  owner: group:default/<team>

The matching request must carry metadata.labels["courier.sororlab.dev/client"]: <name>.

Groups

backstage/catalog/teams.yaml: one Group per team, name equal to the IdP group and namespace, spec.type: courier-team, parent sororlab.