JWT verification in Ruby: secure signing, JWKS, and claim checks

At a glance

What this is: NHI Mgmt Group's analysis, drawing on WorkOS's blog post: Securely creating, verifying, and rotating JWTs in Ruby requires emphasis on signature validation, JWKS, and claim checks.

Why it matters: It matters because JWTs often carry authentication and authorization decisions, so weak verification turns bearer tokens into a trust shortcut for application access.

Context

JWT verification in Ruby is an identity control problem, not just a coding pattern. A token only becomes a trustworthy assertion after the signature is checked and the expected issuer, audience, and expiry are validated.

The article focuses on the mechanics that make token-based identity safe in production: algorithm pinning, JWKS-backed key lookup, rotation handling, and rejecting decoded claims until verification succeeds. That is the difference between parsing a token and trusting it.

For IAM teams, the issue sits at the boundary between authentication and authorization. If that boundary is loose, downstream services can end up making access decisions from unverified assertions.

Key questions

Q: What breaks when Ruby applications decode JWTs without verifying them?

A: The application starts treating readable token content as trusted identity data, which means attacker-controlled claims can influence access decisions before any proof of authenticity exists. That failure is especially dangerous when teams use decoded payloads for user lookup, role checks, or tenant routing. Verification must come first, every time.

Q: Why do service endpoints need strict iss, aud, and exp checks for JWTs?

A: Because signature validity alone does not prove the token was intended for your service or is still usable. Issuer, audience, and expiration checks bind the token to the right trust domain and time window. Without them, a valid token can be replayed or accepted out of context.

Q: How do security teams know a JWT verification flow is too loose?

A: Warning signs include accepting tokens based on decode-only logic, failing open when claims are missing, trusting the header's algorithm, or allowing tokens to travel in URLs and logs. Any one of those patterns weakens the boundary between authentication and authorization and should be treated as a control defect.

Q: When should organisations prefer JWKS over static PEM files for JWT verification?

A: Organisations should prefer JWKS whenever multiple services need to verify tokens from the same issuer, or whenever key rotation is expected. JWKS lets verifiers select the correct key by kid, cache responses, and refresh automatically. Static PEM files are manageable only in very small environments with tightly controlled distribution.

Technical breakdown

JWT structure and what verification actually proves

A JWT has three parts: header, payload, and signature. The payload is only Base64URL-encoded, so anyone who has the token can read it, which means secrecy is not the point. Verification proves that the token was signed by the expected key and that the claims have not been altered. In Ruby, that means the verifier must not treat decoded output as trusted input until signature validation, algorithm selection, and claim checks all succeed. The jwt gem supports this directly, but the application still decides what counts as a valid issuer, audience, and expiration window.

Practical implication: never use decoded claims for authorization until signature and claim validation have both passed.

JWKS and key rotation in Ruby APIs

JWKS, or JSON Web Key Set, is the publishing model that lets verifiers fetch current public keys from a central endpoint. In distributed environments it reduces manual key distribution and makes rotation practical because services can resolve keys by kid rather than hard-coding a single public key. The Ruby jwt gem supports a JWKS loader and can refresh when it sees an unknown kid. That makes verification resilient to planned rotation, but only if the issuer publishes overlapping keys long enough for older tokens to expire and verifiers cache safely.

Practical implication: use JWKS with kid-based lookup instead of static PEM files when tokens are issued across multiple services.

Algorithm pinning and claim validation against token confusion

JWT verification fails when applications trust whatever the token header declares. Algorithm confusion attacks exploit that mistake by switching the verifier onto an unexpected signing method, such as accepting HS256 when RS256 was intended. Claim validation closes the other half of the gap: iss confirms the issuer, aud limits the intended recipient, and exp limits token lifetime. The article also highlights bearer-token handling, which matters because transport leakage turns any valid token into a reusable credential. In Ruby, the secure pattern is explicit algorithm selection plus strict claim enforcement on every protected request.

Practical implication: pin the expected algorithm and require iss, aud, and exp checks on every verification path.

Threat narrative

Attacker objective: The attacker wants an unverified or misverified bearer token to be accepted as a trusted identity assertion so they can obtain unauthorized application access.

1. Entry occurs when a service accepts a JWT that has only been decoded, not verified, so the token contents are treated as if they were already authenticated identity data.
2. Escalation occurs when the application accepts the token header's algorithm at face value or skips issuer and audience checks, allowing a crafted token to pass as legitimate.
3. Impact occurs when a replayed or confused token grants access to protected API actions or user context that the requester should not control.

Breaches seen in the wild

• Microsoft Storm-0558 key breach 2023: China-based Storm-0558 used a stolen, never-retired Microsoft signing key to forge tokens and read email at 22 organisations in 2023.

Read and download The State of NHI & AI Agent Breach Report 2026, covering 150+ breaches impacting Non-Human Identities including AI Agents.

NHI Mgmt Group analysis

Unverified JWTs create a trust boundary failure, not just a parsing bug: The article shows that a decoded token is merely structured data until the signature, algorithm, issuer, audience, and expiry checks all pass. That means the real governance problem is treating identity assertions as trustworthy before verification is complete. In IAM terms, the application has accepted an unauthenticated statement as a credential, which is exactly where authorization controls become meaningless.

JWKS turns key management into an operational dependency, not a static configuration choice: Once verification depends on public-key distribution, rotation policy becomes part of access reliability. If issuers and verifiers do not overlap old and new keys correctly, valid users lose access or stale keys linger longer than intended. Practitioners should read this as a lifecycle issue for cryptographic trust, not as a language-specific implementation detail.

Algorithm confusion is a policy failure disguised as a library feature: The dangerous assumption is that the token itself can tell the verifier how it should be checked. That assumption was designed for convenience, but it fails when an attacker can influence the verification path. The implication is that security teams need to define acceptable signing methods outside the token, then enforce that policy consistently across every service that consumes JWTs.

Bearer-token handling collapses the distance between authentication and replay: A JWT in the wrong transport location is effectively a portable credential. Query parameters, verbose logs, and long-lived access tokens all increase the blast radius when interception or leakage occurs. The practical conclusion is that token format, transport, and lifetime need to be governed as one control surface, not as separate implementation choices.

JWT verification belongs in identity architecture, not scattered endpoint logic: The article implicitly describes a control plane problem. If every controller or service performs its own partial checks, drift appears immediately and weak paths persist unnoticed. Centralized verification, strict claim policy, and clear error handling are the baseline for making token-based access governable at scale.

From our research library:

• Only 44% of developers are reported to follow security best practices for secrets management, exposing a significant developer behaviour gap, according to the State of Secrets in AppSec.
• Read next: Token and Session Security Guide

What this signals

Token verification should be treated as a shared access control layer: Once JWT handling is spread across services, drift appears in algorithm selection, claim checks, and error handling. Centralizing the logic makes the trust boundary auditable and reduces the chance that one weak path undoes the rest of the programme.

JWKS-based rotation is now a governance requirement, not a convenience feature: Teams that issue or consume signed tokens need a defined key lifecycle, including publication, overlap, and retirement. That discipline aligns directly with credential lifecycle management and keeps stale signing material from becoming a hidden trust dependency.

For practitioners

• Enforce signature verification before any authorization decision Reject any JWT that has only been decoded. Verify the signature first, then evaluate claims such as iss, aud, and exp before the request can influence access control.
• Pin the expected signing algorithm Configure the verifier to accept only the algorithm your issuer actually uses, such as RS256, and do not fall back to whatever the token header declares.
• Use JWKS with kid-based lookup Fetch public keys from a JWKS endpoint and resolve the correct key by kid so planned rotation does not force manual redeployment of verifier keys.
• Shorten token lifetime and limit bearer exposure Keep access tokens short-lived, send them only in the Authorization header, and avoid query parameters or logs that can leak reusable credentials.
• Centralize verification logic Move JWT verification into shared middleware or a Rails concern so every protected route applies the same algorithm, claim, and expiry rules.

Key takeaways

• JWT verification fails when teams trust decoded claims before the signature and expected claims have been checked.
• JWKS gives distributed systems a workable way to resolve rotating public keys without hard-coding verifier configuration.
• The main control objective is to make algorithm selection, claim validation, and key rotation consistent across every service that consumes tokens.

Key terms

• Json Web Token: A JSON Web Token is a compact, signed token that carries claims between systems so they can verify identity or authorization without consulting a central session store. In practice, its safety depends on strict validation of the signature, issuer, audience, expiry, and algorithm before any trust decision is made.
• JWKS: A JWKS, or JSON Web Key Set, is a machine-readable publishing format for public keys used by clients to verify signatures or encrypt tokens. It lets consumers fetch current key material automatically instead of relying on manual distribution, which is critical when keys rotate on a schedule.
• Claim Validation: Claim validation is the process of checking whether token fields such as issuer, audience, subject, and expiry match the expected security context. It is the control that prevents a validly signed token from being accepted in the wrong place, for the wrong system, or after its intended lifetime.
• Algorithm Confusion: Algorithm confusion is a verification failure where a service accepts a token under the wrong signing algorithm or uses token-supplied metadata to decide how to verify it. The result is forgery or unauthorised acceptance. It is a classic example of trusting attacker-controlled header data in an identity flow.

Deepen your knowledge

NHI governance, agentic AI identity, and machine identity lifecycle are core topics in our NHI Foundation Level course, the industry's only accredited NHI security programme. If you are building or maturing an IAM programme, it is worth exploring.