OIDC Groups Claim
An oidc groups claim is a token field that lists a user's team names. You set it up by telling your identity tool to add group data during log in. Most teams use this claim to map directory groups to app roles. This approach saves time because admins do not manage users one by one. Still, broad group roles often give users too much power inside target systems. A single group might grant full write rights across an entire database or server. How the oidc groups claim works in your setup OpenID
K8s OIDC Authentication: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
An oidc groups claim is a token field that lists a user's team names. You set it up by telling your identity tool to add group data during log in. Most teams use this claim to map directory groups to app roles. This approach saves time because admins do not manage users one by one. Still, broad group roles often give users too much power inside target systems. A single group might grant full write rights across an entire database or server.
How the oidc groups claim works in your setup
OpenID Connect builds on OAuth to let users log in with one identity. When a person logs in, the identity provider creates a signed JSON token. This token holds facts about the user, which are called claims. Basic claims store a user's unique ID and email address. The oidc groups claim holds a list of every team the user belongs to.
To make this work, an admin updates the identity provider settings. The admin creates a custom claim or turns on a built-in group setting. Next, the admin sets a filter so the token only includes relevant groups. Without a filter, the token might include every mailing list in the company. That makes the token too big for web headers to carry.
Once the identity provider sends the token, the target app reads it. The app checks the cryptographic signature to make sure the token is real. Then the app looks at the group names inside the payload. It matches those group names to its own local roles and permissions.
Handling token size limits and role mapping
Large companies often hit size limits when they put groups in tokens. If a user belongs to hundreds of groups, the token grows very large. Network tools and web servers often reject requests with huge headers. Some identity providers handle this by sending a link instead of a full list. The app must then make a second call to fetch the group names.
Teams can fix this issue by filtering which groups go into the token. You should only send groups that matter for that specific app. For example, a database tool only needs to see engineering and data groups. It does not need to see HR or office location groups. Keeping the group list short makes the log in process fast and reliable.
K8s OIDC Authentication: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What group claims solve and what they miss
Mapping groups through tokens solves the problem of manual account setup. When a developer joins the backend team, they get the right group right away. When they leave the company, removing them from the identity tool cuts off access. Admins do not have to log into ten different systems to delete old accounts.
Still, group claims only decide who can log in at the start. Once the app checks the token, the user gets a broad local role. The identity provider cannot see what the user does after they log in. It cannot tell if an engineer runs a safe read query or drops a table.
Also, group claims cannot hide private data inside query results. If a group grants read rights, every member sees all the rows. To protect emails, phone numbers, card numbers, or national IDs, you need deeper controls. You must check each command in flight and rewrite matched 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 sits inline in the wire protocol beside those services as an open-source proxy, a sidecar for your Postgres or API. On every query an AI agent or engineer runs against production, hoop.dev decides to pass, mask, block, or hold it for human review.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run, and hoop.dev data masking rewrites matched sensitive values in responses 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
Where does the oidc groups claim live in the token flow?
It usually lives inside the ID token or the access token as a JSON list. Some setups also return it from the user info endpoint when the app asks for it.
Why is my group list missing from the token?
Check that your app asks for the right scope during the log in call. You also need to verify that your identity tool filter matches the user's groups.
Can I use group claims for database access?
Yes, many modern databases and cloud tools can read group claims from tokens. Still, you must map those groups to database roles, which often give broad permissions.