iss (Issuer) Claim in a JWT
iss identifies the party that issued the token. A verifier matches it exactly against an issuer it already trusts and uses it to pick the signing keys, which is why it is normally the first claim checked.
At a glance
- Claim
- iss (Issuer)
- Defined in
- RFC 7519 section 4.1.1
- Value type
- StringOrURI, case sensitive, most often an https URL
- Required
- Optional in RFC 7519. Required in an OpenID Connect ID token and in an RFC 9068 access token.
- Sample value
- https://auth.example.com
- In the decoder
- Explained by name, listed under Registered claims as Issuer. The validation list adds a note when a token has no iss.
In detail
The value is a StringOrURI: any string, but one containing a colon must be a URI. In practice issuers use the https URL that also serves their metadata, such as https://auth.example.com. Comparison is exact and case sensitive, and there is no URL normalization step, so a trailing slash, a different port or an uppercase host makes it a different issuer as far as a correct verifier is concerned.
iss is what tells a verifier which keys to trust. A single tenant service pins one issuer string in configuration and rejects everything else. A multi tenant service maps each accepted iss to its own key set, discovered once from the issuer metadata document described in RFC 8414 and then cached. Taking the key from inside the token instead of from the issuer is where most key injection bugs begin.
Identity is the pair of iss and sub, never sub on its own. Two issuers can hand out the same subject identifier and neither is wrong, so a user table keyed on sub alone will merge two different people the day a second identity provider is added. Store both values, and treat a change of iss on an existing account as a new account rather than a login.
The decoder lists iss under Registered claims with the label Issuer and shows the raw value beside it. It does not fetch issuer metadata or download any keys: to verify a signature you paste the shared secret or the PEM public key yourself. Nothing is uploaded, so an issuer URL from a private network is safe to look at here.
Examples
{
"iss": "https://auth.example.com",
"sub": "5f8d0c1e-9a2b-4c3d-8e7f-1a2b3c4d5e6f",
"aud": "https://api.example.com"
}The same issuer string appears in the metadata document at https://auth.example.com/.well-known/openid-configuration.
Things that catch people out
- A trailing slash is a different issuer. https://auth.example.com and https://auth.example.com/ do not match, and an issuer that changes one of them silently breaks every verifier.
- Case insensitive comparison is wrong here. StringOrURI comparison in RFC 7519 is exact, so lowercasing the value before comparing widens what you accept.
- Accepting any issuer that serves valid metadata is not validation. The set of acceptable iss values has to be a fixed list you control, not whatever the token says.
Try it: JWT Decoder
Paste a token to decode the header and payload, read the claims and expiry, and verify the signature in your browser. Nothing is uploaded.
JWT Decoder
LOCAL · Browser-OnlyDecode and inspect JSON Web Tokens without sending them to a server
Related JWT claims and algorithms
All jwt claims and algorithms →sub (Subject) Claim in a JWT
The sub claim says who the token is about. Why it is only unique within one issuer, what pairwise subjects change, and how the decoder shows it.
aud (Audience) Claim in a JWT
The aud claim names who a token is for. Why every API must check it, how the string and array forms differ, and what the decoder shows.
kid (Key ID) Header Parameter in a JWT
The kid header says which key signed a token. How rotation depends on it, why the value must be a lookup and never a path, and decoder behaviour.
exp (Expiration Time) Claim in a JWT
The exp claim sets when a JWT stops being accepted. NumericDate format, clock skew allowances, and the four expiry states the decoder shows.
nbf (Not Before) Claim in a JWT
The nbf claim marks the earliest time a JWT may be accepted. When a not before time is worth setting, and how the decoder flags a future one.
iat (Issued At) Claim in a JWT
The iat claim records when a JWT was created. What it is good for, why it is not an expiry, and the age and lifetime figures the decoder derives.
Tools for this
- JWT Decoder Free online JWT decoder - decode and inspect JSON Web Tokens without sending them to a server