---
title: "How to validate the JWT iss claim and why it matters"
description: "Why skipping issuer validation is the most common JWT security mistake, and how to fix it."
url: https://workos.com/blog/how-to-validate-the-jwt-iss-claim
published: "Mar 18, 2026"
---

# How to validate the JWT iss claim and why it matters

If you work with JWTs in any capacity, you've seen the `iss` claim sitting near the top of every token payload. It's one of those fields that feels self-explanatory, it just says who issued the token, right? But in practice, the `iss` claim is one of the most frequently under-validated claims in production systems, and getting it wrong can let an attacker mint tokens that your API happily accepts.

This article covers what the `iss` claim is actually for, the specific ways developers mishandle it, and the concrete validation patterns you should implement to keep your system secure.

> **Need to inspect a token?** Use the [WorkOS JWT Debugger](https://workos.com/docs/tools/jwt-debugger) to decode and inspect your JWTs directly in the browser. It's a quick way to verify your token's `iss`, `aud`, `sub`, and other claims while debugging.

## What is `iss` in JWT?

The `iss` (issuer) claim identifies the principal that issued the JWT. As defined in RFC 7519, Section 4.1.1, its value is a case-sensitive string (typically a URL) that uniquely identifies the authorization server that created and signed the token. The `iss` claim is a mandatory claim, and must be included in every JWT.

A typical JWT payload looks like this:

```js
{
  "iss": "https://api.workos.com",
  "sub": "user_8x7k2m",
  "aud": "https://api.example.com",
  "exp": 1716249600
}
```

The `iss` claim here tells the receiving service: "This token was created by `https://https://api.workos.com`." The receiving service should verify this claim before trusting anything else in the token.

**If the issuer isn't one you explicitly trust, the token should be rejected.**

This sounds straightforward. In practice, it's where a surprising number of security bugs originate.

## Why the `iss` claim matters

Think of JWT validation like checking a passport:

- `exp` → Is it expired?
- `aud` → Is it meant for me?
- `iss` → Did a trusted authority issue it?

If you skip issuer validation, you’re basically saying: “I’ll accept a passport… from anyone who prints one.”

That’s a fast lane to security issues.

## How to validate the `iss` claim

When your backend receives a JWT, it should:

1. Extract the `iss` value.
2. Compare it against a trusted list of issuers.
3. Reject the token if it doesn’t match.

This ensures you only accept tokens from systems you explicitly trust.

## `iss` + signature validation: A duo, not a substitute

A common misconception is that if the signature is valid, you don't need to check `iss`. This is not true.

The signature is used to verify that the sender of the JWT is who they say they are and to ensure that the message wasn't tampered with along the way.

Without checking `iss`, a malicious actor could:

- Generate a valid token.
- Sign it with their own key.
- Claim to be your trusted provider.

Unless you verify the issuer, your system might accept it.

## Common mistakes with the `iss` claim

### 1. Not validating `iss` at all

The most dangerous mistake is also the most common: simply not checking the issuer. Many developers validate the signature and the `exp` claim and assume that's sufficient. It isn't.

Without issuer validation, your API will accept a validly signed token from *any* issuer, including an attacker's own authorization server. If your signature validation uses a JWKS endpoint derived from the token itself (a pattern some libraries encourage), the attacker controls both the key and the token. Your API sees a valid signature and lets them in.

Here's the vulnerable pattern:

```js
// DANGEROUS: no issuer check
const decoded = jwt.verify(token, getSigningKey);
// Proceeds to use decoded.sub for authorization
```

And here's what it should look like:

```js
// SAFE: explicit issuer validation
const decoded = jwt.verify(token, getSigningKey, {
  issuer: "https://api.workos.com"
});
```

### 2. Accepting any issuer from a dynamic list without proper controls

In multi-tenant systems, you often need to accept tokens from multiple issuers. The mistake here is building a list of trusted issuers that grows dynamically without strict controls; for example, pulling the list from a database that a tenant admin can modify, or auto-trusting any issuer that appears in a federation metadata document.

If an attacker can add their own issuer URL to your trusted list, they can issue tokens your system will accept. The trusted issuer list should be treated as a security-critical configuration, not as application data.

### 3. String matching pitfalls

The `iss` claim is a case-sensitive string. Subtle differences between `https://auth.example.com` and `https://auth.example.com/` (trailing slash) will cause validation to fail, or worse, cause you to implement a loose comparison that an attacker can exploit.

Other common string issues include scheme mismatches (`http` vs `https`), port numbers (`:443` vs omitted), and path casing. These are especially problematic when your auth provider changes their issuer URL format in an update and your hardcoded string stops matching.

### 4. Using iss to derive the JWKS endpoint without a whitelist

Some libraries and frameworks fetch the signing keys from a URL derived from the `iss` claim. For example, by appending `/.well-known/openid-configuration` to the issuer URL. This is standard OpenID Connect behavior, but it becomes a vulnerability if you don't first verify that the issuer is one you trust.

Without a whitelist check, an attacker sets `iss` to their own server, your library fetches the attacker's JWKS, and the signature validates successfully against the attacker's keys. The token is forged, but your system thinks it's legitimate.

## How `iss` interacts with other claims

The `iss` claim doesn't exist in isolation. It interacts with several other claims, and understanding these relationships is important for correct validation.

- **iss + sub:** The subject (`sub`) claim is only unique within the scope of an issuer. User `12345` from Okta and user `12345` from Azure AD are completely different people. Your user lookup should always key on the combination of `iss` and `sub`, never `sub` alone. Getting this wrong is a real identity confusion vulnerability in federated systems.
- **iss + aud:** While `iss` tells you who made the token, `aud` tells you who it's for. Both must be validated. A validly issued token from a trusted issuer is still invalid if it wasn't intended for your service. Token forwarding attacks exploit exactly this gap: a token issued for Service A gets forwarded to Service B, which accepts it because the issuer is trusted.
- **iss + kid:** The `kid` (key ID) in the JWT header tells you which specific key from the issuer's JWKS was used to sign the token. The validation flow should be: check `iss` against whitelist → fetch JWKS for that issuer → find the key matching `kid` → verify signature. Never reverse this order.

## Best practices for `iss` claim validation

1. **Always validate the issuer.** Never skip `iss` validation, even in development or internal services. Use your JWT library's built-in issuer check, don't roll your own string comparison.
2. **Maintain an explicit whitelist.** Every trusted issuer should be explicitly configured. No auto-discovery, no dynamic registration without human approval.
3. **Bind JWKS endpoints to specific issuers.** Never derive the JWKS URL from the token's `iss` claim without first checking the issuer against your whitelist.
4. **Use exact string matching.** The `iss` claim is case-sensitive. Normalize trailing slashes and schemes in your configuration, but match exactly.
5. **Combine iss + sub for user identity.** In any system that accepts tokens from multiple issuers, always use the issuer/subject pair as the user's unique identifier.
6. **Log and alert on untrusted issuers.** A token with an unrecognized issuer hitting your API is a signal worth investigating. Don't just reject silently, log it.

## Final thoughts

The `iss` claim is deceptively simple. It's just a string that says who made the token. But that simplicity hides real security weight: it's the foundation of your trust chain.

The fix isn't complicated. Validate the issuer. Maintain a whitelist. These are small engineering decisions that prevent entire categories of token forgery attacks.
