OAuth Client IP Range Metadata

1.1. Requirements Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶

1.2. Terminology

This specification uses the terms "access token", "authorization server", "client", "client authentication", "protected resource", "resource owner", "resource server", and "token endpoint" defined by OAuth 2.0 [RFC6749], and the terms "client metadata" and "software statement" defined by OAuth 2.0 Dynamic Client Registration [RFC7591].¶

This specification defines the following terms:¶

IP range set:

The set of IPv4 and IPv6 prefixes that a client declares, either by value with client_ip_ranges or by reference with client_ip_ranges_uri.¶

Client IP Range Document:

A JSON document, defined in Section 3, that contains an IP range set and is referenced by client_ip_ranges_uri.¶

client IP range metadata:

The client_ip_ranges and client_ip_ranges_uri client metadata parameters.¶

accepted IP range set:

The IP range set, if any, that an authorization server has validated, accepted, and currently uses for a client, possibly narrowed (Section 4.3).¶

2.1. Prefix Syntax

Each prefix MUST conform to the ip-prefix type defined in Section 4 of [RFC9911], that is, match in full every pattern of either the ipv4-prefix or the ipv6-prefix type. A value that does not conform is invalid.¶

The client, and the party hosting a Client IP Range Document, MUST represent each prefix in the canonical format of that type, with all bits outside the prefix length set to zero and, for IPv6, the address represented as defined in Section 4 of [RFC5952]. A value that is not in canonical format is nonetheless valid and denotes the prefix given by its network address and prefix length (Section 4 of [RFC9911]). For example, 192.0.2.1/24 denotes 192.0.2.0/24, and 2001:DB8::1/64 denotes 2001:db8::/64.¶

A prefix within the IPv4-mapped IPv6 address range ::ffff:0:0/96 (Section 2.5.5.2 of [RFC4291]) is invalid; IPv4 ranges are expressed as IPv4 prefixes. Every prefix length that the ip-prefix type permits, including zero, is valid. Whether to accept a broad prefix is local policy (Section 7.2).¶

2.2. Metadata Validation

If a trusted software statement (Section 2.3 of [RFC7591]) carries client_ip_ranges or client_ip_ranges_uri, the authorization server ignores both parameters elsewhere in the client metadata, whether in a registration request or in a Client ID Metadata Document (Section 4.3 of [CIMD]). This extends the precedence rule of Section 2 of [RFC7591] to the pair of parameters.¶

After this precedence is applied, client IP range metadata is invalid if any of the following is true:¶

1. Both client_ip_ranges and client_ip_ranges_uri are present.¶

2. The value of client_ip_ranges is not an array of strings, or any entry is an invalid prefix (Section 2.1).¶

3. The value of client_ip_ranges_uri does not meet the requirements of Section 2.¶

4. The value of client_ip_ranges has more entries than the authorization server's bound on prefixes (Section 7.5).¶

If a client registration request, or a client update request (Section 2.2 of [RFC7592]), contains invalid client IP range metadata, the authorization server responds with an HTTP 400 (Bad Request) error response as described in Section 3.2.2 of [RFC7591], using invalid_client_metadata as the error code value, or invalid_software_statement if the invalid value comes from a trusted software statement. The authorization server MUST NOT substitute a default value for invalid client IP range metadata. If a Client ID Metadata Document [CIMD] contains invalid client IP range metadata, the authorization server handles this as a validation failure (Section 4.5.1) without treating the rest of the document as invalid.¶

An authorization server that does not support these parameters ignores them (Section 2 of [RFC7591]). The client information response (Section 3.2.1 of [RFC7591]) shows whether the authorization server registered them.¶

4.1. Retrieval

An authorization server retrieves a Client IP Range Document by sending an HTTP GET request to the client_ip_ranges_uri URL, subject to Section 7.4. A response is successful if it has status code 200 (OK), the application/json media type, and a complete body within the authorization server's bounds (Section 7.5), or if it has status code 304 (Not Modified) (Section 15.4.5 of [RFC9110]) in answer to a conditional request (Section 13 of [RFC9110]). Following a 304 response, the authorization server MUST apply the same response and document validation requirements to the corresponding stored response, with its header fields updated as described in Section 4.3.4 of [RFC9111]. A 304 response for which the authorization server has no corresponding stored response is a failure.¶

The party hosting a Client IP Range Document MUST serve it with the application/json media type and MUST NOT require authentication to retrieve it unless that party and the authorization server have agreed on an authentication mechanism, which is outside the scope of this specification. The authorization server MUST NOT send credentials associated with an OAuth request, such as client credentials, access tokens, or authorization codes, when retrieving the document.¶

The authorization server MUST NOT treat a failed retrieval, an unsuccessful response, or an invalid document as an empty IP range set; each is a failure (Section 4.5.1).¶

4.2. Caching

The party hosting a Client IP Range Document SHOULD support HTTP caching [RFC9111] and SHOULD include the Cache-Control (Section 5.2 of [RFC9111]) and ETag (Section 8.8.3 of [RFC9110]) response header fields.¶

The accepted IP range set is application state, distinct from any HTTP cache (Section 6 of [RFC9111]). A fresh response does not make its IP range set accepted, and expiry of a cached response does not end use of the accepted IP range set (Section 4.3). The authorization server SHOULD retrieve the document periodically to obtain changes.¶

4.3. Acceptance

Before accepting an IP range set, the authorization server MUST ensure the following:¶

1. The client IP range metadata that conveys the set is valid (Section 2.2), and every prefix in the set is valid (Section 2.1).¶

2. If the set was obtained from a Client IP Range Document, the response is successful (Section 4.1) and the complete document is valid (Section 3).¶

If any of these checks fails, the authorization server MUST reject the entire set. Acceptance is also subject to local policy (Section 7.2). Registering client IP range metadata does not by itself accept its IP range set.¶

An accepted IP range set replaces the previously accepted IP range set in full; this specification defines no incremental update format. The accepted IP range set remains in effect until the authorization server accepts a replacement, narrows it, or stops using it (Section 4.5.3).¶

While a validated replacement awaits acceptance, an authorization server MAY narrow the accepted IP range set to its intersection with the replacement, so that it admits only source addresses that both sets match. The narrowed set remains the accepted IP range set; the replacement is still not accepted.¶

A client SHOULD add a prefix to its IP range set before it originates requests from addresses in that prefix and SHOULD keep the prefix in the set until it no longer originates requests from them.¶

4.4. Changes to Client Metadata

A client's metadata can change the value of client_ip_ranges_uri, switch between client_ip_ranges and client_ip_ranges_uri, or remove both. The new metadata replaces the previous declaration.¶

When the metadata changes representation or URL, the accepted IP range set remains in effect as described in Section 4.3. An invalid new declaration in a Client ID Metadata Document, or an unretrievable or invalid new document, is a failure (Section 4.5.1). If the previous metadata contained client_ip_ranges_uri, the authorization server MUST NOT retrieve that URL for the client while the client's current metadata does not reference it.¶

Removal of both parameters withdraws the client's declaration (Section 4.5.2). In a client update request (Section 2.2 of [RFC7592]), omitting both parameters requests their removal, which the authorization server can ignore. An empty client_ip_ranges array is different: unlike other empty values in an update request (Section 2.2 of [RFC7592]), it declares an empty IP range set, and the authorization server MUST NOT treat it as a request to delete the parameter or ignore it. The client information response (Section 3 of [RFC7592]) shows whether the parameters were removed.¶

4.5. Retention

5.1. Client Identification and Error Responses

An authorization server can enforce a client's accepted IP range set at the token endpoint and at other endpoints that receive direct requests from the client, once it has identified the client, either through client authentication or, for a public client (Section 2.1 of [RFC6749]), as the client to which a grant or token presented in the request was issued, such as an authorization code, a device code (Section 3.4 of [RFC8628]), or a refresh token. At the client configuration endpoint, the registration access token identifies the client (Section 2 of [RFC7592]). This specification does not define enforcement for a public client in a request that identifies the client only by an unauthenticated client_id, such as a device authorization request (Section 3.1 of [RFC8628]). A request rejected because of its source address does not count as a use of the authorization code it presents (Section 4.1.2 of [RFC6749]).¶

In a response to a party that has not authenticated as the client, an authorization server SHOULD NOT indicate that a request was rejected because of its source address. This specification does not yet define the error response for a request rejected because of its source address (Appendix C).¶

6.1. Enforcement Points

Enforcing the accepted IP range set of a specific client requires knowing which client sent a request. A network enforcement point that operates below HTTP, such as a firewall, observes the source address but not the client, so it can enforce only the aggregate of the IP range sets of the clients permitted to reach an endpoint. An authorization server can enforce each client's accepted IP range set once it has identified the client (Section 5.1).¶

For example, an enterprise adds a hosted client's approved ranges to the network allowlist in front of its token endpoint, and the authorization server also enforces the client's accepted IP range set. Local policy determines whether later changes are accepted automatically or require administrator approval (Section 7.2).¶

Deployments that require an accepted IP range set need an administrative recovery path for a client whose source addresses move outside that set, such as approving a replacement set. Enforcement at the client configuration endpoint (Section 2 of [RFC7592]) can prevent the client from updating a declaration made by value.¶

6.2. Retrieval Scheduling

An authorization server can retrieve documents in the background rather than while processing an OAuth request, and typically schedules the next retrieval when the stored response's freshness lifetime (Section 4.2 of [RFC9111]) ends, within local minimum and maximum intervals. A client needs to allow for these intervals, and for approval delays, when adding a prefix (Section 4.3).¶

To revalidate with If-None-Match (Section 13.1.2 of [RFC9110]), an authorization server uses the entity tag of the most recent complete response it stored from that URL (Section 4.3 of [RFC9111]), which can be newer than the one from which the accepted IP range set was derived.¶

6.3. Document Size

Section 8.7 of [CIMD] recommends that authorization servers read at most 5 kilobytes of a Client ID Metadata Document. A client whose IP range set does not fit within such a limit can use client_ip_ranges_uri. An authorization server sets its bounds on Client IP Range Documents (Section 7.5) independently of bounds on client metadata. The gzip content coding (Section 8.4.1.3 of [RFC9110]) can reduce the transfer size of large documents.¶

7.1. Trust in Declared Ranges

Client IP range metadata is a declaration made by or on behalf of the client. Inclusion of a prefix does not establish that the client exclusively owns or controls the addresses it contains. Prefixes of shared infrastructure, such as cloud provider or carrier-grade NAT egress ranges, also carry traffic from other parties.¶

Whether to use declared ranges in network access control is a local trust decision. A software statement (Section 2.3 of [RFC7591]) vouches only for the values it contains: for client_ip_ranges, the prefixes; for client_ip_ranges_uri, the URL but not the referenced document. The party hosting the document asserts its contents, and accepting them automatically is a separate decision to trust that party within an approved scope (Section 7.2). A malicious or compromised party hosting a document can also deny service to every client that references it, by publishing an empty or unrelated IP range set or by keeping the document unavailable beyond the retention limit.¶

A client cannot observe whether an authorization server enforces its declaration, so declaring an IP range set does not by itself protect the client's credentials.¶

An authorization server can require that client_ip_ranges_uri share an origin ([RFC6454]) with the client identifier URL of a Client ID Metadata Document [CIMD].¶

7.2. Changes to Declared Ranges

A change to a client's IP range set can broaden or narrow the source addresses admitted by a network policy derived from it. An authorization server MUST NOT treat the addition of a prefix to a client's IP range set as granting network access by itself. When local policy permits automatic updates for the client and the change falls within an approved scope, such as prefixes contained in supernets that the authorization server has configured for the client, the authorization server MAY accept the change automatically. Detecting unexpected expansion of a client's IP range set, including the addition of overly broad prefixes, helps an authorization server decide which changes to hold for approval. The authorization server SHOULD apply changes atomically, so that no intermediate state admits a source address that neither the previous nor the new IP range set contains.¶

An accepted IP range set that no longer matches the client's current declaration can include addresses that have since been reassigned to another party. The retention limit (Section 4.5.3) and narrowing (Section 4.3) limit how long such addresses remain admitted.¶

7.3. Rejection Responses

A rejection that a requesting party can attribute to its source address tells that party that its other inputs were acceptable. If the authorization server checks the source address only after client authentication succeeds, such a rejection confirms to a party holding stolen or guessed client credentials that they are valid. Section 5.1 limits this disclosure for parties that have not authenticated as the client; what the error response discloses to authenticated parties is part of the open issue on that response (Appendix C).¶

7.4. Server-Side Request Forgery

Retrieval of client_ip_ranges_uri causes an authorization server to send a request to a URL supplied in client metadata, which creates a risk of Server-Side Request Forgery (SSRF) attacks. When retrieving a Client IP Range Document, the following requirements apply:¶

1. The authorization server MUST NOT retrieve a URL that does not meet the requirements for client_ip_ranges_uri in Section 2.¶

2. The authorization server MUST verify the server certificate as described in Section 4.3.4 of [RFC9110] and MUST NOT accept a document retrieved over a connection that fails this verification. This strengthens the requirement of that section for automated clients.¶

3. The authorization server MUST NOT automatically follow HTTP redirects (Section 15.4 of [RFC9110]).¶

4. The authorization server MUST NOT connect to an address that the IANA special-purpose address registries ([RFC6890], [RFC8190]) list as not globally reachable, unless local policy explicitly permits that destination. This check applies to the address of each connection after DNS resolution. An authorization server that retrieves through a configured forward proxy relies on the proxy to apply this check.¶

An authorization server retrieving a URL obtained from a Client ID Metadata Document is also subject to Section 8.6 of [CIMD]; the local policy exception in item 4 does not override that section.¶

7.5. Resource Exhaustion

A malicious or compromised party hosting a Client IP Range Document can return an oversized document, a highly compressed response, or a large number of overlapping prefixes. An authorization server MUST bound retrieval time, response size, decompressed size, and the number of prefixes in an IP range set, whether conveyed by value or in a document. If a document exceeds any bound, the authorization server MUST reject the entire document. This specification sets no minimum value for any of these bounds.¶

7.6. Source Address Interpretation

Proxies, load balancers, and network address translation change the source address that an authorization server observes. The authorization server MUST determine the source address from a trusted source of connection-origin information. A source address that the authorization server cannot determine in this way matches no IP range set. The authorization server MUST NOT use a forwarding header field, such as Forwarded [RFC7239] or X-Forwarded-For, as the source address unless it was set by an intermediary the authorization server trusts. Because a trusted intermediary can append its own observation to a field that already carries entries supplied by an attacker (Section 8.1 of [RFC7239]), the authorization server MUST select the source address from such a field using its configuration of trusted proxies and MUST NOT trust an entry merely because a trusted intermediary forwarded or appended to the field.¶

10.1. Normative References

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC3986]

Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005, <https://www.rfc-editor.org/rfc/rfc3986>.

[RFC4291]

Hinden, R. and S. Deering, "IP Version 6 Addressing Architecture", RFC 4291, DOI 10.17487/RFC4291, February 2006, <https://www.rfc-editor.org/rfc/rfc4291>.

[RFC5952]

Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 Address Text Representation", RFC 5952, DOI 10.17487/RFC5952, August 2010, <https://www.rfc-editor.org/rfc/rfc5952>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC6890]

Cotton, M., Vegoda, L., Bonica, R., Ed., and B. Haberman, "Special-Purpose IP Address Registries", BCP 153, RFC 6890, DOI 10.17487/RFC6890, April 2013, <https://www.rfc-editor.org/rfc/rfc6890>.

[RFC7591]

Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/rfc/rfc7591>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8190]

Bonica, R., Cotton, M., Haberman, B., and L. Vegoda, "Updates to the Special-Purpose IP Address Registries", BCP 153, RFC 8190, DOI 10.17487/RFC8190, June 2017, <https://www.rfc-editor.org/rfc/rfc8190>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

[RFC9111]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022, <https://www.rfc-editor.org/rfc/rfc9111>.

[RFC9911]

Schönwälder, J., Ed., "Common YANG Data Types", RFC 9911, DOI 10.17487/RFC9911, December 2025, <https://www.rfc-editor.org/rfc/rfc9911>.

10.2. Informative References

[CIMD]

Parecki, A. and E. Smith, "OAuth Client ID Metadata Document", Work in Progress, Internet-Draft, draft-ietf-oauth-client-id-metadata-document-02, 6 July 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-02>.

[JAFAR]

Illyes, G., "A JSON-Based Format for Publishing IP Ranges of Automated HTTP Clients", Work in Progress, Internet-Draft, draft-illyes-webbotauth-jafar-01, 22 October 2026, <https://datatracker.ietf.org/doc/html/draft-illyes-webbotauth-jafar-01>.

[RFC6454]

Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011, <https://www.rfc-editor.org/rfc/rfc6454>.

[RFC7239]

Petersson, A. and M. Nilsson, "Forwarded HTTP Extension", RFC 7239, DOI 10.17487/RFC7239, June 2014, <https://www.rfc-editor.org/rfc/rfc7239>.

[RFC7592]

Richer, J., Ed., Jones, M., Bradley, J., and M. Machulak, "OAuth 2.0 Dynamic Client Registration Management Protocol", RFC 7592, DOI 10.17487/RFC7592, July 2015, <https://www.rfc-editor.org/rfc/rfc7592>.

[RFC8628]

Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, <https://www.rfc-editor.org/rfc/rfc8628>.

[RFC8705]

Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, <https://www.rfc-editor.org/rfc/rfc8705>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/rfc/rfc9449>.

[SSF]

Tulshibagwale, A., Cappalli, T., Scurtescu, M., Backman, A., Bradley, J., and S. Miel, "OpenID Shared Signals Framework Specification 1.0", 29 August 2025, <https://openid.net/specs/openid-sharedsignals-framework-1_0-final.html>.

A.1. Dynamic Client Registration by Value

The following is a non-normative example of a client registration request (Section 3.1 of [RFC7591]) that declares an IP range set by value:¶

POST /register HTTP/1.1
Host: server.example.com
Content-Type: application/json

{
  "client_name": "Example Client",
  "grant_types": ["client_credentials"],
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://client.example.com/jwks.json",
  "client_ip_ranges": [
    "192.0.2.0/24",
    "2001:db8:100::/48"
  ]
}

A.2. Client ID Metadata Document by Reference

The following is a non-normative example of a Client ID Metadata Document [CIMD] that declares an IP range set by reference:¶

{
  "client_id": "https://client.example.com/oauth/client.json",
  "client_name": "Example Client",
  "redirect_uris": ["https://client.example.com/callback"],
  "token_endpoint_auth_method": "private_key_jwt",
  "jwks_uri": "https://client.example.com/jwks.json",
  "client_ip_ranges_uri": "https://client.example.com/ip-ranges.json"
}

A.3. Document Retrieval

The following is a non-normative example of a request for the Client IP Range Document referenced above:¶

GET /ip-ranges.json HTTP/1.1
Host: client.example.com
Accept: application/json
Accept-Encoding: gzip

The following is a non-normative example of a successful response:¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: public, max-age=3600
ETag: "ranges-v42"

{
  "client_ip_ranges": [
    "192.0.2.0/24",
    "198.51.100.0/24",
    "2001:db8:100::/48"
  ]
}

The following non-normative example shows a later conditional request and a response indicating that the document is unchanged:¶

GET /ip-ranges.json HTTP/1.1
Host: client.example.com
Accept: application/json
Accept-Encoding: gzip
If-None-Match: "ranges-v42"

HTTP/1.1 304 Not Modified
Cache-Control: public, max-age=3600
ETag: "ranges-v42"