oauth2.dev

iss

IETF

Registry Context

`iss` identifies the authorization server that created an authorization response. It is also the JWT issuer claim, including when used in a JWT-secured OAuth Request Object.

Technical Summary

Under RFC 9207, `iss` is an HTTPS issuer URL included in authorization responses by supporting authorization servers and compared by clients with the expected issuer. In JWTs, `iss` is a case-sensitive StringOrURI identifying the issuer; signed Request Objects should contain `iss` and `aud`.

When Used

Authorization responses from authorization servers supporting RFC 9207, including error responses; signed JWT-secured authorization Request Objects; and JWTs generally. RFC 9207 also defines consistency rules when an ID Token is returned from the authorization endpoint.

Normative Requirements

Clients

MUST NOT
3
  1. RFC 9207 - Section 2.4

    Proceed with the authorization grant when `iss` does not match the expected issuer identifier..

    Condition: when the issuer comparison fails

    MUST NOT proceed with the authorization grant

  2. RFC 9207 - Section 2.4

    Assume that an error response originated from the intended authorization server..

    Condition: when processing an error response

    clients MUST NOT assume that the error originates from the intended authorization server

  3. RFC 9207 - Section 4

    Allow multiple authorization servers to use the same issuer identifier..

    Condition: when supporting RFC 9207

    MUST NOT allow multiple authorization servers to use the same issuer identifier

MUST
11
  1. RFC 9207 - Section 2.4

    Extract `iss` from received authorization responses when the parameter is present..

    Condition: when supporting RFC 9207

    MUST extract the value of the iss parameter

  2. RFC 9207 - Section 2.4

    Decode `iss` from its `application/x-www-form-urlencoded` form and compare it with the issuer identifier of the authorization server to which the request was sent..

    Condition: when supporting RFC 9207 and `iss` is present

    Clients MUST then decode the value

  3. RFC 9207 - Section 2.4

    Use simple string comparison when comparing issuer identifiers..

    Condition: when validating the authorization-response `iss` value

    comparison MUST use simple string comparison

  4. RFC 9207 - Section 2.4

    Reject the authorization response when `iss` does not match the expected issuer identifier..

    Condition: when the issuer comparison fails

    clients MUST reject the authorization response

  5. RFC 9207 - Section 2.4

    Compare `iss` with the `issuer` value in the authorization server's RFC 8414 metadata document..

    Condition: when interacting with an authorization server that supports RFC 8414 OAuth metadata

    MUST compare the iss parameter value to the issuer value

  6. RFC 9207 - Section 2.4

    Use a deployment-specific mechanism, such as static configuration, to determine the expected issuer..

    Condition: when RFC 8414 OAuth authorization server metadata is not used

    clients MUST use deployment-specific ways

  7. RFC 9207 - Section 2.4

    Retain state indicating whether each authorization server supports the `iss` parameter..

    Condition: when interacting with both supporting and non-supporting authorization servers

    clients MUST retain state

  8. RFC 9207 - Section 2.4

    Reject an authorization response that lacks `iss` when the authorization server is configured as supporting the parameter..

    Condition: when the authorization server supports `iss` according to client configuration

    Clients MUST reject authorization responses without the iss parameter

  9. RFC 9207 - Section 4

    Validate `iss` precisely as specified by RFC 9207 Section 2.4..

    Condition: when supporting RFC 9207

    Clients MUST validate the iss parameter precisely as described in Section 2.4

  10. RFC 9207 - Section 4

    Ensure that accepted `iss` values are unique for each authorization server..

    Condition: when authorization server details can be manually configured

    client MUST ensure that the accepted iss values are unique

  11. RFC 9207 - Section 4

    Reject an authorization response containing multiple issuer identifiers when those identifiers do not match..

    Condition: when multiple issuer identifiers are present

    client MUST reject the response if these issuer identifiers do not match

SHOULD
1
  1. RFC 9207 - Section 2.4

    Discard an authorization response containing `iss` when the authorization server does not indicate support for the parameter..

    Condition: subject to local policy for legitimate unadvertised support

    Clients SHOULD discard authorization responses with the iss parameter

MAY
1
  1. RFC 9207 - Section 2.4

    Accept authorization responses without `iss`, or reject them and support only authorization servers that provide `iss`..

    Condition: according to local policy or configuration

    clients that support this specification MAY accept authorization responses that do not contain the iss parameter

Authorization servers

MUST
6
  1. RFC 9207 - Section 2

    Indicate its identity by including the `iss` parameter in authorization responses, including error responses..

    Condition: when supporting RFC 9207

    MUST indicate its identity by including the iss parameter

  2. RFC 9207 - Section 2

    Use an `iss` value that is an HTTPS URL without query or fragment components..

    Condition: when supporting RFC 9207

    value MUST be a URL that uses the "https" scheme without any query or fragment components

  3. RFC 9207 - Section 2.3

    Provide its issuer identifier so clients can validate the `iss` parameter..

    Condition: when supporting RFC 9207

    MUST provide their issuer identifier

  4. RFC 9207 - Section 2.3

    Make the RFC 8414 metadata `issuer` value identical to the authorization-response `iss` value..

    Condition: when publishing OAuth authorization server metadata according to RFC 8414

    metadata value issuer MUST be identical to the iss parameter's value

  5. RFC 9207 - Section 2.3

    Advertise support by setting the OAuth authorization server metadata parameter `authorization_response_iss_parameter_supported` to `true`..

    Condition: when publishing OAuth authorization server metadata according to RFC 8414

    server MUST indicate its support for the iss parameter

  6. RFC 9207 - Section 2.4

    Make the authorization-response `iss` value identical to the ID Token `iss` claim..

    Condition: in an OpenID Connect flow where an ID Token is returned from the authorization endpoint

    value in the iss parameter MUST always be identical

MAY
1
  1. RFC 9207 - Section 2.3

    Additionally provide its issuer identifier to clients through another mechanism..

    Condition: when supporting RFC 9207

    MAY additionally provide the issuer identifier

Requests

MUST
2
  1. RFC 9101 - Section 4

    Represent parameter names and string values, including a string-valued `iss`, as JSON strings..

    Condition: when constructing a Request Object

    Parameter names and string values MUST be included as JSON strings

  2. RFC 9101 - Section 4

    Encode JSON strings in a Request Object using UTF-8..

    Condition: when constructing a Request Object

    these JSON strings MUST be encoded using UTF-8

SHOULD
1
  1. RFC 9101 - Section 4

    Include `iss` and `aud` claims with JWT semantics in a signed Authorization Request Object..

    Condition: when the Request Object is signed

    Authorization Request Object SHOULD contain the Claims iss (issuer) and aud (audience)

authorization server and client

MAY
1
  1. RFC 9207 - Section 4

    Omit use and verification of the `iss` response parameter when another issuer identifier is included and checked as specified in RFC 9207 Section 2.4..

    Condition: when an authorization response identifies the authorization server by another checked mechanism

    use and verification of the iss parameter is not necessary and MAY be omitted

JWT producer

OPTIONAL
1
  1. RFC 7519 - Section 4.1.1

    Include the JWT `iss` claim..

    Condition: when constructing a JWT unless another specification requires it

    Use of this claim is OPTIONAL

Validation Guidance

error

Verify that an RFC 9207-supporting authorization server includes `iss` in successful and error authorization responses and that its value is an HTTPS URL without query or fragment components.

error

When RFC 8414 OAuth authorization server metadata is published, verify that its `issuer` equals the response `iss` and that `authorization_response_iss_parameter_supported` is `true`.

error

Decode a present response `iss`, determine the expected issuer from RFC 8414 metadata or deployment-specific configuration, and compare the values using simple string comparison.

error

Reject a response whose issuer does not match and do not continue the authorization grant.

error

Do not attribute an error response to the intended authorization server until its issuer has been validated.

error

Track each authorization server's `iss` support and reject responses missing `iss` from servers configured as supporting it.

warning

Normally discard an unexpected `iss` from a server that does not advertise support, while allowing explicitly configured local policy for legitimate unadvertised support.

error

When an ID Token is returned from the authorization endpoint, verify that the response `iss` and ID Token `iss` are identical.

warning

For a signed Request Object, check for `iss` and `aud`; report their absence as a recommendation violation rather than an unconditional protocol error.

error

Represent a Request Object's string-valued `iss` as a JSON string encoded using UTF-8.

info

Treat a general JWT `iss` value as a case-sensitive StringOrURI identifying the JWT issuer; its use is optional unless another specification requires it.

error

Ensure each configured authorization server has a unique accepted issuer identifier.

error

When multiple issuer identifiers are present through `iss`, an ID Token, JARM, or another mechanism, reject the response if they do not match.

Security Notes

RFC 9207 - Section 4

The authorization-response `iss` parameter is not cryptographically integrity protected. RFC 9207 explains that this does not prevent its use as a mix-up-attack countermeasure, while JWT-secured responses such as JARM can provide integrity protection.

RFC 9207 - Section 4

Issuer identifiers must be unique per authorization server; sharing an issuer identifier prevents the client from reliably associating a response with the correct server and endpoints.

Reference

Details

Entry Id
iss
Name
iss
Parameter Usage Location
authorization request, authorization response
Change Controller
IETF
Reference
RFC9207 - Section 2, RFC9101, RFC7519 - Section 4.1.1