oauth2.dev

issuer

IESG

Registry Context

The `issuer` metadata value identifies the authorization server. It is required, must be an HTTPS URL without query or fragment components, and must exactly match the issuer identifier used to construct the metadata request URL.

Technical Summary

`issuer` is the required authorization server issuer identifier URL. A client compares the returned value with the issuer identifier into which the well-known URI string was inserted, using Unicode code-point equality without normalization. Metadata from a mismatching response must not be used.

When Used

Used when publishing and validating OAuth authorization server metadata. Exact matching helps prevent authorization server mix-up and impersonation attacks.

Normative Requirements

Clients

MUST NOT
1

  1. RFC 8414 - Section 3.3

    Use data contained in the metadata response when the returned `issuer` and expected issuer identifier are not identical..

    Condition: The returned `issuer` value and expected issuer identifier are not identical.

    If these values are not identical, the data contained in the response MUST NOT be used.

MUST
3

  1. RFC 8414 - Section 3.3

    Verify that the returned `issuer` value is identical to the issuer identifier into which the well-known URI string was inserted to create the metadata retrieval URL..

    Condition: When validating an authorization server metadata response.

    The "issuer" value returned MUST be identical to the authorization server's issuer identifier value into which the well-known URI string was inserted

  2. RFC 8414 - Section 6.2

    Perform TLS certificate checking when making an authorization server metadata request..

    Condition: Making an authorization server metadata request.

    TLS certificate checking MUST be performed by the client

  3. RFC 8414 - Section 6.2

    Ensure that the issuer identifier URL used as the metadata request prefix exactly matches the received `issuer` metadata value..

    Condition: Receiving an authorization server metadata document.

    the client MUST ensure that the issuer identifier URL it is using as the prefix for the metadata request exactly matches the value of the "issuer" metadata value

authorization server publishing metadata

REQUIRED
1

  1. RFC 8414 - Section 2

    Include `issuer` as the authorization server's issuer identifier URL, using the HTTPS scheme and no query or fragment components..

    REQUIRED. The authorization server's issuer identifier, which is a URL that uses the "https" scheme and has no query or fragment components.

implementation comparing the returned `issuer`

MUST NOT
1

  1. RFC 8414 - Section 4

    Apply Unicode Normalization to either the JSON string or the expected issuer identifier..

    Condition: Comparing the returned JSON `issuer` string with the expected issuer identifier.

    Unicode Normalization [USA15] MUST NOT be applied at any point to either the JSON string or the string it is to be compared against.

MUST
2

  1. RFC 8414 - Section 4

    Remove JSON-applied escaping to produce an array of Unicode code points before comparison..

    Condition: Comparing the returned JSON `issuer` string with the expected issuer identifier.

    comparisons between JSON strings and other Unicode strings MUST be performed as specified below: 1. Remove any JSON-applied escaping

  2. RFC 8414 - Section 4

    Compare the strings using Unicode code-point-to-code-point equality..

    Condition: Comparing the returned JSON `issuer` string with the expected issuer identifier.

    Comparisons between the two strings MUST be performed as a Unicode code-point-to-code-point equality comparison.

Validation Guidance

error

Require the `issuer` metadata member to be present.

error

Reject an `issuer` that does not use HTTPS or contains a query or fragment component.

error

After removing JSON-applied escaping, compare the returned `issuer` with the expected issuer identifier using Unicode code-point equality without Unicode normalization or URL normalization.

error

Do not use any metadata from a response whose `issuer` does not exactly match the issuer identifier used to construct the retrieval URL.

error

Perform TLS certificate checking for the metadata request.

Security Notes

RFC 8414 - Section 6.2

Checking that the server certificate is valid for the issuer identifier URL prevents man-in-the-middle and DNS-based attacks that could substitute attacker-controlled keys and endpoints. Exact issuer matching prevents acceptance of metadata that claims another authorization server's issuer identifier.

Reference

RFC8414 - Section 2

Details

Entry Id
issuer
Metadata Name
issuer
Metadata Description
Authorization server's issuer identifier URL
Change Controller
IESG
Reference
RFC8414 - Section 2