oauth2.dev

authorization_response_iss_parameter_supported

IETF

Registry Context

This Boolean authorization server metadata parameter indicates whether the authorization server provides the RFC 9207 iss parameter in authorization responses. If omitted, its default value is false.

Technical Summary

authorization_response_iss_parameter_supported is an OAuth authorization server metadata parameter defined by RFC 9207. An authorization server that publishes RFC 8414 metadata and supports RFC 9207 must set it to true, and its metadata issuer value must be identical to the authorization response iss value.

When Used

Used in OAuth authorization server metadata to advertise support for the authorization response iss parameter, which lets clients identify the responding authorization server and defend against mix-up attacks.

Normative Requirements

Clients

MUST NOT
3
  1. RFC 9207 - Section 2.4

    proceed with the authorization grant.

    Condition: when the iss value does not match the expected issuer identifier

    Clients [...] MUST NOT proceed with the authorization grant.

  2. RFC 9207 - Section 2.4

    assume an error response originated from the intended authorization server.

    Condition: when issuer validation fails

    For error responses, 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.

    Clients [...] MUST NOT allow multiple authorization servers to use the same issuer identifier.

MUST
12
  1. RFC 9207 - Section 2.4

    extract the iss value from a received authorization response.

    Condition: when supporting RFC 9207 and the parameter is present

    Clients that support this specification MUST extract the value of the iss parameter [...] if the parameter is present.

  2. RFC 9207 - Section 2.4

    form-decode the iss value and compare it with the expected issuer identifier.

    Condition: after extracting a present iss parameter

    Clients MUST then decode the value [...] and compare the result to the issuer identifier of the authorization server where the authorization request was sent to.

  3. RFC 9207 - Section 2.4

    use simple string comparison when comparing issuer identifiers.

    Condition: when validating the iss value

    This comparison MUST use simple string comparison as defined in Section 6.2.1 of [RFC3986].

  4. RFC 9207 - Section 2.4

    reject the authorization response.

    Condition: when the iss value does not match the expected issuer identifier

    If the value does not match the expected issuer identifier, clients MUST reject the authorization response.

  5. RFC 9207 - Section 2.4

    compare the authorization response iss value with the metadata issuer value.

    Condition: when interacting with an authorization server supporting OAuth metadata

    Clients that interact with authorization servers supporting OAuth metadata [RFC8414] MUST compare the iss parameter value to the issuer value in the server's metadata document.

  6. RFC 9207 - Section 2.4

    use deployment-specific means to determine the expected issuer value.

    Condition: when OAuth authorization server metadata is not used

    If OAuth metadata is not used, clients MUST use deployment-specific ways [...] to decide if the returned iss value is the expected value.

  7. RFC 9207 - Section 2.4

    retain per-authorization-server state indicating iss support.

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

    Clients MUST retain state about whether each authorization server supports the iss parameter.

  8. RFC 9207 - Section 2.4

    reject authorization responses that omit iss.

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

    Clients MUST reject authorization responses without the iss parameter from authorization servers that do support the parameter according to the client's configuration.

  9. RFC 9207 - Section 2.4

    require the response iss value to be identical to the ID Token iss claim.

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

    The value in the iss parameter MUST always be identical to the iss claim in the ID Token.

  10. RFC 9207 - Section 4

    validate iss precisely as specified in RFC 9207 Section 2.4.

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

  11. RFC 9207 - Section 4

    ensure accepted iss values are unique for each authorization server.

    Condition: when authorization server details can be manually configured

    The client MUST ensure that the accepted iss values are unique for each authorization server.

  12. RFC 9207 - Section 4

    reject an authorization response containing nonmatching issuer identifiers.

    Condition: when the response contains multiple issuer identifiers

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

SHOULD
1
  1. RFC 9207 - Section 2.4

    discard authorization responses containing iss.

    Condition: when the authorization server does not indicate support for iss

    Clients SHOULD discard authorization responses with the iss parameter from authorization servers that do not indicate their support for the parameter.

MAY
2
  1. RFC 9207 - Section 2.4

    accept authorization responses that omit iss.

    Condition: when supporting RFC 9207, subject to local policy or configuration

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

  2. RFC 9207 - Section 4

    omit use and verification of the standalone iss parameter.

    Condition: when the response already includes an authorization server issuer identifier by another means and that identifier is validated as specified

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

Authorization servers

MUST
5
  1. RFC 9207 - Section 2

    include the iss parameter in authorization responses, including error responses.

    Condition: when supporting RFC 9207

    An authorization server supporting this specification MUST indicate its identity by including the iss parameter in the response.

  2. RFC 9207 - Section 2

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

    Condition: when including the iss parameter

    Its 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 to clients.

    Condition: when supporting RFC 9207

    Authorization servers supporting this specification MUST provide their issuer identifier.

  4. RFC 9207 - Section 2.3

    make the metadata issuer value identical to the authorization response iss value.

    Condition: when publishing metadata according to RFC 8414

    The issuer identifier included in the server's metadata value issuer MUST be identical to the iss parameter's value.

  5. RFC 9207 - Section 2.3

    set authorization_response_iss_parameter_supported to true.

    Condition: when publishing RFC 8414 metadata and supporting RFC 9207

    The server MUST indicate its support for the iss parameter by setting the metadata parameter authorization_response_iss_parameter_supported [...] to true.

MAY
1
  1. RFC 9207 - Section 2.3

    provide the issuer identifier through another mechanism.

    Condition: in addition to the mechanism required by RFC 9207

    Authorization servers MAY additionally provide the issuer identifier to clients by any other mechanism.

Validation Guidance

error

When present, verify that authorization_response_iss_parameter_supported is Boolean; when omitted, treat it as false.

error

If an authorization server publishes RFC 8414 metadata and supports RFC 9207, verify that authorization_response_iss_parameter_supported is true.

error

For a supporting authorization server, verify that all authorization responses, including error responses, contain iss.

error

Verify that the iss value is an HTTPS URL without query or fragment components.

error

Verify that the metadata issuer value and authorization response iss value are identical.

error

Form-decode iss and compare it with the expected issuer using simple string comparison; reject mismatches and do not continue the grant.

error

When OAuth authorization server metadata is unavailable, obtain the expected issuer through deployment-specific configuration.

error

Track iss support per authorization server and reject missing iss from servers configured as supporting it.

warning

Normally discard an iss-bearing response from a server that does not indicate support, while allowing documented local policy for legitimate exceptions.

error

For OpenID Connect responses carrying an ID Token from the authorization endpoint, verify that the response iss and ID Token iss claim are identical.

error

Ensure issuer identifiers are unique across authorization servers, including manually configured servers.

error

If multiple issuer identifiers are present, reject the response unless all identifiers match.

Security Notes

RFC 9207 - Section 4

The iss parameter enables the client to associate an authorization response with the expected authorization server and its endpoints, providing a countermeasure to mix-up attacks.

RFC 9207 - Section 4

The authorization response issuer identifier is not cryptographically integrity protected, but RFC 9207 explains that this protection is not necessary specifically to defend against mix-up attacks.

Reference

Details

Entry Id
authorization_response_iss_parameter_supported
Metadata Name
authorization_response_iss_parameter_supported
Metadata Description
Boolean value indicating whether the authorization server provides the iss parameter in the authorization response.
Change Controller
IETF
Reference
RFC9207 - Section 3