Jwt Principal
A jwt principal is the user or service identity read from a verified JSON Web Token. You set it up by mapping a token claim, such as a subject or email, to an app identity. Teams often use this method so services can trust logins from a central identity provider. Still, teams often map tokens to broad shared roles to save time during setup. When a token maps to an admin role, any request with that token gets full control. How a jwt principal works in your app The flow starts when a user or s
Principal: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
A jwt principal is the user or service identity read from a verified JSON Web Token. You set it up by mapping a token claim, such as a subject or email, to an app identity.
Teams often use this method so services can trust logins from a central identity provider. Still, teams often map tokens to broad shared roles to save time during setup. When a token maps to an admin role, any request with that token gets full control.
How a jwt principal works in your app
The flow starts when a user or service logs in to an identity provider. That provider checks the login and creates a signed JSON Web Token. The token holds claims that state who the user is and what groups they join.
Next, the client sends this token in the header of each request to the backend app. Your backend app reads the token and checks the digital signature against a trusted public key. It also checks the time claims to make sure the token is still valid.
Once the signature check passes, the app extracts the specific claim you chose as the identity. It turns that claim value into the active user object for that request context. The app then checks its local role rules to see what that identity can do.
Many teams map the subject claim or an email claim to build this identity object. Some setups also pull group names from the token to assign local roles on the fly. This lets teams manage user groups in one central place instead of inside every single app.
What token mapping solves and what it misses
Setting up a token identity solves the problem of checking who sent a network request. It removes the need for every backend service to store passwords or manage login forms. Services can check a signature fast and know which user or bot is calling them.
Still, token mapping only decides who logs in and which broad role they receive. It does not inspect what individual database queries, shell commands, or API payloads do in flight. Once the app accepts the identity, the user can run anything their mapped role allows.
Principal: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
This creates a gap when engineers or services need temporary access to production systems. If a token maps to a write role, it allows both safe updates and destructive deletes. Token checks also cannot mask sensitive data like emails, phone numbers, card numbers, or national IDs.
Tokens also stay valid until they expire, even if a user changes roles mid-session. If an engineer runs a bad query, the token check has already passed long ago. Teams need controls at the command and query level to keep live sessions safe.
Best practices for mapping token claims to roles
Always pick a claim that never changes for a user, such as a unique subject ID. Email addresses can change when people change names or leave a team. If you use a changing claim, a new user might inherit an old user account.
Keep the roles tied to your token identities as small and specific as possible. Do not map a whole engineering group claim to a single root database role. Split read roles from write roles so daily checks do not carry destructive power.
Set short lifetimes on your tokens so stolen tokens stop working after a few minutes. Always check the audience and issuer claims so tokens from one app cannot manage another app. Combine clean token mapping with session controls to protect your systems during every single request.
Govern statements and responses across databases and APIs
Good config and scoped roles are needed setup. They do not check single queries in flight or mask sensitive fields in returned rows. Across Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, and internal HTTP endpoints, hoop.dev runs beside each supported service as an open-source proxy, a sidecar for your database or API.
First, hoop.dev guardrails block banned queries before they run. Then hoop.dev data masking rewrites matched sensitive values in responses in memory. The audit trail records every statement and verdict per resource. Furthermore, hoop.dev holds SOC 2 Type II and is open source on GitHub.
Frequently asked questions
Which token claim should I use as the jwt principal?
Use the subject claim when you need a permanent ID that will never change over time. You can also read the email claim along with it to make audit logs easier to read.
How is a jwt principal different from a role claim?
The principal states who the actor is, such as a specific user or service account. A role claim states which group or permission set that actor holds during the session.
Can a jwt principal control which SQL queries a user runs?
No, the token only proves identity and maps the user to a database role at login. Controlling individual queries or masking fields like card numbers requires inspection of the live session traffic.