<?xml version="1.0" encoding="utf-8"?>
<rfc version="3" ipr="trust200902" updates="8620" docName="draft-ietf-mailmaint-oauth-public-07" submissionType="IETF" category="info" xml:lang="en" xmlns:xi="http://www.w3.org/2001/XInclude" indexInclude="true" consensus="true">

<front>
<title abbrev="OAuth for Native Clients">OAuth Profile for Native Clients of Open Protocols</title><seriesInfo value="draft-ietf-mailmaint-oauth-public-07" stream="IETF" status="informational" name="Internet-Draft"></seriesInfo>
<author role="editor" initials="N.M." surname="Jenkins" fullname="Neil Jenkins">
  <organization>Fastmail</organization>
  <address>
    <postal>
    <street>PO Box 234, Collins St West</street>
    <city>Melbourne</city>
    <code>VIC 8007</code>
    <country>Australia</country>
  </postal>
  <email>neilj@fastmailteam.com</email>
  <uri>https://www.fastmail.com</uri>
  </address>
</author>
<author fullname="Ben Bucksch">
    <organization>Beonex</organization>
    <address>
      <email>ben.bucksch@beonex.com</email>
    </address>
</author>
<date/>
<area>ART</area>
<workgroup>Mail Maintenance</workgroup>
<keyword>OAuth</keyword>
<keyword>IMAP</keyword>
<keyword>JMAP</keyword>
<keyword>SMTP</keyword>
<keyword>POP</keyword>
<keyword>CardDAV</keyword>
<keyword>CalDAV</keyword>

<abstract>
<t>This document specifies a profile of the OAuth authorization protocol to allow for interoperability between native clients and servers using open protocols, such as JMAP, IMAP, SMTP, POP, CalDAV, and CardDAV. The profile is restricted to native clients, that is, applications installed and run on the end user's device. It deliberately does not support web-based clients, which cannot complete the flow as specified. This document updates RFC 8620 by adding a column for interoperable OAuth scopes to the JMAP Capabilities registry.</t>
</abstract>

</front>

<middle>

<section anchor="introduction"><name>Introduction</name>
<t>This document pulls together several existing standards and uses them to specify a specific OAuth profile, allowing interoperable modern authentication for native clients of open protocols, such as JMAP, IMAP, SMTP, POP, CalDAV, and CardDAV. For these protocols, there are many servers and many clients with no pre-existing relationship, that need to be able to connect. At the moment, the only interoperable way to do so is with a basic username and password, which has many deficiencies from a security standpoint.</t>

<section anchor="notational-conventions"><name>Notational Conventions</name>
<t>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 <xref target="RFC2119" /> <xref target="RFC8174" /> when, and only when, they appear in all capitals, as shown here.</t>
</section>

<section anchor="native-clients-only"><name>Applicability to Native Clients Only</name>
<t>This profile applies only to native clients: applications that are installed and executed on the end user's device, as described in <xref target="RFC8252" />. Web-based clients, that is, clients that run in a web browser or on a web server, are out of scope for this document.</t>
<t>This restriction is deliberate. The profile allows any client to register with any server without a pre-existing relationship (see <xref target="dynamic-client-registration" />), and there is no way for the server to verify any of the information supplied during that registration. For a native client, this does not introduce a new risk. A malicious application that the user has already installed and run could spoof the user's browser to phish their credentials, or, in unsandboxed environments, install malware. Allowing it to complete an OAuth flow therefore makes the user no worse off. Indeed, it is more secure, as the alternative is a legitimate client storing the user's password.</t>
<t>Just navigating to a web page, however, is a different security scenario. Allowing arbitrary web-based clients to seamlessly register and obtain authorization would make it substantially easier for phishing sites to gain access to a user's account. A phishing site could send the user through a legitimate OAuth flow at the real authorization server, and then receive the resulting tokens.</t>
<t>The profile therefore enforces this restriction by limiting the redirect URIs that may be registered to loopback addresses (<xref target="RFC8252" section="7.3" />) and private-use URI schemes (<xref target="RFC8252" section="7.1" />), which can only be received by software running on the user's device. See <xref target="redirect-uri-requirements" /> for the specific requirements and <xref target="security-considerations" /> for further discussion.</t>
<t>Native clients are public clients in OAuth terminology (<xref target="RFC6749" section="2.1" />). The client software is distributed to and runs on end users' devices, so it cannot hold a client secret that is kept confidential from those users. "Public" refers only to this property; each client instance is typically used by a single user to access their own account.</t>
</section>

<section anchor="overview"><name>Protocol Overview</name>
<t>OAuth 2 <xref target="RFC6749" /> can be used in many different ways. This document specifies one particular set of options to ensure interoperability and security. Servers may implement more options, but MUST support the flow as described in this document for interoperability with clients. Similarly, clients may choose to support additional flows but there is no guarantee that this will be interoperable.</t>
<t anchor="presumptions">This profile presumes a deployment has a set of one or more resource server endpoints (e.g., for JMAP/IMAP/SMTP/POP/CardDAV/CalDAV), and a common authorization server issuer identifier for all of them. For example, a deployment might have a JMAP session endpoint <tt>https://api.example.com/jmap/session</tt>, an IMAP endpoint <tt>imap.example.com</tt>, and an issuer identifier <tt>https://auth.example.com/acmeinc</tt>.</t>
<t>The protocol involves four parties: the client instance (a single installation of the client software on the user's device), the user-agent (normally the user's web browser), the authorization server, and the resource servers the client instance wishes to access. <xref target="fig-overview" /> shows the messages exchanged between them.</t>

<figure anchor="fig-overview"><name>Protocol Overview</name>
<artwork type="ascii-art"><![CDATA[
  Client          User-Agent         Authorization         Resource
 Instance          (Browser)            Server              Server
     |                 |                   |                   |
     | (1) Discover issuer (if needed)     |                   |
     |-------------------------------------------------------->|
     |<--------------------------------------------------------|
     |                 |                   |                   |
     | (2) Fetch metadata                  |                   |
     |------------------------------------>|                   |
     |<------------------------------------|                   |
     |                 |                   |                   |
     | (3) Register    |                   |                   |
     |------------------------------------>|                   |
     |<-- client_id -----------------------|                   |
     |                 |                   |                   |
     | (4) Open        |                   |                   |
     | authorization   |                   |                   |
     | request         |                   |                   |
     |---------------->|                   |                   |
     |                 |                   |                   |
     |                 | (5) Authenticate  |                   |
     |                 | and grant access  |                   |
     |                 |------------------>|                   |
     |                 |<------------------|                   |
     |                 |                   |                   |
     | (6) Redirect    |                   |                   |
     | with code       |                   |                   |
     |<----------------|                   |                   |
     |                 |                   |                   |
     | (7) Exchange code for tokens        |                   |
     |------------------------------------>|                   |
     |<-- access + refresh tokens ---------|                   |
     |                 |                   |                   |
     | (8) Access resources with access token                  |
     |-------------------------------------------------------->|
     |<--------------------------------------------------------|
     |                 |                   |                   |
     | (9) Refresh access token            |                   |
     |--- refresh token ------------------>|                   |
     |<-- new access token ----------------|                   |
]]></artwork>
</figure>

<t>The steps are as follows:</t>

<ol>
<li>The client instance discovers the authorization server's issuer identifier, either from autoconfiguration or user input, or by querying a resource server (<xref target="getting-the-issuer-identifier" />).</li>
<li>The OAuth 2.0 Authorization Server Metadata <xref target="RFC8414" /> is fetched (<xref target="fetching-the-authorization-server-data" />).</li>
<li>The client instance registers with the authorization server to get a client id using the OAuth 2.0 Dynamic Client Registration Protocol <xref target="RFC7591" /> (<xref target="dynamic-client-registration" />).</li>
<li>The client instance opens an authorization request in the user's browser (<xref target="authorization-request" /> and <xref target="user-agent-requirements" />). It authorizes using the Authorization Code Grant flow (<xref target="RFC6749" section="4.1" />) with PKCE <xref target="RFC7636" /> and Issuer Identification <xref target="RFC9207" />. The client instance also includes Resource Indicators <xref target="RFC8707" /> in the authorization request. Server support for Resource Indicators is RECOMMENDED but not required. An authorization server that does not support them ignores the unrecognized parameters (as required by <xref target="RFC6749" section="3.1" />), and the flow proceeds without them. The client instance then relies on the rules in <xref target="permitted-resource-servers" /> to decide which resource servers it may send access tokens to. The consequences of this are discussed in <xref target="resource-indicators" />, <xref target="permitted-resource-servers" />, and <xref target="security-considerations" />.</li>
<li>The authorization server authenticates the user and asks them to grant access to the client (<xref target="authorization-processing" />).</li>
<li>The authorization server redirects the user-agent back to the client instance with an authorization code. The client instance verifies the response (<xref target="authorization-response" />).</li>
<li>The client instance exchanges the authorization code for an access token and refresh token, as per <xref target="RFC6749" section="4.1.3" /> (<xref target="tokens" />).</li>
<li>The access token is used to authenticate requests to the resource servers, as per <xref target="RFC6750" /> (or <xref target="RFC9449" /> if using DPoP) for HTTP requests, or <xref target="RFC7628" /> for SASL authentication (<xref target="using-access-tokens" />).</li>
<li>When the access token expires, a new one is requested using the refresh token, as per <xref target="RFC6749" section="6"/> (<xref target="getting-a-new-access-token" />).</li>
</ol>
<t>The rest of this document describes in detail each of the above steps.</t>
</section>

</section>

<section anchor="getting-the-issuer-identifier"><name>Discovering the Authorization Server</name>
<t>The endpoints may be discovered via an autoconfiguration mechanism, such as <xref target="I-D.ietf-mailmaint-pacc" />, or via manual user input. Autoconfiguration may also include the issuer identifier.</t>

<section anchor="issuer-discovery-http"><name>HTTP-Based Protocols</name>
<t>HTTP endpoints that support this profile MUST support <xref target="RFC9728">Protected Resource Metadata</xref>, accessible via the <tt>oauth-protected-resource</tt> well-known path, as specified in <xref target="RFC9728" section="3" />. This allows OAuth to be configured when the endpoints were entered manually, or when the autoconfiguration data does not include the issuer identifier. The <tt>authorization_servers</tt> property MUST be present in the resource metadata. Servers SHOULD list exactly one issuer identifier, that of the authorization server to be used with this profile; if more than one is listed, the client instance MUST use the first. HTTP requests made without valid authentication to the resource endpoints MUST indicate the protected resource metadata URL in the <tt>resource_metadata</tt> parameter of the <tt>WWW-Authenticate</tt> HTTP response header field, as described in <xref target="RFC9728" section="5.1" />.</t>
<t>A client instance that needs the issuer identifier for an HTTP endpoint SHOULD obtain the metadata URL by making a request to the endpoint without credentials and reading the <tt>resource_metadata</tt> parameter from the <tt>WWW-Authenticate</tt> header field of the response. This works for endpoints whose own path is a well-known path, such as <tt>https://caldav.example.com/.well-known/caldav</tt>. It also works for endpoints that redirect during service discovery, as is common for CalDAV and CardDAV: the client instance follows the redirects as it normally would, and reads the header field from the final response. If the header field is absent, the client instance MAY instead construct the metadata URL from the endpoint URL as described in <xref target="RFC9728" section="3.1" />. The client instance MUST NOT follow HTTP redirects when fetching the metadata document itself.</t>
<t>In either case, the client instance MUST validate the metadata as required by <xref target="RFC9728" section="3.3" />. If the metadata URL was obtained from the <tt>WWW-Authenticate</tt> header field, the <tt>resource</tt> property MUST be identical to the URL of the request that returned that header field. If the metadata URL was constructed, the <tt>resource</tt> property MUST be identical to the endpoint URL into which the well-known path was inserted. If it is not, the metadata MUST NOT be used. This check ensures that a redirect or a misconfigured server cannot cause the client instance to use metadata that describes some other resource.</t>
</section>

<section anchor="issuer-discovery-sasl"><name>IMAP, POP, and SMTP</name>
<t>Protected Resource Metadata is only available for HTTP-based endpoints. For IMAP, POP, and SMTP, the equivalent in-protocol mechanism is the <tt>openid-configuration</tt> field of the OAUTHBEARER failed-authentication response (<xref target="RFC7628" section="3.2.2" />). Servers offering these protocols under this profile MUST include this field in every failed OAUTHBEARER response, with the URL of the authorization server metadata document, in either of the forms described in <xref target="metadata-fetching" />. <xref target="RFC7628" /> defines this field as the URL of an OpenID Connect Discovery document; this profile also permits the URL of an RFC 8414 metadata document.</t>
<t>A client instance that has not obtained the issuer identifier from autoconfiguration or the user MAY discover it as follows. The client instance connects to the endpoint over TLS, and attempts OAUTHBEARER authentication with a syntactically valid but deliberately invalid token. It then reads this field from the failure response. If the URL does not use the <tt>https</tt> scheme, the client instance MUST NOT use it. Otherwise, the client instance MUST then fetch the document at that URL, without following redirects (as in <xref target="metadata-fetching" />), and take its <tt>issuer</tt> property as the issuer identifier. It MUST then discard the fetched document, and proceed as described in <xref target="metadata-fetching" /> starting from the issuer identifier alone. This ensures the metadata used is subject to every check in this document, regardless of the URL to which the field pointed. As with autoconfiguration data and protected resource metadata, the URL is supplied by a server that may itself be counterfeit, and the protections of <xref target="permitted-resource-servers" /> apply.</t>
</section>
</section>

<section anchor="fetching-the-authorization-server-data"><name>Authorization Server Metadata</name>

<section anchor="metadata-fetching"><name>Fetching the Metadata</name>
<t>The authorization server issuer identifier MUST be an HTTPS URL with no userinfo, query, or fragment component. If a path is present, it MUST NOT contain <tt>.</tt> or <tt>..</tt> segments, and MUST NOT use percent-encoding for unreserved characters (as defined in <xref target="RFC3986" section="2.3" />). If the issuer identifier does not conform to these requirements, the flow MUST be aborted. Note that <tt>https://auth.example.com</tt> and <tt>https://auth.example.com/</tt> are both permitted, but they are distinct issuer identifiers: clients do not normalize one to the other, and the <tt>issuer</tt> metadata property (see <xref target="metadata-required-properties" />) must match exactly whichever form was used. The authorization server metadata MUST first be fetched as specified in <xref target="RFC8414" section="3" /> by constructing a URL that places <tt>/.well-known/oauth-authorization-server</tt> after the host and before any path. For example, for an issuer identifier of <tt>https://auth.example.com/acmeinc</tt>, the authorization server metadata would be fetched from <tt>https://auth.example.com/.well-known/oauth-authorization-server/acmeinc</tt>.</t>
<t>If this request does not result in a successful response (a 200 OK HTTP status code with an "application/json" content type), the client MUST also try the OpenID Connect Discovery <xref target="OpenID.Discovery" /> metadata path. This is constructed by appending <tt>/.well-known/openid-configuration</tt> to the issuer identifier after stripping any trailing slash. For example, for an issuer identifier of <tt>https://auth.example.com/acmeinc</tt>, this would be <tt>https://auth.example.com/acmeinc/.well-known/openid-configuration</tt>. This fallback is necessary for compatibility with existing deployments that only serve metadata at the OpenID Connect path. See <xref target="security-considerations" /> for a discussion of the security implications of this fallback.</t>
<t>A successful response is indicated by a 200 OK HTTP status code. The response MUST have an "application/json" content type. If neither metadata path results in a successful response, the flow MUST be aborted. Clients MUST NOT follow HTTP redirects when fetching the metadata; a redirect MUST be treated the same as an error response.</t>
</section>

<section anchor="metadata-required-properties"><name>Required Properties</name>
<t>The authorization server metadata is a JSON document with properties as specified in <xref target="RFC8414" />. It MUST include the following properties:</t>

<dl spacing="normal" newline="true">
<dt><tt>issuer</tt></dt>
<dd><t>The authorization server's issuer identifier. This MUST be identical to the issuer identifier from which this metadata URL was derived — not the URL from which it was fetched. For example, if the issuer identifier is <tt>https://auth.example.com/acmeinc</tt>, the issuer property MUST be <tt>https://auth.example.com/acmeinc</tt>, regardless of whether the metadata was fetched from <tt>https://auth.example.com/.well-known/oauth-authorization-server/acmeinc</tt> or <tt>https://auth.example.com/acmeinc/.well-known/openid-configuration</tt>. If not, the flow MUST be aborted.</t>
<t>This MUST be verified again during the authorization flow (see <xref target="authorization-response" />, or <xref target="RFC9207" /> for more details), to protect against mix-up attacks.</t>
</dd>
<dt><tt>registration_endpoint</tt></dt>
<dd><t>The URL the client instance will use to register, to get a client id it needs for authorization (see <xref target="dynamic-client-registration" />).</t>
</dd>
<dt><tt>authorization_endpoint</tt></dt>
<dd><t>The URL the client instance will use to start the authorization process (see <xref target="authorization" />) once it has registered.</t>
</dd>
<dt><tt>token_endpoint</tt></dt>
<dd><t>The URL the client instance will use to get refresh and access tokens after successful authorization (see <xref target="tokens" />).</t>
</dd>
<dt><tt>scopes_supported</tt></dt>
<dd><t>An array of supported scopes on the server (see <xref target="scopes" />).</t>
</dd>
<dt><tt>response_types_supported</tt></dt>
<dd><t>A list of response types supported in the OAuth authorization flow. This is an array of strings that MUST include "code".</t>
</dd>
<dt><tt>grant_types_supported</tt></dt>
<dd><t>A list of the OAuth 2.0 grant type values that this authorization server supports. This is an array of strings that MUST include "authorization_code" and "refresh_token".</t>
</dd>
<dt><tt>token_endpoint_auth_methods_supported</tt></dt>
<dd><t>This is an array of strings that MUST include "none".</t>
</dd>
<dt><tt>code_challenge_methods_supported</tt></dt>
<dd><t>An array of strings listing Proof Key for Code Exchange (PKCE) <xref target="RFC7636" />
code challenge methods supported by this authorization server.
This MUST include "S256".</t>
</dd>
<dt><tt>authorization_response_iss_parameter_supported</tt></dt>
<dd><t>This MUST have the boolean value true.</t>
</dd>
</dl>
</section>

<section anchor="metadata-optional-properties"><name>Conditional and Optional Properties</name>
<t>This section describes metadata properties that are required only in some circumstances, or are optional.</t>

<section anchor="metadata-protected-resources"><name>Protected Resources</name>
<t>Servers MUST include the following property if either of these conditions applies:</t>
<ul spacing="compact">
<li>Any resource server accessed via this profile, other than one reached only through a service-supplied endpoint URL (see <xref target="service-supplied-endpoints" />), does not share the registrable domain of the issuer identifier (see <xref target="permitted-resource-servers" />).</li>
<li>The server requires Resource Indicators <xref target="RFC8707" />, that is, it will not issue a usable access token unless the authorization request includes <tt>resource</tt> parameters.</li>
</ul>
<t>All other servers that support Resource Indicators SHOULD include it:</t>

<dl spacing="normal" newline="true">
<dt><tt>protected_resources</tt></dt>
<dd><t>A JSON array of strings, as defined in <xref target="RFC9728" section="4" />, listing all of the resource indicator values that may be used with this authorization server for resources accessed via this profile. Clients use this list to determine the <tt>resource</tt> values to send in the authorization request (see <xref target="resource-indicators" />). For HTTP-based protocols, each entry is an <tt>https</tt> URL with no query or fragment part that identifies a resource server, or a path within one, for example <tt>https://api.example.com</tt> or <tt>https://caldav.example.com/dav</tt>. Entries are matched against resource locations as described in <xref target="resource-indicators" />. For non-HTTP protocols, each entry is a hostname with no scheme or port, for example <tt>imap.example.com</tt>. <xref target="RFC9728" section="4" /> defines the entries of this array as resource identifiers, which <xref target="RFC9728" section="1.2" /> restricts to <tt>https</tt> URLs. This profile deviates from that restriction for non-HTTP protocols, for the reasons given in <xref target="resource-indicators" />.</t>
<t><xref target="RFC9728" /> permits an authorization server to omit some of its protected resources from this list. This profile is stricter: if the property is present, it MUST include an entry matching every resource endpoint that may be accessed using this profile, other than those reached only through service-supplied endpoint URLs (see <xref target="service-supplied-endpoints" />). This is because a client can only send resource indicators for endpoints that it can match against the list.</t></dd>
</dl>
</section>

<section anchor="metadata-dpop"><name>DPoP</name>
<t>It is RECOMMENDED servers support DPoP (<xref target="RFC9449" />) to allow sender-constrained refresh and access tokens for HTTP-based protocols. Servers that support DPoP MUST include the following property:</t>

<dl spacing="normal" newline="true">
<dt><tt>dpop_signing_alg_values_supported</tt></dt>
<dd>A JSON array containing a list of the JWS alg values (from the <xref target="IANA.JOSE.ALGS" /> registry) supported by the authorization server for DPoP proof JWTs, as defined in <xref target="RFC9449" />, Section 5.1.</dd>
</dl>
</section>

<section anchor="metadata-revocation"><name>Token Revocation</name>
<t>Also of possible interest to client/server implementers following this document:</t>

<dl spacing="normal" newline="true">
<dt><tt>revocation_endpoint</tt></dt>
<dd>The URL the client instance can use to revoke its tokens, as per <xref target="RFC7009" />.</dd>
<dt><tt>revocation_endpoint_auth_methods_supported</tt></dt>
<dd>If a revocation_endpoint is included, this property MUST be included, and is an array of strings that MUST include "none".</dd>
</dl>
</section>
</section>

<section anchor="metadata-validation"><name>Validating the Metadata</name>
<t>Clients MUST verify that all of the properties listed in <xref target="metadata-required-properties" /> are present and conform to the requirements of this document. If any of them is missing or does not conform, the server is not using OAuth in conformance with this document, and the client MUST abort the flow.</t>
<t>Clients MUST also verify that the values of the <tt>registration_endpoint</tt>, <tt>authorization_endpoint</tt>, and <tt>token_endpoint</tt> properties, and of the <tt>revocation_endpoint</tt> property if present, are all URLs with the <tt>https</tt> scheme. If any of these values does not use the <tt>https</tt> scheme, the client MUST abort the flow. This is required because the client instance will send authorization codes and refresh tokens to these endpoints.</t>
<t>The metadata MAY include other properties, or other values for multi-valued properties, however clients are not required to understand or use any of them for interoperability.</t>
</section>
</section>

<section anchor="dynamic-client-registration">
<name>Dynamic Client Registration</name>

<section anchor="registration-request"><name>Registration Request</name>
<t>The client registration endpoint MUST accept registration requests that carry no initial access token or other form of authentication (open registration, see <xref target="RFC7591" section="3" />), since a client instance following this profile has no pre-existing relationship with the server.</t>
<t>To register, the client instance sends an HTTP POST to the client registration endpoint (as found in the metadata) with a content type of "application/json", and a body consisting of a JSON document with the following properties. The <tt>client_uri</tt>, <tt>logo_uri</tt>, <tt>tos_uri</tt>, <tt>policy_uri</tt>, <tt>software_id</tt>, and <tt>software_version</tt> properties are OPTIONAL, but client instances SHOULD include them wherever the information is available. All other properties in the list below MUST be included.</t>

<dl spacing="normal" newline="true">
<dt><tt>redirect_uris</tt></dt>
<dd>An array of URIs the client instance may use to receive back information at the end of the authorization flow. Each URI MUST satisfy the requirements in <xref target="redirect-uri-requirements" />.</dd>
<dt><tt>token_endpoint_auth_method</tt></dt>
<dd>This MUST be "none".</dd>
<dt><tt>grant_types</tt></dt>
<dd>This is an array of strings that MUST include "authorization_code" and "refresh_token".</dd>
<dt><tt>response_types</tt></dt>
<dd>This is an array of strings that MUST include "code".</dd>
<dt><tt>scope</tt></dt>
<dd><t>A string containing a space-separated list of scope values the client may request access for. (Note! This is not a JSON array.)</t></dd>
<dt><tt>client_name</tt></dt>
<dd>The name of the client software to be presented to the end-user during authorization.</dd>
<dt><tt>client_uri</tt></dt>
<dd>A URL for a web page providing information about the client software. This MUST use HTTPS.</dd>
<dt><tt>logo_uri</tt></dt>
<dd>A URL for a logo to display for this client software. This SHOULD be square, and in a PNG or SVG image format. This MUST use HTTPS.</dd>
<dt><tt>tos_uri</tt></dt>
<dd>A URL that points to a human-readable terms of service or license document for the client software. This MUST use HTTPS.</dd>
<dt><tt>policy_uri</tt></dt>
<dd>A URL that points to a human-readable privacy policy document for the client software. This MUST use HTTPS.</dd>
<dt><tt>software_id</tt></dt>
<dd>A unique identifier string (e.g., a Universally Unique Identifier
  (UUID)) assigned by the client developer or software publisher, used by
  registration endpoints to identify the client software doing the
  dynamic registration.  Unlike "client_id", which is issued by the
  authorization server and may vary between instances, the
  "software_id" SHOULD remain the same for all instances of the client
  software.  The "software_id" SHOULD remain the same across multiple
  updates or versions of the same piece of software. The value of this
  field is not intended to be human readable and is usually opaque to the
  client and authorization server.</dd>
<dt><tt>software_version</tt></dt>
<dd>A version identifier string for the client software identified by
  "software_id".  The value of the "software_version" SHOULD change on
  any update to the client software identified by the same
  "software_id".  The value of this field is intended to be compared
  using string equality matching and no other comparison semantics are
  defined by this specification.</dd>
</dl>
<t>For compatibility with servers implementing OpenID Connect Core <xref target="OpenID.Core" />, if the server advertised the <tt>offline_access</tt> scope in the "scopes_supported" property of the authorization server metadata, the client instance MUST also register for this scope.</t>
<t>If the server indicated in its metadata that it supports DPoP <xref target="RFC9449" /> and the client instance is intending to authenticate all requests using DPoP, the client instance SHOULD also include the following property, with the value <tt>true</tt>:</t>

<dl spacing="normal" newline="true">
<dt><tt>dpop_bound_access_tokens</tt></dt>
<dd><t>A boolean, as defined in <xref target="RFC9449" section="5.2" />. If the property is omitted, the value is <tt>false</tt>.</t>
<t>If the value is <tt>true</tt>, the server MUST require every token request for the issued client id to include a DPoP proof, and MUST issue only DPoP-bound access tokens, as specified in <xref target="RFC9449" section="5.2" />.</t>
<t>DPoP is only defined for HTTP, so a client instance that uses non-HTTP protocols such as IMAP, POP, or SMTP MUST NOT set this property to <tt>true</tt>. See <xref target="dpop-non-http" /> for how such a client instance can still make use of DPoP.</t></dd>
</dl>
</section>

<section anchor="redirect-uri-requirements"><name>Redirect URI Requirements</name>
<t>Each redirect URI registered by the client instance MUST satisfy all of these conditions:</t>

<ul spacing="compact">
<li><t>The URI MUST start with one of the following:</t>
<ul>
  <li><tt>http://127.0.0.1/</tt></li>
  <li><tt>http://[::1]/</tt></li>
  <li>A private-use URI scheme, as described in <xref target="RFC8252" section="7.1" />: a scheme that is not registered with IANA, and is instead named after a domain the client developer controls, written in reverse order, as recommended for private use by <xref target="RFC7595" section="3.8" />. For example, the developer of <tt>example.com</tt> could use the scheme <tt>com.example</tt>, giving a redirect URI such as <tt>com.example:/</tt>. Such a scheme MUST have at least one dot in it.</li>
</ul></li>
<li>The URI MUST NOT include two consecutive dots (e.g., <tt>/../</tt>).</li>
<li>The URI MUST NOT include a fragment part (<tt>#</tt>).</li>
</ul>
<t>The URI may include a path and query parameters.</t>
<t>Some platforms allow an application to claim an "https" URL, so that the operating system delivers it to the application rather than opening it in a browser. <xref target="RFC8252" section="7.2" /> describes using such a URL as a redirect URI, and for native clients it is otherwise the most secure option. This profile deliberately does not permit this. An authorization server cannot tell whether an "https" redirect URI has been claimed by a native application or is an ordinary web page. Permitting such URIs would therefore allow web-based clients to complete the flow. See <xref target="native-clients-only" /> and <xref target="security-considerations" />.</t>
<t>The redirect URI restrictions MUST be enforced: a registration request containing a redirect URI that does not satisfy them MUST be rejected with an <tt>invalid_redirect_uri</tt> error (<xref target="RFC7591" section="3.2.2" />). These ensure the OAuth flow can only be completed by native clients — not web clients — as discussed in <xref target="native-clients-only" />. Since a malicious native client could present the user with a custom browser to phish credentials anyway, the lack of verification of client registration details does not provide additional danger beyond existing threats. Allowing seamless dynamic registration for web-based clients, however, unfortunately makes it much easier for a phishing site to gain access to an account, by sending the user through the OAuth flow.</t>
</section>

<section anchor="registration-processing"><name>Server Processing</name>
<t>The server MUST check that all required properties are present and have valid values, and MUST reject a registration request that omits a required property with an <tt>invalid_client_metadata</tt> error (<xref target="RFC7591" section="3.2.2" />). Any unknown properties supplied by the client instance MUST just be ignored. The authorization server MAY replace any of the client's requested metadata values submitted during the registration and substitute them with suitable values.</t>
<t>If there is an exact match for all properties except for software_version, an existing registration may be returned. Otherwise, servers SHOULD create a new registration and client id.</t>
<t>There is no way to verify the authenticity of the information supplied by the client. However, the information is usually accurate, and is still useful to the server: for example, it allows the server to contact client authors to help debug issues if aberrant behavior is observed. Servers MAY choose to ignore all of the information instead and just return a static client id to all requests.</t>
</section>

<section anchor="registration-response"><name>Registration Response</name>
<t>If successful, the server responds with an HTTP 201 Created status code and a body of type "application/json". The body is a JSON object containing all the properties submitted during registration, with their values as set by the server if it replaced any of them, plus the following property:</t>

<dl spacing="normal" newline="true">
<dt><tt>client_id</tt></dt>
<dd>The OAuth 2.0 client identifier string, used in the authorization flow (see <xref target="authorization" />).</dd>
</dl>
<t>Clients following this profile are public clients (see <xref target="native-clients-only" />): they register with a <tt>token_endpoint_auth_method</tt> of "none" and do not authenticate to the token endpoint, instead proving possession of the authorization code using PKCE. The server MUST NOT issue a client secret in the registration response, so the <tt>client_secret</tt> and <tt>client_secret_expires_at</tt> properties defined in <xref target="RFC7591" section="3.2.1" /> MUST NOT be present. A native client cannot keep a secret confidential, so a secret would offer no security benefit, and a client that expected to use one would not be interoperable with servers that correctly omit it. If a server nonetheless returns a <tt>client_secret</tt>, the client instance MUST ignore it and continue as a public client.</t>
<t>The client instance MUST use the values returned in the registration response in preference to those it requested, in particular for the <tt>redirect_uris</tt>, <tt>scope</tt>, and <tt>dpop_bound_access_tokens</tt> properties. If the returned <tt>redirect_uris</tt> or <tt>scope</tt> omit a value the client instance requires, it MUST abort the flow and inform the user. The server may omit <tt>dpop_bound_access_tokens</tt> from the response or return it as false, for example because it returns a static client id to all requests. In that case, the client instance MUST NOT assume that access tokens will be DPoP-bound and MUST check the <tt>token_type</tt> of each token response (see <xref target="dpop-non-http" />). Conversely, if the server returns <tt>dpop_bound_access_tokens</tt> as true when the client instance did not request it, and the client instance needs to access non-HTTP resources, it MUST abort the flow and inform the user, as it will not be able to obtain bearer access tokens.</t>
<t>If the registration fails, the server will respond with an HTTP 400 status code and a JSON body as described in <xref target="RFC7591" section="3.2.2" />.</t>
</section>

<section anchor="dynamic-client-registration-considerations">
<name>Client Id Validity</name>
<t>The client id MUST remain valid for as long as there is a valid refresh token associated with that client id.</t>
<t>To ensure a good user experience, the client id assigned upon dynamic registration SHOULD be valid for use in the authorization flow (<xref target="authorization"/>) for at least one hour after issuance.</t>
<t>Clients MUST associate a client id with each refresh token they have. If the refresh token is invalidated and the client instance has to reauthenticate, it MUST submit the dynamic client registration (<xref target="dynamic-client-registration" />) again and use the client id returned, which MAY be different than the previous client id. A client instance that receives an <tt>invalid_client</tt> error from the token endpoint MUST likewise treat the client id as no longer valid and re-register before obtaining new authorization.</t>
<t>Servers that wish to store client registration information MUST be careful of resource exhaustion attacks. A RECOMMENDED approach is to:</t>
<ul>
  <li>Normalize and securely hash the submitted registration data.</li>
  <li>Check if this hash already exists in the database, and if so return the existing client id issued for this registration.</li>
  <li>Otherwise, keep the registration in temporary storage and only insert it into the database upon successful authorization. Creating a new client id in the temporary storage can be rate limited, for example by IP.</li>
  <li>Remove any client registrations from the database whenever there are no valid refresh tokens associated with that client id.</li>
</ul>
</section>
</section>

<section anchor="authorization"><name>Authorization</name>

<section anchor="authorization-request"><name>Authorization Request</name>
<t>Clients construct an authorization request URL by taking the <tt>authorization_endpoint</tt> from the authorization server metadata and adding the following additional query parameters:</t>

<dl spacing="normal" newline="true">
<dt><tt>client_id</tt></dt>
<dd>The client id as returned in the registration.</dd>
<dt><tt>redirect_uri</tt></dt>
<dd><t>One of the redirect URIs registered by the client instance. This MUST be identical to the registered URI, with one exception. If the registered URI has the prefix "http://127.0.0.1/" or "http://[::1]/", the URI sent MAY differ from it by the addition of a port number, and the authorization server MUST accept any port (see <xref target="RFC8252" section="7.3" />). This is necessary because the client instance cannot know in advance which port it will be able to listen on.</t>
<t>For example, if <tt>http://127.0.0.1/redirect</tt> was registered, then the client instance could send <tt>http://127.0.0.1:49152/redirect</tt> as the redirect_uri for authorization.</t></dd>
<dt><tt>response_type</tt></dt>
<dd>This MUST be "code".</dd>
<dt><tt>scope</tt></dt>
<dd><t>A space delimited set of scopes the client instance would like access to. This MUST be a subset of the scopes registered for this client id.</t></dd>
<dt><tt>code_challenge</tt></dt>
<dd><t>A PKCE code challenge as per <xref target="RFC7636" />, using SHA 256. To generate a challenge, first generate a code_verifier. This is a high-entropy cryptographic random string using the unreserved characters <tt>[A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"</tt> from Section 2.3 of <xref target="RFC3986" />, with a minimum length of 43 characters and a maximum length of 128 characters.</t>
<t>The code_challenge is then <tt>BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))</tt>.</t></dd>
<dt><tt>code_challenge_method</tt></dt>
<dd>This MUST be "S256".</dd>
<dt><tt>resource</tt></dt>
<dd><t>A Resource Indicator <xref target="RFC8707" /> for a resource endpoint (as obtained from autoconfiguration or user input) that the client instance wishes to access after successful authorization. The client instance MUST include a <tt>resource</tt> parameter for each endpoint it intends to use, so if it wishes to use multiple protocols it will include multiple <tt>resource</tt> query parameters. If two endpoints result in the same value, the value MUST only be included once.</t>
<t>The value for each endpoint is determined as described in <xref target="resource-indicators" />.</t></dd>
<dt><tt>state</tt></dt>
<dd>An opaque value used by the client instance to verify that an authorization response is due to a request that the client instance initiated. The authorization server will include this value when redirecting the user-agent back to the client instance.  Client instances MUST generate a state with a unique, unguessable random string when initiating an authorization request.</dd>
<dt><tt>login_hint (optional)</tt></dt>
<dd>The username the user originally asked to log in with, as defined in Section 3.1.2.1 of <xref target="OpenID.Core" />. The server can prefill this in a login form. Note, the user may choose to log in with a different username; the client instance learns which username was actually authenticated from the <tt>username</tt> property of the token response (see <xref target="token-response" />).</dd>
</dl>
<t>For compatibility with servers implementing OpenID Connect Core <xref target="OpenID.Core" />, if the server advertised the <tt>offline_access</tt> scope in the "scopes_supported" property of the authorization server metadata, the client instance MUST also request this scope. Section 11 of <xref target="OpenID.Core" /> further requires the <tt>prompt</tt> parameter to have the value <tt>consent</tt> when <tt>offline_access</tt> is requested, unless other conditions permitting offline access are in place, and some deployments will not issue a refresh token without it. A client instance requesting <tt>offline_access</tt> SHOULD therefore also include a <tt>prompt</tt> parameter with the value <tt>consent</tt> (see Section 3.1.2.1 of <xref target="OpenID.Core" />).</t>

<t>The client instance MAY include additional request parameters defined by other OAuth extensions, for example the <tt>prompt</tt> or <tt>ui_locales</tt> parameters defined by OpenID Connect Core <xref target="OpenID.Core" />. This does not permit alternative or additional values for the parameters defined above; in particular, it does not relax the <tt>redirect_uri</tt> matching rules, and a request whose defined parameters do not conform MUST be rejected regardless of any other parameters present. The authorization server MUST ignore any request parameter it does not recognize, as required by <xref target="RFC6749" section="3.1" />, and clients MUST NOT depend on such parameters being understood for interoperability. Ignoring unrecognized parameters is safe because they cannot affect the processing of the parameters defined by this document, and it allows this profile to coexist with other OAuth extensions that both the client and server happen to support.</t>
</section>

<section anchor="resource-indicators"><name>Determining Resource Indicator Values</name>
<t>The client instance determines the <tt>resource</tt> value for each endpoint (see <xref target="authorization-request" />) as follows. First, the client instance determines the endpoint's resource location. If the client instance followed HTTP redirects to reach the endpoint during service discovery (see <xref target="issuer-discovery-http" />), the endpoint URL used here is the URL of the final response, after following those redirects.</t>
<ul spacing="compact">
<li>For HTTP-based protocols, such as JMAP, CalDAV, and CardDAV, this is the endpoint URL, for example <tt>https://api.example.com/jmap/session</tt> or <tt>https://caldav.example.com/.well-known/caldav</tt>.</li>
<li>For non-HTTP protocols, such as IMAP, POP, and SMTP, this is the hostname of the server with no scheme or port, for example <tt>imap.example.com</tt>.</li>
</ul>
<t>Then, if the authorization server metadata includes the <tt>protected_resources</tt> property (see <xref target="metadata-protected-resources" />), the client instance MUST use as the <tt>resource</tt> value the entry in that array that matches the resource location. An entry matches an HTTP resource location if all of the following hold:</t>
<ul spacing="compact">
<li>The schemes are identical.</li>
<li>The hosts are identical when compared case-insensitively, after conversion of any internationalized host names to A-labels <xref target="RFC5890" />.</li>
<li>The ports are identical, after applying the default port for the scheme wherever a port is not given explicitly.</li>
<li>The path of the entry, with any trailing "/" removed, is either identical to the path of the resource location or is followed in the path of the resource location by a "/". That is, the entry's path is a prefix of the resource location's path at a segment boundary.</li>
</ul>
<t>Any query or fragment part of the resource location is disregarded for matching. An entry matches a non-HTTP resource host name if the two are identical when compared case-insensitively, again after conversion to A-labels. If more than one entry matches, the client instance MUST use the one with the longest path.</t>
<t>For example, if the client instance wishes to connect to <tt>https://caldav.example.com/.well-known/caldav</tt> and the metadata lists <tt>["https://caldav.example.com", "https://carddav.example.com"]</tt>, the <tt>resource</tt> value is <tt>https://caldav.example.com</tt>. An entry of <tt>https://api.example.com</tt> does not match <tt>https://api.example.com.attacker.net/jmap/session</tt>, <tt>https://api.example.com:8443/jmap/session</tt>, or <tt>https://api.example.com@attacker.net/</tt>, and an entry of <tt>https://example.com/dav</tt> does not match <tt>https://example.com/davenport</tt>. Matching MUST be performed on the parsed components of the URL and not by comparing strings, as a plain prefix comparison would accept each of these counterfeit URLs.</t>
<t>If no entry matches, the endpoint is not a protected resource of this authorization server: the client instance MUST NOT include a <tt>resource</tt> parameter for it, and MUST NOT send access tokens obtained from this authorization server to it (see <xref target="permitted-resource-servers" />). If the client instance cannot function without that endpoint, it MUST abort the flow and inform the user.</t>
<t>If the metadata does not include the <tt>protected_resources</tt> property, the client instance MUST use the resource location itself, with any query or fragment component removed (see <xref target="RFC8707" section="2" />), as the <tt>resource</tt> value. In this case the client instance MUST also apply the registrable domain rule in <xref target="permitted-resource-servers" /> before sending access tokens to the endpoint.</t>
<t>Note that in this case the <tt>resource</tt> value names a specific endpoint URL. However, <xref target="permitted-resource-servers" /> permits the client instance to send the resulting access token to any host within the registrable domain of the issuer identifier, for example one reached by following an HTTP redirect during CalDAV or CardDAV service discovery. An authorization server that supports Resource Indicators and issues audience-restricted access tokens (see <xref target="RFC9700" section="4.10.2" />) may therefore issue a token that the redirect target rejects, even though the client instance has behaved correctly. Servers that support Resource Indicators SHOULD avoid this by publishing <tt>protected_resources</tt>, so that the client instance sends a value that covers every host the token may legitimately be presented to. A server that supports Resource Indicators but does not publish <tt>protected_resources</tt> MUST ensure that a token issued for an endpoint URL is accepted by any resource server to which that endpoint redirects the client.</t>
<t>Note that <xref target="RFC8707" section="2" /> requires the <tt>resource</tt> value to be an absolute URI, and <xref target="RFC9728" section="4" /> likewise requires entries of <tt>protected_resources</tt> to be <tt>https</tt> URLs. This profile deviates from both requirements for non-HTTP protocols, where the value is a bare hostname. Endpoints for these protocols are not naturally identified by a URI. URI schemes exist for some of these protocols, such as <tt>imap</tt> <xref target="RFC5092" /> and <tt>pop</tt> <xref target="RFC2384" />, but they are not used here. These schemes identify mailboxes or messages rather than servers, and do not distinguish the implicit-TLS and STARTTLS ports of the same server. There is also no equivalent scheme for SMTP submission. The hostname is used instead, as it is what the client instance MUST present in the <tt>host</tt> attribute of the OAUTHBEARER SASL exchange <xref target="RFC7628" /> (see <xref target="using-the-access-token" />). Servers implementing this profile MUST accept a bare hostname as a <tt>resource</tt> value for such endpoints.</t>
<t>Server support for Resource Indicators is RECOMMENDED; servers that do not support them will ignore these parameters and the flow will still succeed. Servers that do support Resource Indicators MUST verify that every requested <tt>resource</tt> value is a permitted location to send access tokens to. A value is permitted if it identifies one of the real resource endpoints associated with this authorization server, or is an entry in the server's <tt>protected_resources</tt> list. If any value is not permitted, the server MUST reject the request with an <tt>invalid_target</tt> error, as defined in <xref target="RFC8707" section="2" />.</t>
</section>

<section anchor="user-agent-requirements"><name>User-Agent Requirements</name>
<t>After constructing the authorization request URL, the client instance MUST use platform-specific APIs to open it in an external user-agent. It MUST NOT use an embedded user-agent (such as a web view) within the application, as required by <xref target="RFC8252" section="8.12" />. Typically, the external user-agent used is the default browser, that is, the application configured for handling "http" and "https" scheme URLs on the system. See <xref target="RFC8252" section="6"/> for a discussion of best practices and alternatives, such as in-app browser tabs, which are external user-agents that render within the application while retaining the security properties of the browser. The client instance MUST use a user-agent that supports session cookies, JavaScript, and the Web Authentication API <xref target="WebAuthn" />, so that authorization servers can rely on these being available.</t>

<t>Embedded user-agents are prohibited because they undermine much of the security benefit of this profile. An embedded user-agent is under the control of the client application, which can therefore observe and modify everything the user enters, including their password and any second factor. The user also has no way to verify which site they are actually entering their credentials into. An external user-agent, by contrast, shares the user's existing authentication state and credential stores with the rest of the system. This allows single sign-on, password managers, and origin-bound authenticators such as passkeys <xref target="WebAuthn" /> to work, and allows the browser's built-in phishing protections to apply. Users are also better able to recognize and reason about a login page shown in their familiar browser than one shown inside an arbitrary application.</t>

<t>This restriction is a requirement on clients and is not reliably enforceable by the authorization server, as an embedded user-agent may be indistinguishable from an external one. Servers MAY use heuristics (for example, the <tt>User-Agent</tt> header field) to detect and refuse authorization from known embedded user-agents, as suggested in <xref target="RFC8252" section="8.12" />, but the security of this profile does not depend on them doing so. As discussed in <xref target="security-considerations" />, a malicious native application could already present the user with a fake browser, so this profile does not attempt to defend against a malicious client; the requirement ensures that well-behaved clients provide the security properties users expect.</t>
</section>

<section anchor="authorization-processing"><name>Server Processing</name>
<t>The authorization server MUST verify that all of the parameters defined in <xref target="authorization-request" /> are present, other than <tt>login_hint</tt>, which is optional, and <tt>resource</tt>, which is not always included (see <xref target="resource-indicators" />). It MUST also verify that every parameter present conforms to the restrictions in this document. A server that issues the same client id for registrations with different redirect URIs, for example a static client id, cannot meaningfully require the <tt>redirect_uri</tt> to be identical to a registered URI; such a server MUST instead verify that the <tt>redirect_uri</tt> satisfies the requirements in <xref target="redirect-uri-requirements" />. A request in which any parameter is included more than once MUST be rejected, with the exception of the <tt>resource</tt> parameter, which may be repeated as described in that section.</t>

<t>If verified, the authorization server will authenticate the user and ask them if they wish to grant authorization to the client.</t>

<t>The authorization request may fail because the redirection URI is missing, invalid, or mismatching, or because the client identifier is missing or invalid. In these cases, the authorization server SHOULD inform the user of the error, and MUST NOT automatically redirect the user-agent to the invalid redirection URI. If the authorization request fails for any other reason, the client instance will receive an error response via the redirect_uri. This MUST include an error query parameter with an appropriate error code, as defined in <xref target="RFC6749" section="4.1.2.1"/>. The error response also includes the <tt>state</tt> parameter and, as required by <xref target="RFC9207" section="2" />, the <tt>iss</tt> parameter. The client instance MUST verify both as described in <xref target="authorization-response" /> before acting on the error, and MUST ignore an error response whose <tt>state</tt> does not match a request it has outstanding.</t>
</section>

<section anchor="authorization-response"><name>Authorization Response</name>
<t>If authorization is successful, the client instance will receive a response via the redirect_uri, which will include the following query parameters:</t>

<dl spacing="normal" newline="true">
<dt><tt>code</tt></dt>
<dd>The authorization code. This may be exchanged for the refresh token. This code MUST expire, but MUST NOT expire less than 10 minutes after it is issued. This allows the client instance to complete the exchange even on a poor network, or if the operating system suspends the client instance before it can make the token request. <xref target="RFC6749" section="4.1.2" /> recommends a maximum lifetime of 10 minutes; a server choosing a longer lifetime deviates from that recommendation. This is acceptable for this profile because the code can only be exchanged by the holder of the PKCE code verifier, and only once. It MUST NOT be used again once the client instance has successfully exchanged it for a refresh token. Doing so may cause the server to detect it as stolen and revoke all associated tokens.</dd>
<dt><tt>state</tt></dt>
<dd>The value of the state parameter that was passed in with the initial request.</dd>
<dt><tt>iss</tt></dt>
<dd>The issuer identifier of the authorization server.</dd>
</dl>
<t>The client instance MUST verify all of the following:</t>

<ul spacing="compact">
<li>The "iss" returned is identical to the "issuer" property in the authorization server metadata. This is critical for protecting against various mix-up attacks should a malicious OAuth metadata object be fetched, as discussed in the security considerations.</li>
<li>The state returned matches exactly the state it sent, to verify that this
request was indeed initiated by the client and not an attacker.</li>
</ul>
<t>If the state returned does not match a request the client instance has outstanding, the client instance MUST ignore the response, and continue to wait for a response to its request. This prevents another process on the device from disrupting the flow by sending a bogus response. If the state matches but any other verification fails, the client instance MUST abort the flow and not send the authorization code anywhere. It MUST inform the user of what went wrong and what they can do next. For a loopback redirect URI, this is done by returning an HTML page in response to the redirect request; for a private-use URI scheme the client instance is invoked directly and displays the message itself.</t>
</section>
</section>

<section anchor="tokens"><name>Obtaining Tokens</name>

<section anchor="obtaining-a-refresh-token"><name>Exchanging the Authorization Code</name>
<t>Following authorization, the client instance will obtain initial refresh and
access tokens by making a POST request to the token_endpoint URL. The following parameters, other than those marked as optional, MUST be present, using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:</t>

<dl spacing="normal" newline="true">
<dt><tt>client_id</tt></dt>
<dd>The client id as returned in the registration.</dd>
<dt><tt>redirect_uri</tt></dt>
<dd>The redirect_uri parameter sent with the authorization request from which the code was obtained.</dd>
<dt><tt>grant_type</tt></dt>
<dd>This MUST be "authorization_code".</dd>
<dt><tt>code</tt></dt>
<dd>The code returned via the redirect back from authorization.</dd>
<dt><tt>code_verifier</tt></dt>
<dd><t>The code_verifier generated for the authorization (the random string generated in the authorization step, as per <xref target="RFC7636" />).</t>
<t>The server MUST reject a request that omits this parameter, or whose value does not verify against the <tt>code_challenge</tt> sent with the authorization request, as specified in <xref target="RFC7636" section="4.6" />. An authorization code issued to a client registered under this profile MUST NOT be exchangeable without it: PKCE is the only protection against an authorization code intercepted via a loopback or private-use URI scheme redirect.</t></dd>
<dt><tt>resource (optional)</tt></dt>
<dd>One or more Resource Indicators, as described in <xref target="RFC8707" section="2.2" />, restricting the access token to a subset of the resources that were authorized. Each value MUST be one of the <tt>resource</tt> values sent in the authorization request. If omitted, the access token is issued for all of the authorized resources. See <xref target="dpop-non-http" /> for when a client instance needs to use this.</dd>
</dl>
<t>The client instance MAY include additional parameters defined by other OAuth extensions. The server MUST ignore any parameter it does not recognize, as required by <xref target="RFC6749" section="3.2" />, and clients MUST NOT depend on such parameters being understood for interoperability. If using DPoP, the client instance MUST also set a DPoP header in accordance with <xref target="RFC9449" section="5" />. A client instance using DPoP MUST support the authorization server-provided nonce (<xref target="RFC9449" section="8" />) and resource server-provided nonce (<xref target="RFC9449" section="9" />) mechanisms, retrying a request that fails with a <tt>use_dpop_nonce</tt> error using the nonce supplied, as servers MAY require a nonce in every proof.</t>
</section>

<section anchor="token-response"><name>Token Response</name>
<t>The server will verify the parameters and if successful, return a <tt>200 OK</tt> response with a content type of application/json. The body will be a JSON
object with the following properties:</t>

<dl spacing="normal" newline="true">
<dt><tt>access_token</tt></dt>
<dd>The access token used to authenticate API requests. Unless it is DPoP-bound, this is a bearer token. It will be valid for a fixed, limited time.</dd>
<dt><tt>token_type</tt></dt>
<dd>The type of the access token. This MUST be "Bearer", or "DPoP" if the client is using DPoP (<xref target="RFC9449" />). The value is case insensitive (<xref target="RFC6749" section="5.1" />), and clients MUST compare it accordingly; servers commonly return "bearer".</dd>
<dt><tt>expires_in</tt></dt>
<dd>The lifetime in seconds of the access token. For example, the value <tt>3600</tt> denotes that the access token will expire in one hour from the time the response was generated. Servers MUST include this property in every token response (it is only RECOMMENDED in <xref target="RFC6749" section="5.1" />), as clients rely on it to obtain a new access token before the current one expires (see <xref target="getting-a-new-access-token" />).</dd>
<dt><tt>scope</tt></dt>
<dd><t>The space delimited set of scopes that this access token may use. Servers MUST include this property in every token response, even where it is identical to the set of scopes requested (in which case it is OPTIONAL in <xref target="RFC6749" section="5.1" />).</t>
<t>Note that this may be different from the set of scopes requested. Servers MAY allow users to choose to authorize only a subset of the requested scopes. Clients MUST check that the set of scopes granted is sufficient for their needs.</t></dd>
<dt><tt>refresh_token</tt></dt>
<dd>The refresh token to use next time the client instance needs to get a new access token. Servers MUST include this property in the response to an authorization code grant; a client instance following this profile cannot function without it. For its presence in the response to a refresh token grant, see <xref target="refresh-token-rotation" />.</dd>
<dt><tt>username</tt></dt>
<dd><t>The username of the account that was authenticated and granted this authorization, in the form the user would enter it to log in to this deployment (typically the user's email address). Servers MUST include this property in every token response, and the value MUST be the same in every token response issued under the same authorization.</t></dd>
</dl>
<t>The user may have started the flow by giving the client instance one username (which the client instance may have passed as the <tt>login_hint</tt>, see <xref target="authorization-request" />) and then authenticated at the authorization server as a different user. Without the <tt>username</tt> property in the token response, the client instance has no interoperable way to discover this, and may label the account, or associate the tokens with a local account, incorrectly. The client instance MUST use the <tt>username</tt> value, together with the issuer identifier, rather than the username originally supplied by the user, as the identity of the account the tokens belong to. Tokens from one authorization server MUST NOT be associated with an account established with a different issuer, even if the usernames are the same. If it differs from the username the user supplied, the client instance SHOULD make this visible to the user.</t>
<t>OpenID Connect Core <xref target="OpenID.Core" /> can convey the authenticated user's identity in an ID Token, but this profile does not require OpenID Connect support, and the <tt>sub</tt> claim it guarantees is an opaque identifier rather than a username the user would recognize. This document therefore registers "token response" as an additional usage location for the existing <tt>username</tt> parameter (see <xref target="oauth-parameters-registry-update" />).</t>

<t>If the request fails, the server MUST return an error response as described in <xref target="RFC6749" section="5.2"/>. This MUST have a <tt>400 Bad Request</tt> status code, including for an <tt>invalid_client</tt> error: as clients following this profile do not authenticate to the token endpoint, the <tt>401 Unauthorized</tt> status code that <xref target="RFC6749" section="5.2"/> permits for that error does not apply. The response has a content type of application/json, and a JSON object body with the properties defined there. A client id that is no longer valid (see <xref target="dynamic-client-registration-considerations" />) is reported with the <tt>invalid_client</tt> error code. An authorization code or refresh token that is invalid, expired, or revoked is reported with the <tt>invalid_grant</tt> error code.</t>
</section>

<section anchor="getting-a-new-access-token"><name>Refreshing the Access Token</name>
<t>The client instance obtains its first access token, together with its refresh token, by exchanging the authorization code as described in <xref target="obtaining-a-refresh-token" />. This section describes how it obtains every subsequent access token, using the refresh token. It does not apply to the first access token.</t>
<t>Clients SHOULD keep using an access token they have been issued until it expires. The client instance knows when this will happen from the <tt>expires_in</tt> property returned with the token. While the client instance has an active need for the token (for example, open connections it expects to re-establish), it SHOULD proactively obtain a new access token shortly before the current one expires, rather than waiting for a request to fail. A client instance with no such need SHOULD NOT refresh merely to keep a token current. This is particularly important for stateful protocols such as IMAP and SMTP, where the token is needed at connection time and a round trip to the token endpoint would otherwise delay every reconnection. Clients MUST nonetheless be prepared for an access token to be rejected at any time (for HTTP-based protocols, with a <tt>401</tt> response), as the server may invalidate it early, and MUST handle this by obtaining a new one.</t>
<t>To obtain a new access token, the client instance makes a POST request to the authorization server token endpoint. The following parameters, other than those marked as optional, MUST be present, using the "application/x-www-form-urlencoded" format with a character encoding of UTF-8 in the HTTP request entity-body:</t>

<dl spacing="normal" newline="true">
<dt><tt>client_id</tt></dt>
<dd>The client id as returned in the registration.</dd>
<dt><tt>grant_type</tt></dt>
<dd>This MUST be "refresh_token".</dd>
<dt><tt>refresh_token</tt></dt>
<dd>The most recent refresh token the client instance has received (see <xref target="refresh-token-rotation" />).</dd>
<dt><tt>refresh_key</tt></dt>
<dd>The refresh key the client instance generated for this request, as described in <xref target="refresh-token-rotation" />. A retry of a request MUST use the same refresh key as the original request. This parameter is only used with the <tt>refresh_token</tt> grant type; servers MUST ignore it in other token requests. Servers SHOULD reject a request with an <tt>invalid_request</tt> error if the value does not have the syntax of a PKCE code_verifier <xref target="RFC7636" />.</dd>
<dt><tt>resource (optional)</tt></dt>
<dd>One or more Resource Indicators restricting the access token to a subset of the authorized resources, with the same semantics as in <xref target="obtaining-a-refresh-token" />.</dd>
</dl>
<t>The success and failure responses are identical to those documented in <xref target="token-response" />.</t>
</section>

<section anchor="refresh-token-rotation"><name>Refresh Token Rotation and Replay Protection</name>
<t>Because clients following this profile are public clients, the server MUST protect against refresh token replay, using one of the two methods required by <xref target="RFC9700" section="4.14.2" />:</t>
<ul>
<li>Sender-constrained refresh tokens. If the client instance presented a DPoP proof when the refresh token was issued, the server binds the refresh token to the client instance's key (<xref target="RFC9449" section="5" />). In this case, the server MAY omit the <tt>refresh_token</tt> property from a refresh response, or MAY return the same refresh token again. The client instance then continues to use the refresh token it already holds.</li>
<li>Refresh token rotation. If the refresh token is not sender-constrained, the server MUST return a new refresh token in every refresh response.</li>
</ul>
<t>Whenever a refresh response contains a refresh token that differs from the one the client instance holds, the client instance MUST replace its stored refresh token with the new one. The client instance MUST persist the new refresh token before making any use of the access token returned in the same response.</t>
<t>Simply invalidating the previous refresh token as soon as a new one is issued, as <xref target="RFC9700" section="4.14.2" /> specifies, causes a problem for native clients. The response containing the new refresh token may not reach the client instance: the connection may drop, or the client instance may be suspended or terminated by the operating system before it can persist the new token. The client instance will then retry with the previous refresh token, possibly much later, and this retry must succeed. However, the server also has to be able to distinguish this retry from an attacker presenting a copy of the previous refresh token. The refresh key makes this possible.</t>
<t>Before making a refresh request, the client instance generates a refresh key: a high-entropy cryptographic random string, generated in the same way as a PKCE code_verifier (see <xref target="authorization-request" />). The client instance MUST generate a new refresh key for every refresh request other than a retry, and MUST NOT use a refresh key with more than one refresh token. It MUST persist the refresh key, associated with the refresh token it is about to present, before sending the request, and MUST include it in the <tt>refresh_key</tt> parameter of the request (see <xref target="getting-a-new-access-token" />).</t>
<t>The client instance MUST keep the refresh key, and retry the request with the same refresh token, the same refresh key, and the same other parameters, until it either receives and persists a successful token response, or receives an <tt>invalid_grant</tt> or <tt>invalid_client</tt> error response. Any other outcome, including a network failure, a timeout, an HTTP 5xx status code, a response that is not a valid token response or error response, or a <tt>use_dpop_nonce</tt> error, MUST be treated as a lost response, and handled by retrying. Once the client instance has persisted a successful response, or received one of those two errors, it MUST discard the refresh key.</t>
<t>The client instance MUST protect the refresh key in the same way as the refresh token (see <xref target="security-considerations" />). A refresh key exists only while a refresh request is outstanding, so a copy of the client instance's storage taken at any other time does not include it.</t>
<t>When the server issues a new refresh token in response to a request that included a refresh key, it MUST record the refresh key with the refresh token that was presented. A refresh token that has been replaced by a new one, at any point in the history of the authorization, is a superseded refresh token. The server MUST be able to recognize every superseded refresh token of an authorization for as long as the authorization remains valid, for example by recording an identifier for the authorization in each refresh token it issues. The server only needs to retain the refresh key recorded for the most recently superseded refresh token. It SHOULD store only a hash of the refresh key, and MUST NOT write refresh keys to logs. A refresh token is considered to have been used once the server has successfully processed a request presenting it.</t>
<t>The server MUST respond to a request presenting a superseded refresh token as follows:</t>
<ul>
<li><t>If it is the most recently superseded refresh token of the authorization, the request includes the refresh key recorded for it, and the refresh token that replaced it has not been used, the request is a retry by the client instance that made the original request. The server MUST respond as follows:</t>
<ul>
<li>The response MUST contain the same new refresh token that was issued in the original response. The server MUST NOT issue a further new refresh token. To allow this, the server needs to be able to reproduce the new refresh token, for example by storing it in encrypted form, or by deriving it deterministically from the original request.</li>
<li>The response MUST contain either the same access token as the original response, with <tt>expires_in</tt> adjusted for the time elapsed, or a newly issued access token. The server MUST NOT return the same access token unless the request's <tt>resource</tt> parameters match those of the original request, the request includes a DPoP proof for the same key as the original request (or neither includes a DPoP proof), and at least 10 minutes of the access token's lifetime remain (see <xref target="token-expiry-times" />).</li>
</ul></li>
<li>Otherwise, the request indicates that the refresh token has been leaked or stolen. The server MUST reject the request with an <tt>invalid_grant</tt> error, and MUST revoke the entire authorization, including the current refresh token and all associated access tokens. This applies whether or not the refresh token is sender-constrained.</li>
</ul>
<t>The server MUST check whether a refresh token has been superseded, and apply the rules above, before validating any other parameters of the request. If a superseded refresh token is presented at the revocation endpoint <xref target="RFC7009" />, the server MUST revoke the entire authorization.</t>
<t>If a refresh request does not include a refresh key, no refresh key is recorded for the refresh token it presents. The refresh token is then handled exactly as specified for refresh token rotation in <xref target="RFC9700" section="4.14.2" />: it is invalidated as soon as the new refresh token is issued, and any later presentation of it is treated as an indication that it has been leaked or stolen, as described in the last case above. The refresh key mechanism is therefore purely an addition to that behavior, which applies only when the client instance supplies a refresh key.</t>
<t>The server MUST process requests relating to the same authorization atomically, so that concurrent requests cannot result in more than one new refresh token being issued, or in a retry being answered after the refresh token that replaced the presented one has been used.</t>
<t>A legitimate client instance that did not receive a response therefore recovers without user interaction, however long it is before it retries, as long as the authorization is still valid. As the server never issues a further new refresh token in response to a superseded one, a retry cannot create a second, independent refresh token chain. An attacker who has obtained a copy of a refresh token, but not the corresponding refresh key, cannot use it without the reuse being detected. If the attacker presents it after the client instance has refreshed, the refresh key does not match, and the authorization is revoked immediately. If the attacker presents it first, the client instance's next refresh presents the same refresh token with a different refresh key, and the authorization is revoked at that point. If an attacker obtains the refresh key as well, it can obtain the new refresh token, but the reuse is still detected: either the client instance later presents the superseded refresh token, or whichever of them uses the new refresh token second presents it with a refresh key that does not match. Either results in revocation.</t>
<t>This deviates from <xref target="RFC9700" section="4.14.2" />, which invalidates the previous refresh token as soon as the new one is issued. The deviation applies only to a request presenting the most recently superseded refresh token with the refresh key recorded for it, before the refresh token that replaced it has been used. The deviation is necessary so that a client instance that did not receive the response can recover without user interaction. The security implications are discussed in <xref target="security-considerations" />.</t>
<t>The client instance MUST ensure that only one token request is in flight at a time for a given refresh token, for example by serializing refresh operations across all connections that share the authorization. Concurrent refreshes would otherwise race, with one of them presenting a refresh token that has just been superseded. A request that the client instance has abandoned, for example after a timeout, may still be received and processed by the server; this is safe, as any retry of it uses the same refresh key.</t>
<t>If a user has multiple devices with the same client software installed, each instance of the client MUST obtain separate authorization. A refresh token MUST NOT be shared between devices.</t>
</section>

<section anchor="token-expiry-times"><name>Token Lifetimes and Revocation</name>
<t>Access tokens MUST have a lifetime of at least 10 minutes, and SHOULD have a lifetime of at least 1 hour.</t>
<t>The hard minimum exists so that a client instance can rely on an access token it has just obtained lasting long enough for a single operation. This matters especially on poor networks, where the client instance may have to retry several times before it can connect to the resource server. It also bounds the rate at which a client instance must contact the token endpoint, making the client more efficient with its network usage.</t>
<t>The recommended lifetime of one hour further reduces load on the token endpoint. More importantly, it loosens the coupling between the authorization server and the resource servers. With hour-long tokens, a brief outage of the authorization server, or a period on a network where it is unreachable, is invisible to the user. The trade-off is that a longer lifetime extends the window during which a leaked bearer token can be misused. Servers that consider this window too long are encouraged to support DPoP (<xref target="RFC9449" />) rather than shorten the lifetime below one hour. DPoP prevents a stolen access token from being used by anyone other than the client instance it was issued to.</t>
<t>Refresh tokens SHOULD NOT expire, unless the user explicitly revokes the token or it has been unused for a considerable period of time (at least 30 days).</t>
<t>For stateful connection-based protocols such as SMTP and IMAP the access token is only presented on first connection. Expiry of the access token SHOULD NOT affect current IMAP/SMTP etc. sessions that have already authenticated. However, if the server chooses to force reauthorization, it MUST do so by unilaterally closing the connection. There is no way to reauthenticate an existing session in these protocols, and all clients already have to be able to reconnect after a dropped connection.</t>
<t>When a refresh token is revoked, the deployment MUST close any existing stateful connections, such as IMAP or SMTP sessions, that were authenticated using access tokens issued under the same authorization. A refresh token may be revoked, for example, because the user has revoked the client's authorization, or because the token has been detected as leaked.</t>
<t>A client instance cannot detect that its refresh token has been revoked until it next attempts to use it. A client instance detects revocation by receiving an <tt>invalid_grant</tt> error from the token endpoint, or an <tt>invalid_client</tt> error indicating that the client id is no longer valid (see <xref target="dynamic-client-registration-considerations" />). Once it does so, the client instance MUST discard the refresh token and any associated access tokens, and MUST close any stateful connections it still has open that were authenticated with them. It MUST then obtain new authorization before reconnecting (see <xref target="dynamic-client-registration-considerations" />).</t>
</section>
</section>

<section anchor="using-access-tokens"><name>Using Access Tokens</name>

<section anchor="permitted-resource-servers"><name>Permitted Resource Servers</name>
<t>An access token obtained from an authorization server MUST only be sent to a resource server that the client instance has determined to be associated with that authorization server, as described in this section. This protects against a counterfeit resource server that has been named in autoconfiguration data or protected resource metadata under the attacker's control (see <xref target="RFC9700" section="4.9.1" /> and <xref target="security-considerations" />).</t>
<t>The client instance MUST make this determination for every request URL to which it sends an access token. This includes any URL reached by following an HTTP redirect, such as those commonly used in CalDAV and CardDAV service discovery: the determination is made against the URL actually being requested, not only the endpoint URL the client instance started from. A client instance MUST NOT send an access token to a URL for which the determination fails. If the client instance cannot function without that resource server, it MUST abort and inform the user.</t>
<t>A resource server is permitted if and only if at least one of the following applies:</t>
<ul>
<li>The authorization server metadata includes the <tt>protected_resources</tt> property (see <xref target="metadata-protected-resources" />), and an entry in the list matches the request URL (for HTTP-based protocols) or the host name (for non-HTTP protocols), using the matching rules given in <xref target="resource-indicators" />.</li>
<li>The authorization server metadata does not include the <tt>protected_resources</tt> property, the request URL uses the <tt>https</tt> scheme (for HTTP-based protocols), and the resource server's host name has the same registrable domain as the host of the authorization server issuer identifier. For HTTP-based protocols the host name is the host component of the request URL; for non-HTTP protocols it is the host name the client instance connects to.</li>
<li>The request URL is a service-supplied endpoint URL, as described in <xref target="service-supplied-endpoints" />.</li>
</ul>
<t>The registrable domain of a host name is its public suffix plus the DNS label immediately preceding that suffix, where the public suffix is determined using the Public Suffix List <xref target="PSL" />. For example, the registrable domain of <tt>imap.example.com</tt> is <tt>example.com</tt>, and the registrable domain of <tt>auth.example.co.uk</tt> is <tt>example.co.uk</tt>. Host names MUST be compared case-insensitively, and internationalized host names MUST be converted to A-labels <xref target="RFC5890" /> before comparison. A host that is an IP address literal, or that has no registrable domain (for example, a single-label host name, or a host name that is itself a public suffix), is never permitted under this rule.</t>
<t>The registrable domain rule allows deployments that host their authorization server and resource servers within a single domain, for example <tt>auth.example.com</tt> and <tt>imap.example.com</tt>, to be secure without further configuration. Some deployments have resource servers that are not all within the registrable domain of the issuer identifier. These include providers that use a separate identity provider domain, and multi-tenant authorization servers whose issuer identifier includes a path component. Such deployments MUST publish <tt>protected_resources</tt> (see <xref target="metadata-protected-resources" />), as clients following this profile will otherwise refuse to use their resource servers. This does not apply to resource servers that clients reach only through service-supplied endpoint URLs (see <xref target="service-supplied-endpoints" />).</t>
</section>

<section anchor="service-supplied-endpoints"><name>Service-Supplied Endpoints</name>
<t>Some protocols allow a resource server to tell the client where other endpoints of the same service are located, and these may be on hosts that are not otherwise permitted. For example, a JMAP Session object may give an <tt>apiUrl</tt> on a different domain to the session resource, to allow load balancing or regional deployment. Requiring every such host to be listed in <tt>protected_resources</tt> in advance would be impractical.</t>
<t>A URL is a service-supplied endpoint URL if all of the following apply:</t>
<ul>
<li>The client instance obtained it from one of the fields listed below, in a response to a request that was authenticated with an access token issued under the same authorization, that is, for the same account, as the access token the client instance intends to send to it.</li>
<li>That request was made to a resource server permitted under <xref target="permitted-resource-servers" />. This includes a resource server that is permitted because its URL is itself a service-supplied endpoint URL.</li>
<li>The URL uses the <tt>https</tt> scheme, or the <tt>wss</tt> scheme for a WebSocket endpoint.</li>
</ul>
<t>The fields are:</t>
<ul>
<li><t>For JMAP <xref target="RFC8620" />: the <tt>apiUrl</tt>, <tt>downloadUrl</tt>, <tt>uploadUrl</tt>, and <tt>eventSourceUrl</tt> properties of the Session object. Also, any URL in the Session object that the specification of a JMAP capability defines as an endpoint of the service that the client authenticates to, such as the <tt>url</tt> property of the <tt>urn:ietf:params:jmap:websocket</tt> capability <xref target="RFC8887" />.</t>
<t>The <tt>downloadUrl</tt>, <tt>uploadUrl</tt>, and <tt>eventSourceUrl</tt> properties are URI templates <xref target="RFC6570" />. The determination is made against the expanded URL. If any part of the template before the path, that is, its scheme, userinfo, host, or port, contains a template expression, the URL is not a service-supplied endpoint URL.</t></li>
<li><t>For CalDAV <xref target="RFC4791" /> and CardDAV <xref target="RFC6352" />: the <tt>DAV:current-user-principal</tt> property <xref target="RFC5397" />, the <tt>CALDAV:calendar-home-set</tt> and <tt>CARDDAV:addressbook-home-set</tt> properties, and the <tt>CALDAV:schedule-inbox-URL</tt> and <tt>CALDAV:schedule-outbox-URL</tt> properties <xref target="RFC6638" />.</t>
<t>Also, the <tt>DAV:href</tt> values in a multistatus response <xref target="RFC4918" /> to a request on a calendar home or address book home identified in this way, or on a collection within one, that identify collections or resources within that home. A URL is within a home if it has the same scheme, host, and port as the home's URL, and the home's path, with any trailing "/" removed, is either identical to the URL's path or is followed in the URL's path by a "/".</t></li>
</ul>
<t>Other specifications MAY define further fields as service-supplied endpoint URLs, for the protocols they define or extend. A field qualifies only if the specification defines it as identifying an endpoint of the same service, for the same account, which the client authenticates to with the same credentials.</t>
<t>No other URL is a service-supplied endpoint URL, even if it was obtained in an authenticated response from a permitted resource server. A response from a legitimate server can contain URLs that point to third parties. For example, the <tt>source</tt> property of a subscribed calendar, as returned by some CalDAV servers, identifies an external calendar feed. A client instance MUST NOT send an access token to such a URL unless the URL is permitted on its own under <xref target="permitted-resource-servers" />. Implementations that attach credentials to every request made on behalf of an account need to take particular care here: whether to include an access token has to be decided for each request, based on its URL.</t>
<t>A redirect from a service-supplied endpoint URL does not extend this permission to the redirect target. As for any other redirect, the client instance makes the determination again for the target URL, which is permitted only if it matches an entry in <tt>protected_resources</tt> or, where that property is absent, shares the registrable domain of the issuer identifier.</t>
<t>The permission applies only to the URL obtained from the field, or to URLs expanded from it if it is a URI template, or, for a calendar home or address book home, to URLs within that home. It does not extend to other URLs on the same host. Permission based on a field lasts only while the client instance continues to use the value it obtained. If the value changes, for example because the client instance fetches the JMAP Session object again, the new value replaces the old one.</t>
<t>Deployments MUST ensure that an access token accepted by a resource server is also accepted at every service-supplied endpoint URL obtained from that resource server's responses. In particular, an authorization server that issues audience-restricted access tokens (see <xref target="RFC9700" section="4.10.2" />) needs to take these endpoints into account.</t>
<t>This does not weaken the protection described in <xref target="permitted-resource-servers" />. That protection prevents an attacker who controls autoconfiguration data or protected resource metadata from naming a counterfeit resource server. A resource server that has already been determined to be associated with the authorization server already receives the access token, so trusting it to name other endpoints of the same service gives it no further access. An attacker who does not control such a server cannot alter its responses, which are protected by TLS.</t>
</section>

<section anchor="using-the-access-token"><name>Authenticating to Resource Servers</name>
<t>The client instance is now authenticated. It can connect to the resource servers permitted under <xref target="permitted-resource-servers" />. For HTTP-based protocols, a bearer access token is sent using the Bearer scheme <xref target="RFC6750" />, by setting an <tt>Authorization</tt> header with the value <tt>Bearer {access_token}</tt> (where <tt>{access_token}</tt> is replaced with the value of the access_token). A DPoP-bound access token, that is, one issued with a <tt>token_type</tt> of "DPoP", is instead sent using the DPoP authentication scheme together with a DPoP proof, as described in <xref target="RFC9449" section="7"/>.</t>
<t>For protocols that use SASL authentication, such as IMAP, POP, and SMTP, the access token is used in accordance with the OAUTHBEARER mechanism defined in <xref target="RFC7628" />. Servers MUST NOT require the username associated with the resource (the "authzid") be included in the GS2 header. The client instance MUST include the <tt>host</tt> attribute in its initial client response (<xref target="RFC7628" section="3.1" />), set to the host name it connected to, and SHOULD include the <tt>port</tt> attribute. <xref target="RFC7628" /> makes these attributes optional for bearer tokens. This profile requires <tt>host</tt> because it is the value the client instance used as the Resource Indicator for the endpoint (see <xref target="resource-indicators" />). This allows a server to check that the access token was issued for the host it is being presented to.</t>
</section>

<section anchor="dpop-non-http"><name>DPoP and Non-HTTP Protocols</name>
<t>DPoP <xref target="RFC9449" /> is only defined for HTTP. The proof JWT (<xref target="RFC9449" section="4.2" />) is bound to the HTTP method and URI of the request it protects and is carried in an HTTP header field, and the OAUTHBEARER SASL mechanism <xref target="RFC7628" /> has no means of carrying such a proof. A DPoP-bound access token therefore cannot be used to authenticate to an IMAP, POP, or SMTP server. Sender-constraining access tokens for SASL-based protocols would require a new SASL mechanism, or an extension to OAUTHBEARER, together with a means for the resource server to verify the proof. That is out of scope for this document.</t>
<t>A client instance that uses only HTTP-based protocols and wishes to use DPoP SHOULD register with <tt>dpop_bound_access_tokens</tt> set to true (see <xref target="registration-request" />), include a DPoP proof in every token request, and use the resulting DPoP-bound access tokens as described in <xref target="RFC9449" section="7" />.</t>
<t>A client instance that uses non-HTTP protocols, whether exclusively or alongside HTTP-based protocols, has two choices. The simplest is not to use DPoP at all, in which case all tokens are bearer tokens. Alternatively, it MAY use DPoP for the token endpoint and for HTTP-based resources while still obtaining bearer tokens for non-HTTP resources, as follows:</t>
<ul>
<li>The client instance MUST NOT set <tt>dpop_bound_access_tokens</tt> to true when registering, as the server would then be required to issue only DPoP-bound access tokens.</li>
<li>The client instance includes a DPoP proof in every token request. As required by <xref target="RFC9449" section="5" />, the server binds the refresh token to the client instance's key, so the refresh token is sender-constrained even though some of the access tokens obtained with it are not.</li>
<li>The client instance obtains separate access tokens for HTTP and non-HTTP resources by including <tt>resource</tt> parameters in its token requests (see <xref target="obtaining-a-refresh-token" /> and <xref target="getting-a-new-access-token" />). One request lists only its HTTP-based resources, and a second lists only its non-HTTP resources (that is, hostnames, see <xref target="resource-indicators" />). The initial token request exchanging the authorization code can be made for either set, and the other set is then obtained by a refresh request.</li>
<li>Consider a token request that includes a valid DPoP proof, and in which every <tt>resource</tt> parameter is a hostname for a non-HTTP resource. A server that supports both DPoP and Resource Indicators MUST respond to such a request with an access token that is not bound to the DPoP key, with a <tt>token_type</tt> of "Bearer". For any other token request that includes a DPoP proof, the server issues a DPoP-bound access token with a <tt>token_type</tt> of "DPoP", as normal. Servers that support DPoP SHOULD therefore also support Resource Indicators, so that client instances using non-HTTP protocols are not prevented from using DPoP.</li>
<li>The client instance MUST check the <tt>token_type</tt> of each response and use the token accordingly: a "DPoP" token with the DPoP authentication scheme for HTTP requests, and a "Bearer" token with the Bearer scheme or OAUTHBEARER. If the client instance receives a "DPoP" token in response to a request that listed only non-HTTP resources, the server does not support this arrangement (for example, because it does not support Resource Indicators and ignored the parameters). The client instance MUST NOT attempt to use that token with a non-HTTP server, and MUST obtain a new authorization without using DPoP if it is to continue.</li>
</ul>
<t>A client instance can avoid the last failure case in most deployments by only attempting this arrangement when the authorization server metadata includes <tt>protected_resources</tt>, which indicates the server acts on Resource Indicators.</t>
</section>
</section>

<section anchor="scopes"><name>Scopes</name>
<t>To work interoperably, clients and servers must use a common set of scopes for access. This document creates a new IANA registry for such scopes (see <xref target="scopes-registry" />), and registers scopes to cover IMAP, SMTP, POP, ManageSieve, CardDAV, CalDAV, and JMAP.</t>
<t>Registration of a scope in that registry does not by itself impose any requirement on OAuth implementations in general (see <xref target="scopes-registry" />). This profile, however, does require support: a server implementing this profile MUST support each of the scopes registered by this document (<xref target="initial-registry-contents" />) whose definition covers a protocol or type of data that the server offers. For example, a server that offers IMAP and SMTP MUST support <tt>urn:ietf:params:oauth:scope:mail</tt>, and a server that offers CalDAV MUST support <tt>urn:ietf:params:oauth:scope:calendars</tt>. Supporting a scope means advertising it in the <tt>scopes_supported</tt> metadata property, accepting it in registration and authorization requests, and granting the access described in its registration when it is authorized.</t>
<t>The scopes registered by this document grant access to a type of data, such as the user's email, and not to particular protocols. A client granted a scope may use any of the protocols listed for it that the server supports, whether or not the user has used that protocol before. Which of these protocols a client actually uses is a matter between the client and the user, and is not part of authorization. Separate scopes for individual protocols are not defined, because the protocols covered by each scope give access to the same data, so restricting a token to one of them would not meaningfully limit what the client can access.</t>
<t>Servers MAY additionally support other scopes, for example finer-grained or vendor-specific scopes, but clients following this profile can only rely on the registered scopes being available.</t>
</section>

<section anchor="security-considerations"><name>Security Considerations</name>
<t>This profile mandates best practices for OAuth with native clients, as defined in <xref target="RFC8252" />.  A thorough discussion of the security considerations generally applicable to OAuth is out of scope for this document. It can be found in <xref target="RFC6819" />, in the OAuth 2.0 Security Best Current Practice <xref target="RFC9700" /> (BCP 240), and in the security considerations (Section 10) of <xref target="RFC6749" />.</t>
<t>Implementers are encouraged to read all of the above documents for a more thorough consideration of the specific threats and mitigations with OAuth.</t>
<t>The choices made for this profile are intended to mitigate as far as possible the inherent risks that come from allowing arbitrary clients to talk to arbitrary servers.</t>
<t>The key restriction of this profile is that the redirect_uri MUST be something only a native client can access. If the user has downloaded and run a malicious native app, it could already undetectably spoof the user's browser to phish them, or, in unsandboxed environments, install malware. Supporting the OAuth flow from an unknown client therefore does not increase the risk. Indeed, it is more secure than the current alternative, which is legitimate clients storing the user's password. This is also why claimed "https" scheme redirect URIs (<xref target="RFC8252" section="7.2" />) are excluded. Although they are the most secure redirect option on platforms that support them, an authorization server has no way to tell one from an ordinary web URL, so permitting them would permit web-based clients.</t>
<t>Access tokens, refresh tokens, and authorization codes are bearer credentials: anyone who obtains one can use it. Clients MUST only send them over connections secured with TLS, and MUST verify the server's certificate as described in <xref target="RFC9525" />. This applies to the token endpoint, to HTTP-based resource servers as required by <xref target="RFC6750" section="5.3" />, and to protocols using SASL. For IMAP, POP, and SMTP, the client MUST negotiate TLS (either Implicit TLS or STARTTLS, see <xref target="RFC8314" />) before sending the OAUTHBEARER authentication exchange. Servers MUST NOT accept access tokens over connections that are not protected by TLS. The one exception is the redirect back to a loopback redirect URI (<xref target="redirect-uri-requirements" />), which uses the "http" scheme. This carries only the authorization code, and the connection never leaves the user's device. The code is additionally protected by PKCE, so it is useless to anyone other than the client instance that holds the corresponding code verifier.</t>
<t>The dynamic registration part of this document is not a security component, as there is no way to verify any of the data. The data in the registration may be shown to the user as part of the authorization flow, which may help an attacker with phishing. However, as noted above, the redirect_uri can only be used by a native app, which could already phish the user. On the other hand, the registration gives the server more information to detect suspicious behavior, which can help it to detect compromised users and devices more easily.</t>
<t>All metadata supplied in a dynamic client registration is attacker-controlled from the authorization server's point of view. The <tt>client_name</tt>, <tt>client_uri</tt>, <tt>logo_uri</tt>, <tt>tos_uri</tt>, and <tt>policy_uri</tt> values MAY be shown to the user, but the authorization server MUST treat them as untrusted content. The authorization server MUST escape them appropriately when rendering them. It MUST NOT fetch <tt>logo_uri</tt>, or any other supplied URL, from the server side without the protections appropriate to fetching an untrusted URL, since such a fetch could otherwise be used to reach resources on the server's internal network. Any such URL may also point at malicious content, as discussed in <xref target="RFC7591" section="5" />. A logo loaded by the user's browser additionally discloses the user's IP address, and the fact that an authorization is taking place, to whoever controls the URL. Because the identity of the client cannot be verified, the authorization server SHOULD make clear on the consent page that the client is unverified, and SHOULD display the requested scopes in plain language. It MUST NOT present the registration metadata in a way that suggests it has been vetted. Servers that prefer not to display unverified metadata MAY show only the requested scopes and a generic description of the client.</t>
<t>For the same reason, a client id does not identify a particular piece of client software. A malicious application can submit the same registration as a legitimate one and may be given the same client id, and a server that returns a static client id gives every client the same one. The authorization server therefore SHOULD NOT process an authorization request under this profile without user interaction, on the basis that the user has previously authorized the same client id (see <xref target="RFC8252" section="8.6" />).</t>
<t>Refresh tokens are long-lived credentials, and DPoP private keys and pending refresh keys are equivalent in value to the tokens they protect. Client instances SHOULD store all of them in the most secure storage the platform provides, such as an operating system keychain or keystore, using hardware-backed storage where available. Client instances MUST NOT write them to logs. Where the platform offers protected storage, client instances also MUST NOT write them to storage accessible to other applications. Access tokens SHOULD be handled the same way, but MAY be held only in memory. When the user removes an account from the client, or the client is being uninstalled, the client instance SHOULD revoke its refresh token via the <tt>revocation_endpoint</tt>, if the server advertises one. This allows the server to discard the authorization immediately, rather than waiting for the token to expire through inactivity.</t>
<t>The refresh key (<xref target="refresh-token-rotation" />) allows a client instance to retry a refresh request after a lost response, without allowing an attacker with only a copy of the refresh token to do the same. It does not fully protect against an attacker that obtains both a refresh token and the refresh key used with it, before the refresh token that replaced it has been used. This could happen through a copy of the client instance's storage taken while a refresh request is outstanding, or through a leak of the request itself, for example in server-side request logs. Such an attacker can obtain the new refresh token and an access token, and has access until either it or the client instance next refreshes, at which point the reuse is detected and the authorization revoked. This is why both clients and servers are required not to log refresh keys.</t>
<t>Refresh token rotation also has an inherent limitation: an attacker that uses a stolen refresh token before the client instance next refreshes has access until that refresh, when the reuse is detected and the authorization revoked. A client instance that is used only occasionally may not refresh for some time, and if the client instance never refreshes again, the reuse is never detected. Revoking a superseded refresh token at the revocation endpoint revokes the entire authorization (see <xref target="refresh-token-rotation" />), so a client instance that revokes its refresh token when an account is removed also ends any access an attacker has obtained.</t>
<t>DPoP <xref target="RFC9449" /> addresses these limitations by binding the refresh token to the client instance's key, so that a copy of the refresh token alone is of no use to an attacker. This replaces detection with prevention, and is only as strong as the protection of the DPoP private key: it is fully effective only where the key cannot be extracted from the device, for example where it is held in hardware-backed storage. It also protects only client instances that use DPoP, and this profile does not allow a server to require it. Servers that consider these limitations unacceptable SHOULD support DPoP. Client instances are encouraged to use DPoP where the server supports it, including client instances that use non-HTTP protocols, which can do so using the arrangement described in <xref target="dpop-non-http" />.</t>
<t>Both kinds of redirect URI permitted by this profile can be claimed by software other than the client instance. Another application on the device may register the same private-use URI scheme (<xref target="RFC8252" section="8.1" />), and another process may bind the loopback port the client instance intends to use before it does (<xref target="RFC8252" section="8.3" />). In either case the authorization code may be delivered to the wrong recipient. This profile mitigates this in two ways. The code is useless without the PKCE code verifier, which never leaves the client instance, so an intercepted code cannot be exchanged (<xref target="RFC7636" section="1" />). The <tt>state</tt> parameter binds a response to a request the client instance made, so an attacker cannot inject a code of their own into the client instance's flow (<xref target="RFC9700" section="4.7" />). Client instances MUST bind a loopback listener to the loopback interface only, MUST accept at most one authorization response per listener whose <tt>state</tt> matches the request, and MUST close the listener once such a response has been received or the flow abandoned. Responses whose <tt>state</tt> does not match are ignored, as described in <xref target="authorization-response" />.</t>
<t>The issuer is expected to be autodetected from the user's email address. A threat scenario that must be considered is the user making a small typo in the domain (especially for a common email service), and an attacker controlling this domain. In this scenario the client instance will fetch the OAuth metadata from the attacker's server, and has no way to know it is not the real server the user wishes to connect to. This leads to a number of threats:</t>

<ol>
<li><t>The attacker defines a malicious authorization_endpoint under their control. They attempt to phish the user's credentials with this. The requirements of this document cannot specifically mitigate this. However, requiring origin-bound authentication, such as passkeys <xref target="WebAuthn" />, will mitigate it. Most browsers also have a block list of known phishing sites, which can help.</t>
</li>
<li><t>The attacker publishes their own authorization server metadata, copying the real <tt>authorization_endpoint</tt> and <tt>token_endpoint</tt> values but naming their own resource servers. This is a mix-up attack (<xref target="RFC9700" section="4.4" />) and is protected against by the issuer identifier check. The authorization response will include an <tt>iss</tt> parameter carrying the legitimate issuer identifier. However, the <tt>issuer</tt> property of the attacker's metadata must name the attacker's own domain. If it did not, the client instance would have aborted after fetching the metadata, as the property would not match the identifier from which the metadata URL was derived. The two therefore differ, and a client instance following this specification will abort the flow and not send the authorization code to the token endpoint.</t>
</li>
<li><t>The attacker publishes no authorization server metadata of their own. Instead, the autoconfiguration data or protected resource metadata under their control names the real authorization server's issuer identifier alongside the attacker's own resource servers. The client instance fetches the genuine metadata, and the <tt>issuer</tt> property matches. The user authenticates and grants consent at the genuine authorization server, and the <tt>iss</tt> parameter in the authorization response matches. Every check in the flow passes, because nothing has been mixed up: the client instance then presents a valid access token to the attacker's resource server, and the attacker replays it against the real one. This is the counterfeit resource server attack described in <xref target="RFC9700" section="4.9.1" />, and the issuer identifier check offers no protection against it.</t>
<t>The protection is the rule in <xref target="permitted-resource-servers" />: the authorization server vouches for its resource servers, either explicitly by publishing <tt>protected_resources</tt>, or implicitly through the resource servers sharing the registrable domain of the issuer identifier. In the example above, the attacker's host is under the mistyped domain while the issuer identifier is under the provider's domain, so the client instance refuses to send the token. Servers that support Resource Indicators <xref target="RFC8707" /> add a second, server-side layer: the client instance sends a <tt>resource</tt> value for every resource server it intends to use, and the authorization server rejects the request if any is not one of its own. Sender-constrained access tokens (<xref target="RFC9449" />) further prevent a captured HTTP access token from being replayed, but offer no protection for non-HTTP protocols, so they are not a substitute for the rule above.</t>
<t>The registrable domain rule has two limitations. First, it relies on the Public Suffix List <xref target="PSL" />, which is maintained outside the IETF and changes over time; a client instance with a stale copy may classify a host differently from an up-to-date one. Clients SHOULD keep their copy current and MUST fail closed where a host cannot be classified. Second, an attacker that controls any host within the registrable domain of the issuer identifier (for example, on a shared hosting platform or under an institution's domain) is not excluded by it. Such an attacker must also control the autoconfiguration for the domain the user entered, so the exposure is narrow. Nonetheless, it is common for a domain not to be under the close control of a single operator. For example, a university or other large organization may allow departments, staff, students, or external service providers to create host names and run their own servers within its domain. Some of those servers may be less carefully managed than the authorization server. Any deployment that cannot vouch for every host within the registrable domain of its issuer identifier SHOULD publish <tt>protected_resources</tt> to close this gap.</t>
</li>
<li><t>The attacker uses the real <tt>authorization_endpoint</tt> value and the real resource servers in its metadata, but uses their own <tt>token_endpoint</tt>. The issuer identifier check described in item 2 will also protect against this.</t></li>
</ol>
<t>This specification allows clients to fall back to the OpenID Connect Discovery metadata path if the RFC 8414 metadata path fails. Implementers should be aware that these two paths have different security properties when the issuer identifier contains a path component. The RFC 8414 path inserts the well-known component at the host root (e.g., <tt>https://auth.example.com/.well-known/oauth-authorization-server/acmeinc</tt>), meaning only an entity with control over the host can serve this document. The OpenID Connect Discovery path appends the well-known component to the issuer (e.g., <tt>https://auth.example.com/acmeinc/.well-known/openid-configuration</tt>), meaning any entity that controls the path can serve this document. In multi-tenant environments where different entities control different paths on the same host, the OpenID Connect Discovery fallback allows a tenant to serve their own metadata without host-level control. The issuer identifier verification remains the primary defense against mix-up attacks in all cases. However, operators of shared hosts should be aware that the RFC 8414 path provides an additional layer of host-level vetting that the OpenID Connect Discovery path does not.</t>
</section>

<section anchor="iana-considerations">
<name>IANA Considerations</name>

<section anchor="scopes-registry">
<name>Interoperable OAuth Scopes Registry</name>

<t>IANA is requested to add a new registry called "Interoperable OAuth Scopes" to the "OAuth Parameters" registry group <xref target="IANA.OAuth.Parameters" />. The registry records OAuth scope values that have a standardized, interoperable meaning, such that a client and a server with no pre-existing relationship can agree on the access that is granted by a scope. Each scope provides specific access rights to protected resources, and the registry records a reference to the specification that defines those rights.</t>

<section anchor="registry-applicability">
<name>Applicability of Registered Scopes</name>

<t>Registration of a scope in this registry does not, by itself, impose any requirement on OAuth authorization servers, resource servers, or clients in general. An OAuth implementation is not required to recognize, support, or grant any scope in this registry merely because it is registered. In this respect the registry is a coordination mechanism, ensuring a given scope value has a single well-defined meaning wherever it is used, rather than a statement of what OAuth implementations must support.</t>

<t>Support for a registered scope is required only where a profile or other specification that references this registry mandates it. Such a specification MUST clearly identify which implementations are required to support which scopes. This document is one such profile: the scopes that servers implementing this profile MUST support are specified in <xref target="scopes" />. Other profiles MAY reference scopes in this registry and define their own support requirements, and the same scope MAY be required by more than one profile.</t>
</section>

<section anchor="scope-naming">
<name>Scope Naming Conventions</name>

<t>Each scope value can be registered only once. Scope names in this registry are case sensitive, but a name MUST NOT match another registered name in a case-insensitive manner unless the designated experts state that there is a compelling reason to allow an exception. These rules apply to all registrations, whether the value is a URN or an unstructured string.</t>

<t>A newly defined scope registered in this registry MUST be a URN in the <tt>urn:ietf:params:oauth:scope:</tt> sub-namespace of the OAuth URN namespace <xref target="RFC6755" />, of the form <tt>urn:ietf:params:oauth:scope:&lt;name&gt;</tt>, for example <tt>urn:ietf:params:oauth:scope:mail</tt>. The <tt>&lt;name&gt;</tt> component SHOULD be a short, lowercase, descriptive identifier for the class of data or resources to which the scope grants access. Using this namespace guarantees the value cannot collide with scope strings defined elsewhere, and makes clear to implementers that the value has a standardized meaning. Any such URN MUST also be registered in the IANA "OAuth URI" registry <xref target="IANA.OAuth.Parameters" /> established by <xref target="RFC6755" />, referencing the same specification document(s).</t>

<t>An unstructured scope string, that is, one that is not a URN in the above sub-namespace, MAY be registered only where all of the following apply:</t>
<ul>
<li>The scope value is already defined by an existing, publicly available and stable specification outside of the IETF's control, or is already in widespread deployment with a single well-understood meaning.</li>
<li>The purpose of the registration is to allow profiles referencing this registry to interoperate with that existing usage. Assigning a new URN for the same purpose would therefore harm interoperability rather than help it.</li>
</ul>
<t>Unstructured strings MUST NOT be registered for newly defined scopes. Where a specification wishes to register a scope with an unstructured name, the designated experts MUST verify that the referenced specification defines the value with the meaning given in the registration request.</t>
</section>

<section anchor="registration-procedure">
<name>Registration Procedure</name>

<t>Values are registered via Specification Required <xref target="RFC8126" />. Registration requests should be sent to the <eref target="mailto:oauth-ext-review@ietf.org">oauth-ext-review@ietf.org</eref> mailing list to initiate a two-week review period. To allow for the allocation of values prior to publication of the final version of a specification, the designated experts may approve registration once they are satisfied that the specification will be completed and published. However, if the specification is not completed and published in a timely manner, as determined by the designated experts, the designated experts may request that IANA withdraw the registration.</t>

<t>Registration requests sent to the mailing list for review should use an appropriate subject (e.g., "Request to register Interoperable OAuth Scope: example").</t>

<t>Within the review period, the designated experts will either approve or deny the registration request, communicating this decision to the review list and IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. If the designated experts are not responsive, the registration requesters should contact IANA to escalate the process.</t>

<t>Designated experts should apply the following criteria when reviewing proposed registrations:</t>
<ul>
<li>The proposed scope must be unique, that is, it must not duplicate the functionality of an existing registration.</li>
<li>The proposed scope is likely to be generally applicable, that is, useful to multiple independent clients and servers, as opposed to being used for a single application or deployment.</li>
<li>The proposed scope name follows the naming conventions in <xref target="scope-naming" />. In particular, an unstructured (non-URN) scope name is only permitted under the conditions given there.</li>
<li>The description clearly defines the access rights granted by the scope, with reference to publicly available and stable documentation sufficient for interoperability.</li>
<li>The specification document(s) identify which implementations are required to support the scope (for example, by defining or referencing a profile that mandates it), since registration alone imposes no such requirement (see <xref target="registry-applicability" />).</li>
<li>The change controller is clearly identified.</li>
</ul>

<t>IANA must only accept registry updates from the designated experts and should direct all requests for registration to the review mailing list.</t>

<t>In order to enable broadly informed review of registration decisions, there should be multiple designated experts to represent the perspectives of different applications using this specification. In cases where registration may be perceived as a conflict of interest for a particular expert, that expert should defer to the judgment of the other experts.</t>

<t>The mailing list is used to enable public review of registration requests, which enables both designated experts and other interested parties to provide feedback on proposed registrations. Authors are encouraged to send a registration request for review while their specification is still in draft, so that any issues identified can be fixed before it is published. This is independent of whether the designated experts choose to allocate values before publication, as described above.</t>

</section>

<section anchor="registration-template">
<name>Registration Template</name>

<dl newline="false" spacing="compact">
<dt>Scope Name:</dt>
    <dd>The OAuth scope value requested (e.g., <tt>urn:ietf:params:oauth:scope:mail</tt>). This name is case sensitive and MUST conform to <xref target="scope-naming" />.</dd>

<dt>Description:</dt>
    <dd>A clear description of what access rights this scope grants to the client, with reference to publicly available and stable documentation sufficient for interoperability.</dd>

<dt>Change Controller:</dt>
    <dd>For IETF Stream RFCs, list "IETF". For others, give the name of the responsible party. Other details (e.g., postal address, email address, home page URL) may also be included.</dd>

<dt>Specification Document(s):</dt>
    <dd>Reference to the document or documents that specify the scope, preferably including URLs that can be used to retrieve copies of the documents. An indication of the relevant sections may also be included but is not required. The referenced document(s) MUST identify which implementations are required to support the scope (see <xref target="registry-applicability" />).</dd>
</dl>

</section>

<section anchor="initial-registry-contents">
<name>Initial Registry Contents</name>

<dl newline="false" spacing="compact">
<dt>Scope Name:</dt> <dd><tt>urn:ietf:params:oauth:scope:mail</tt></dd>
<dt>Description:</dt>
<dd>
  <t>Requests access for a client to manage the user's email. This MUST include full access via all of the following protocols that the server supports, regardless of which of them the client actually uses (see <xref target="scopes" />):</t>
  <ul>
    <li>IMAP <xref target="RFC9051" /></li>
    <li>POP <xref target="RFC1939" /></li>
    <li>SMTP submission <xref target="RFC6409" /></li>
    <li>ManageSieve <xref target="RFC5804" /></li>
    <li>JMAP <xref target="RFC8620" /> - this scope grants the right to use all JMAP capabilities that the server supports for which <tt>urn:ietf:params:oauth:scope:mail</tt> is included in the Interoperable OAuth Scopes column of the JMAP capabilities registry.</li>
  </ul>
</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> and <xref target="scopes" /> of this document</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Scope Name:</dt> <dd><tt>urn:ietf:params:oauth:scope:contacts</tt></dd>
<dt>Description:</dt> <dd>Requests access for a client to manage the user's contacts. This MUST include full access via the CardDAV protocol <xref target="RFC6352" /> if the server supports it. If the server supports JMAP <xref target="RFC8620" />, this scope grants the right to use all JMAP capabilities that the server supports for which <tt>urn:ietf:params:oauth:scope:contacts</tt> is included in the Interoperable OAuth Scopes column of the JMAP capabilities registry.</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> and <xref target="scopes" /> of this document</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Scope Name:</dt> <dd><tt>urn:ietf:params:oauth:scope:calendars</tt></dd>
<dt>Description:</dt> <dd>Requests access for a client to manage the user's calendars. This MUST include full access via the CalDAV protocol <xref target="RFC4791" /> if the server supports it. If the server supports JMAP <xref target="RFC8620" />, this scope grants the right to use all JMAP capabilities that the server supports for which <tt>urn:ietf:params:oauth:scope:calendars</tt> is included in the Interoperable OAuth Scopes column of the JMAP capabilities registry.</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> and <xref target="scopes" /> of this document</dd>
</dl>

</section>
</section>

<section anchor="oauth-parameters-registry-update">
<name>Update to the OAuth Parameters Registry</name>
<t>IANA is requested to update the registration of the <tt>username</tt> parameter in the "OAuth Parameters" registry <xref target="IANA.OAuth.Parameters" /> established by <xref target="RFC6749" section="11.2" />, adding "token response" to its parameter usage location and adding this document to its specification document(s). The updated registration is as follows:</t>
<dl newline="false" spacing="compact">
<dt>Parameter name:</dt> <dd><tt>username</tt></dd>
<dt>Parameter usage location:</dt> <dd>token request, token response</dd>
<dt>Change controller:</dt> <dd>IETF</dd>
<dt>Specification document(s):</dt> <dd><xref target="RFC6749" section="4.3.2" />; <xref target="token-response" /> of this document</dd>
</dl>
<t>The use of the <tt>username</tt> parameter in a token response is defined in <xref target="token-response" />. Its use in a token request, defined by <xref target="RFC6749" section="4.3.2" />, is unchanged.</t>
<t>IANA is also requested to register the following parameter in the "OAuth Parameters" registry:</t>
<dl newline="false" spacing="compact">
<dt>Parameter name:</dt> <dd><tt>refresh_key</tt></dd>
<dt>Parameter usage location:</dt> <dd>token request</dd>
<dt>Change controller:</dt> <dd>IETF</dd>
<dt>Specification document(s):</dt> <dd><xref target="getting-a-new-access-token" /> and <xref target="refresh-token-rotation" /> of this document</dd>
</dl>
</section>

<section anchor="oauth-uri-registrations">
<name>OAuth URI Registrations</name>

<t>This section registers the following values in the IANA "OAuth URI" registry <xref target="IANA.OAuth.Parameters" /> established by <xref target="RFC6755" />. They are the scope values defined by this document within the <tt>urn:ietf:params:oauth:scope:</tt> sub-namespace, as required by <xref target="scope-naming" />.</t>

<dl newline="false" spacing="compact">
<dt>URN:</dt> <dd><tt>urn:ietf:params:oauth:scope:mail</tt></dd>
<dt>Common Name:</dt> <dd>Interoperable OAuth scope granting access to the user's email</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> of this document</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>URN:</dt> <dd><tt>urn:ietf:params:oauth:scope:contacts</tt></dd>
<dt>Common Name:</dt> <dd>Interoperable OAuth scope granting access to the user's contacts</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> of this document</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>URN:</dt> <dd><tt>urn:ietf:params:oauth:scope:calendars</tt></dd>
<dt>Common Name:</dt> <dd>Interoperable OAuth scope granting access to the user's calendars</dd>
<dt>Change Controller:</dt> <dd>IETF</dd>
<dt>Specification Document(s):</dt> <dd><xref target="initial-registry-contents" /> of this document</dd>
</dl>
</section>
<section anchor="jmap-capabilities-registry-update">
<name>Update to the JMAP Capabilities Registry</name>

<t>IANA is requested to update the "JMAP Capabilities" registry established in <xref target="RFC8620" /> to add a new column called "Interoperable OAuth Scopes". For each capability, this column shall contain a list of zero or more scopes registered in the Interoperable OAuth Scopes Registry. Authorization for any scope in the list will grant access to use that JMAP capability, if the capability is supported by the server.</t>
<t>The <tt>urn:ietf:params:jmap:blob</tt> and <tt>urn:ietf:params:jmap:quota</tt> capabilities are listed with more than one scope. These provide additional ways of using data, for example manipulating blobs or seeing quota usage, but do not grant any additional access rights. Authorization for a scope never gives a client access to a blob, or other data, that it could not access through the capabilities granted by its authorized scopes, whichever mechanism it uses, including the <tt>downloadUrl</tt> of the JMAP Session object. For example, a client authorized only for <tt>urn:ietf:params:oauth:scope:mail</tt> may use the blob capability, or the <tt>downloadUrl</tt>, to access blobs referenced by the user's email, but not blobs referenced by calendar data, as it has not been granted the calendars capability.</t>

<t>Future registrations in the "JMAP Capabilities" registry SHOULD specify a value for the Interoperable OAuth Scopes column in addition to the fields established in the registration template by <xref target="RFC8620" section="9.4.5"/>. If omitted, registrations will be added with no value for this column (i.e., no interoperable scopes are available to grant access to this capability via OAuth).</t>

<section anchor="jmap-capabilities-initial-scopes">
<name>Initial Interoperable OAuth Scopes Values for the JMAP Capabilities Registry</name>

<t>IANA is requested to update the existing JMAP Capabilities registrations with the following values for the Interoperable OAuth Scopes column.</t>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:core</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:mail</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:mdn</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:smimeverify</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:submission</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:vacationresponse</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:blob</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:quota</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:sieve</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:principals</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:principals:owner</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:contacts</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:contacts</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:calendars</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:principals:availability</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:webpush-vapid</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>

<dl newline="false" spacing="compact">
<dt>Capability Name:</dt> <dd>urn:ietf:params:jmap:websocket</dd>
<dt>Interoperable OAuth Scopes:</dt> <dd>urn:ietf:params:oauth:scope:mail, urn:ietf:params:oauth:scope:contacts, urn:ietf:params:oauth:scope:calendars</dd>
</dl>
</section>
</section>
</section>

</middle>

<back>

<references><name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.3986.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4791.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4918.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5397.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5890.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6352.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6570.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6638.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6749.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6750.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6755.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7009.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7591.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7628.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7636.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8126.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8174.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8252.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8414.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8620.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8707.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8887.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9207.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9449.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9525.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9700.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9728.xml"/>
<reference anchor="PSL" target="https://publicsuffix.org/list/">
  <front>
    <title>Public Suffix List</title>
    <author><organization>Mozilla Foundation</organization></author>
  </front>
</reference>
<reference anchor="WebAuthn" target="https://www.w3.org/TR/2021/REC-webauthn-2-20210408/">
  <front>
    <title>Web Authentication: An API for accessing Public Key Credentials - Level 2</title>
    <author initials="J." surname="Hodges" fullname="Jeff Hodges" role="editor">
      <organization>PayPal</organization>
      <address>
        <email>jdhodges@google.com</email>
      </address>
    </author>
    <author initials="J.C." surname="Jones" fullname="J.C. Jones" role="editor">
      <organization>Mozilla</organization>
      <address>
        <email>jc@mozilla.com</email>
      </address>
    </author>
    <author initials="M.B." surname="Jones" fullname="Michael B. Jones" role="editor">
      <organization>Microsoft</organization>
      <address>
        <email>mbj@microsoft.com</email>
        <uri>http://self-issued.info/</uri>
      </address>
    </author>
    <author initials="A." surname="Kumar" fullname="Akshay Kumar" role="editor">
      <organization>Microsoft</organization>
      <address>
        <email>akshayku@microsoft.com</email>
      </address>
    </author>
    <author initials="E." surname="Lundberg" fullname="Emil Lundberg" role="editor">
      <organization>Yubico</organization>
      <address>
        <email>emil@yubico.com</email>
      </address>
    </author>
    <date day="8" month="April" year="2021"/>
  </front>
  <refcontent>W3C Recommendation</refcontent>
</reference>
<reference anchor="OpenID.Core" target="https://openid.net/specs/openid-connect-core-1_0.html">
  <front>
    <title>OpenID Connect Core 1.0</title>
    <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
      <organization abbrev="NAT.Consulting (was at NRI)">NAT.Consulting</organization>
    </author>
    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization abbrev="Yubico (was at Ping Identity)">Yubico</organization>
    </author>
    <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
      <organization abbrev="Self-Issued Consulting (was at Microsoft)">Self-Issued Consulting</organization>
    </author>
    <author fullname="Breno de Medeiros" initials="B." surname="de Medeiros">
      <organization abbrev="Google">Google</organization>
    </author>
    <author fullname="Chuck Mortimore" initials="C." surname="Mortimore">
      <organization abbrev="Disney (was at Salesforce)">Disney</organization>
    </author>
    <date day="15" month="December" year="2023"/>
  </front>
</reference>
<reference anchor="OpenID.Discovery" target="https://openid.net/specs/openid-connect-discovery-1_0.html">
  <front>
    <title>OpenID Connect Discovery 1.0</title>
    <author fullname="Nat Sakimura" initials="N." surname="Sakimura">
      <organization abbrev="NAT.Consulting (was at NRI)">NAT.Consulting</organization>
    </author>
    <author fullname="John Bradley" initials="J." surname="Bradley">
      <organization abbrev="Yubico (was at Ping Identity)">Yubico</organization>
    </author>
    <author fullname="Michael B. Jones" initials="M.B." surname="Jones">
      <organization abbrev="Self-Issued Consulting (was at Microsoft)">Self-Issued Consulting</organization>
    </author>
    <author fullname="Edmund Jay" initials="E." surname="Jay">
      <organization abbrev="Illumila">Illumila</organization>
    </author>
    <date day="15" month="December" year="2023"/>
  </front>
</reference>
</references>

<references><name>Informative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.1939.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2384.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5092.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.5804.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6409.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.6819.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.7595.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.8314.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.9051.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.ietf-mailmaint-pacc.xml"/>
<reference anchor="IANA.OAuth.Parameters" target="https://www.iana.org/assignments/oauth-parameters">
  <front>
    <title>OAuth Parameters</title>
    <author><organization>IANA</organization></author>
  </front>
</reference>
<reference anchor="IANA.JOSE.ALGS" target="https://www.iana.org/assignments/jose">
  <front>
    <title>JSON Web Signature and Encryption Algorithms</title>
    <author><organization>IANA</organization></author>
  </front>
</reference>
</references>

</back>

</rfc>
