Skip to main content

2. Response Parameter iss

In authorization responses to the client, including error responses, an authorization server supporting this specification MUST indicate its identity by including the iss parameter in the response.

The iss parameter value is the issuer identifier of the authorization server that created the authorization response, as defined in [RFC8414]. Its value MUST be a URL that uses the "https" scheme without any query or fragment components.

2.1. Example Authorization Response​

The following example shows an authorization response from the authorization server whose issuer identifier is https://honest.as.example (extra line breaks and indentation are for display purposes only):

HTTP/1.1 302 Found
Location: https://client.example/cb?
  code=x1848ZT64p4IirMPT0R-X3141MFPTuBX-VFL_cvaplMH58
  &state=ZWVlNDBlYzA1NjdkMDNhYjg3ZjUxZjAyNGQzMTM2NzI
  &iss=https%3A%2F%2Fhonest.as.example

2.2. Example Error Response​

The following example shows an error response from the same authorization server (extra line breaks and indentation are for display purposes only):

HTTP/1.1 302 Found
Location: https://client.example/cb?
  error=access_denied
  &state=N2JjNGJhY2JiZjRhYzA3MGJkMzNmMDE5OWJhZmJhZjA
  &iss=https%3A%2F%2Fhonest.as.example

2.3. Providing the Issuer Identifier​

Authorization servers supporting this specification MUST provide their issuer identifier to enable clients to validate the iss parameter effectively.

For authorization servers publishing metadata according to [RFC8414], the following rules apply:

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

  • The server MUST indicate its support for the iss parameter by setting the metadata parameter authorization_response_iss_parameter_supported, defined in Section 3, to true.

Authorization servers MAY additionally provide the issuer identifier to clients by any other mechanism, which is outside of the scope of this specification.

2.4. Validating the Issuer Identifier​

Clients that support this specification MUST extract the value of the iss parameter from authorization responses they receive if the parameter is present. Clients MUST then decode the value from its "application/x-www-form-urlencoded" form according to Appendix B of [RFC6749] and compare the result to the issuer identifier of the authorization server where the authorization request was sent to. This comparison MUST use simple string comparison as defined in Section 6.2.1 of [RFC3986]. If the value does not match the expected issuer identifier, clients MUST reject the authorization response and MUST NOT proceed with the authorization grant. For error responses, clients MUST NOT assume that the error originates from the intended authorization server.

More precisely, 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. If OAuth metadata is not used, clients MUST use deployment-specific ways (for example, a static configuration) to decide if the returned iss value is the expected value in the current flow (see also Section 4).

If clients interact with both authorization servers supporting this specification and authorization servers not supporting this specification, clients MUST retain state about whether each authorization server supports the iss parameter. Clients MUST reject authorization responses without the iss parameter from authorization servers that do support the parameter according to the client's configuration. Clients SHOULD discard authorization responses with the iss parameter from authorization servers that do not indicate their support for the parameter. However, there might be legitimate authorization servers that provide the iss parameter without indicating their support in their metadata. Local policy or configuration can determine whether to accept such responses, and specific guidance is out of scope for this specification.

In general, clients that support this specification MAY accept authorization responses that do not contain the iss parameter or reject them and exclusively support authorization servers that provide the iss parameter in the authorization response. Local policy or configuration can determine when to accept such responses, and specific guidance is out of scope for this specification.

In OpenID Connect [OIDC.Core] flows 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.

Section 4.1.2 of [RFC6749] already mandates that clients that do not support this specification MUST ignore the unrecognized iss parameter.

Note: The "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)" [JARM] defines a mechanism that conveys all authorization response parameters in a JSON Web Token (JWT). This JWT contains an iss claim that provides the same protection if it is validated as described in Section 2.4. Therefore, an additional iss parameter outside the JWT is not necessary when JARM is used.

Last updated on