OIDC Sub Claim
The oidc sub claim is the subject value inside an identity token. It gives each user or workload a unique string under a single issuer. Platform teams read this string to map a login to a cloud role. If teams match too many subjects to one role, every user gets broad rights. A single mistake can then drop a table or expose customer data. How the oidc sub claim works in a token When a user or build job logs in, the identity provider creates a token. This token holds several fields that describ
K8s OIDC Authentication: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
The oidc sub claim is the subject value inside an identity token. It gives each user or workload a unique string under a single issuer. Platform teams read this string to map a login to a cloud role. If teams match too many subjects to one role, every user gets broad rights. A single mistake can then drop a table or expose customer data.
How the oidc sub claim works in a token
When a user or build job logs in, the identity provider creates a token. This token holds several fields that describe who logged in and when. The issuer field names the identity provider that signed the token. The subject field holds the unique ID for that specific user or job. Together, the issuer and the subject form a global ID that never repeats.
Identity providers let you choose how to build this subject string. For human users, the provider often uses a fixed internal user number. Emails can change when people change names, so fixed numbers work better. For build jobs, the provider combines the repo name, branch, and workflow name. The target system checks the signature and reads this string before granting a role.
How teams map subjects to roles
To let a workload log in without static keys, teams write trust rules. The trust rule lives in the cloud account or database system. It states which issuer to trust and which subject string to allow. When a build job runs, it sends its signed token to the cloud API. The cloud API checks the subject string against the trust rule.
If the string matches the rule, the cloud issues a short session token. The workload uses that session token to read data or run commands. Teams often use wildcards in trust rules to save time during setup. A wildcard might allow every branch or every repo in an account to match. This shortcut makes setup fast, but it creates a huge security risk.
K8s OIDC Authentication: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
Where token checks fall short at runtime
Checking the oidc sub claim solves the problem of who can log in. It replaces long-lived passwords and shared keys with signed identity tokens. Still, the token check stops working the moment the session starts. Once the user or job gets a role, the identity provider steps out. The target database or server trusts every command that role can run.
A valid login does not mean every query or command is safe. A developer with a valid token might still run a broad read query. That query could return sensitive emails, phone numbers, or card numbers in plain text. A build job might run a script that changes production rows by mistake. Token checks alone cannot inspect queries in flight or rewrite sensitive fields in results.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Can two users have the same oidc sub claim?
Within one identity provider, every user gets a unique subject string. Two different providers could use the same string, so always check the issuer field too.
Should I use email addresses as the subject value?
No, email addresses can change or get reused when someone leaves a team. A fixed user ID is safer because it stays tied to one person.
Why do wildcard subject rules cause problems for teams?
Wildcards let untrusted branches or side projects assume production roles by mistake. Always match the exact repo and branch name in your trust rules.