Automatic Configuration of Email, Calendar, and Contact Server Settings

4.1. Example

The following example demonstrates a typical JSON configuration:¶

{
    "protocols": {
        "jmap": {
            "url": "https://jmap.example.com/session"
        },
        "imap": {
            "host": "imap.example.com"
        },
        "pop3": {
            "host": "pop3.example.com"
        },
        "smtp": {
            "host": "smtp.example.com"
        },
        "caldav": {
            "url": "https://sync.example.com/calendar/"
        },
        "carddav": {
            "url": "https://sync.example.com/contacts/"
        }
    },
    "authentication": {
        "oauth-public": {
            "issuer": "https://auth.example.com/"
        },
        "password": true
    },
    "info": {
        "provider": {
            "name": "Example Provider Name",
            "shortName": "Example",
            "logo": [
                {
                    "url": "https://www.example.net/logo.svg",
                    "content-type": "image/svg+xml"
                }
            ]
        },
        "help": {
            "documentation": "https://help.example.net/howto/set-up-your-mail-app.html",
            "developer": "https://developer.example.net/client-apps/",
            "contact": ["mailto:it@team.example.net"]
        }
    }
}

4.2. Protocols

The protocols object specifies all protocols that the domain supports and identifies the server endpoint for each protocol.¶

For the following HTTP-based protocols:¶

• JMAP defined in [RFC8620],¶
• CalDAV defined in [RFC4791], and¶
• CardDAV defined in [RFC6352]¶
• WebDAV defined in [RFC4918]¶

each protocol entry MUST include a url value containing a URL with the https scheme. This URL MUST specify an endpoint that serves the corresponding protocol. The server MUST use the default port 443 for HTTPS, and the URL MUST NOT include an explicit port number.¶

Hostnames in URLs MUST support Internationalized Domain Names (IDNs) as defined in [RFC5890] and [RFC5891]. Service providers MAY use either Unicode labels (u-labels) or ASCII Compatible Encoding labels (a-labels) in their configuration. User agents MUST support both forms and handle the conversion between them as specified in [RFC5891].¶

Example:¶

"jmap": {
    "url": "https://jmap.example.com/session"
}

For the following text-based protocols:¶

• IMAP defined in [RFC9051],¶
• SMTP defined in [RFC5321], and¶
• POP3 defined in [RFC1939]¶
• ManageSieve defined in [RFC5804]¶

each protocol entry MUST include a host value specifying the hostname of the server that provides the corresponding protocol. The server MUST use the default port number for that protocol, with connections secured using TLS. Section 5.4.3 goes into details about TLS and which ports to use.¶

Hostnames MUST support Internationalized Domain Names (IDNs) as defined in [RFC5890] and [RFC5891]. Service providers MAY use either Unicode labels (u-labels) or ASCII Compatible Encoding labels (a-labels) in their configuration. User agents MUST support both forms and handle the conversion between them as specified in [RFC5891].¶

Example:¶

"imap": {
    "host": "imap.mail.example.com"
}

4.3. Authentication

The authentication object specifies which authentication mechanisms the provider supports.¶

The nested password value indicates whether the provider supports username and password authentication.¶

The nested oauth-public object contains a single issuer value that specifies the authorization server's issuer identifier as defined in [RFC8414]. This value is a URL that uses the https scheme and has no query or fragment components. User agents can use this identifier for authentication via [OAuthPublic]. The presence of the oauth-public object indicates that the provider supports OAuth.¶

4.4. Informational

The info object contains information that user agents can present to users. The only required field is info/provider/name, which SHOULD clearly identify the provider to the user. The optional info/provider/shortName provides a shorter version of name.¶

The info/provider/logo array can contain one or more entries pointing to the provider's logo images. User agents can use these to display the provider's logo to users.¶

The info/help/documentation field provides a URL that can be presented to users for additional information about the provider. The info/help/developer field contains a URL with information specifically for user agent developers. The info/help/contact array lists URLs that users can use to contact the provider, such as mailto URLs.¶

A minimal info example:¶

"info": {
    "provider": {
        "name": "Example Provider Name"
    }
}

5.1. Email Address

During the initial configuration process, the user agent requests the user's email address. User agents SHOULD accept any valid mailbox format as specified in Section 3.4 of [RFC5322].¶

5.2. Configuration Source

After the user provides their email address, the user agent extracts the domain part of the user's email address according to Section 3.4.1 of [RFC5322]. For example:¶

This domain is then used to retrieve the JSON configuration resource.¶

There are two methods for retrieving the JSON configuration: a primary method and an MX fallback method. The primary method should be attempted first, with the MX fallback method used only if the primary method fails.¶

https://ua-auto-config.{domain}/.well-known/user-agent-configuration.json

https://ua-auto-config.foo.example.com/.well-known/user-agent-configuration.json

C: GET /.well-known/user-agent-configuration.json HTTP/2
C: Host: foo.example.com
C: user-agent: curl/8.4.0
C: accept: application/json
C:

S: HTTP/2 200
S: server: nginx/1.25.3
S: date: Mon, 23 Oct 2025 10:30:00 GMT
S: content-type: application/json
S: content-length: 1184
S:
S: {
S:     "protocols": {
S:         "jmap": {
S: ...

config-record   = tag-value *( *WSP ";" *WSP tag-value ) *WSP [";"]

tag-value       = version-tag / alg-tag / digest-tag / future-tag

version-tag     = "v" *WSP "=" *WSP "UAAC1"
alg-tag         = "a" *WSP "=" *WSP digest-algorithm
digest-algorithm = "sha256" / "sha512" / "sha3-512"
digest-tag      = "d" *WSP "=" *WSP 1*base64-char

future-tag      = 1*tag-name *WSP "=" *WSP 1*tag-value-char

tag-name        = ALPHA / DIGIT
tag-value-char  = %x21-3A / %x3C-7E ; Any visible ASCII char
                                  ; except semicolon

base64-char     = ALPHA / DIGIT / "+" / "/" / "="
; As defined in Section 4 of RFC 4648

WSP             = " " / HTAB
; As defined in Appendix B.1 of RFC 5234

https://ua-auto-config.{mx-hostname}/.well-known/user-agent-configuration.json

https://ua-auto-config.bar.mail.example.com/.well-known/user-agent-configuration.json

5.3. Configuration JSON Validation

After successfully retrieving a configuration resource, user agents MUST validate that the configuration contains valid JSON syntax according to RFC 8259. Additionally, user agents MUST validate the retrieved configuration against the JSON schema specification provided in Appendix A. If the JSON syntax is invalid, user agents MUST ignore the configuration entirely and not use any portion of it.¶

User agents MUST process only the properties that they support and MUST ignore properties not specified in the schema. This requirement enables future extensions of the format without breaking existing user agent implementations.¶

5.4. Selecting Protocols and Authentication

After successfully retrieving and validating the configuration JSON, the user agent needs to determine:¶

• Which protocols to use¶
• Which authentication mechanism to employ¶

Both user agents and servers support multiple protocols. The user agent needs to decide which protocols to use and determine whether the protocols specified in the configuration are sufficient to proceed. This document does not provide recommendations regarding protocol preferences or minimum protocol requirements, as these decisions depend on the specific needs and implementation details of individual user agents.¶

The automatic configuration flow supports two distinct authentication types:¶

• Username and password-based authentication¶
• OAuth-based authentication¶

User agents can support one or both authentication methods. Similarly, servers for each protocol can support one or both methods. Additionally, the specific implementation details of authentication can vary between protocols.¶

User agents SHOULD probe each protocol and server of interest to determine compatible authentication methods. This probing process can influence the user agent's protocol selection and allows the user agent to verify server availability.¶

This document does not provide recommendations regarding protocol preferences. The user agent MUST make these decisions based on its needs.¶

If the user agent determines that it can use either password-based authentication or OAuth authentication, the user agent SHOULD prefer OAuth-based authentication.¶

{issuer}/.well-known/oauth-authorization-server

"oauth-public" : {
    "issuer" : "https://auth.example.com"
},

GET /jmap/session HTTP/1.1
host: api.example.com
accept: application/json

HTTP/1.1 401 Unauthorized
www-authenticate: Bearer realm="api.example.com"

========== NOTE: '\' line wrapping per RFC 8792 ===========

HTTP/1.1 401 Unauthorized
www-authenticate: Digest realm="api.example.com", qop="auth", \
algorithm=SHA-256, nonce="dcd98b7102dd2f0e8b11d0f600bfb0c093", \
opaque="5ccc069c403ebaf9f0171e9517f40e41"

S: * OK [CAPABILITY IMAP4 IMAP4rev1 SASL-IR AUTH=PLAIN AUTH=OAUTHBEARER] IMAP Server
C: A1 LOGOUT
S: * BYE
S: A1 OK

S: 220 smtp.example.com ESMTP service ready
C: EHLO client.example.com
S: 250-smtp.example.com
S: 250-PIPELINING
S: 250-SIZE 10240000
S: 250-AUTH PLAIN LOGIN OAUTHBEARER
S: 250-ENHANCEDSTATUSCODES
S: 250 8BITMIME
C: QUIT
S: 221 Bye

S: +OK pop.example.com POP3 server ready
C: CAPA
S: +OK List of capabilities follows
S: SASL PLAIN OAUTHBEARER
S: IMPLEMENTATION BlurdyBlurp POP3 server
S: .
C: QUIT
S: +OK POP3 server signing off (maildrop empty)

5.5. Confirming Server Names

The client SHOULD display to the user the hostnames of all servers that it intends to authenticate with. This list of server hostnames gives the user a chance to validate if they want to move ahead.¶

The client MAY choose to limit the hostnames to their second-level domain names when displaying this list. Instead of displaying mail.example.com the client would display example.com if it chooses to do so. Limiting the hostnames to their second-level domain names helps users identify if this is the domain they intend to connect to or not.¶

The client MUST NOT cut off parts of long second-level domains, to avoid spoofing. At least 63 characters of the second-level domain names MUST be displayed.¶

If the user mistyped their email address in Section 5.1, letting the user confirm the server hostnames gives the user a chance to notice this.¶

Clients can enhance the user experience by using the info section of the configuration (described in Section 4.4) to display the provider's name and logo during this configuration step.¶

Section 7.1 list security considerations related to the user confirming these hostnames.¶

5.6. Username

For password-based authentication, the full addr-spec part of the email address MUST be used as the username. For example:¶

For OAuth Profile for Open Public Clients, the client MUST send this username as the login_hint in the authorization request URL.¶

The provider MUST ensure that any valid email address that the user might enter during setup is a valid username for all servers given in this configuration. This will require a mapping on the server level from email address to internal username. This mapping happens internally in the server and the client is not involved in this mapping.¶

5.7. Configuring OAuth

If the client and the provider both support OAuth Profile for Open Public Clients, and if the servers that the client wants to use support OAuth, the client can configure OAuth.¶

The authentication section in the JSON configuration described in Section 4.3 will let the client create a URL to retrieve the OAuth Authorization Server Metadata as described in section Section 5.4.1. With this metadata, the client can then use [OAuthPublic] to configure OAuth.¶

Part of this will require opening the authorization request URL in an external user-agent, which is typically the default browser. The client SHOULD make it very apparent to the user which hostname is being used for the authorization request URL. The client SHOULD make the user confirm least the second-level domain name(s) of the hostname of this URL. This is to minimize the risk of the user exposing their credentials to a third party.¶

As described in Section 5.5, the client SHOULD also confirm the server hostnames with the user. For OAuth authentication, the client SHOULD include the hostname of the authorization request URL in this list of hostnames.¶

5.8. Configuring Password-Based Authentication

If the client and provider both support password-based authentication, and if the servers that the client wants to use support password-based authentication, the client can configure itself to use these servers.¶

The client SHOULD at this point ask the user for the password for their account with the provider.¶

Once the user has entered their password, the client SHOULD validate that it is able to authenticate using the entered password with all servers that it is interested in. Only then would it save the new configuration.¶

6.1. User Approval

Regardless of the mechanism used to obtain the configuration, clients SHOULD display the configuration details to users and request explicit confirmation before use. During this confirmation process:¶

• At least the second-level domain names of all involved hostnames MUST be displayed clearly and prominently.¶

• Clients MUST NOT truncate long second-level domain names to prevent spoofing attacks. At least 63 characters MUST be displayed.¶

6.2. OAuth2 requirements

If OAuth2 is used, the OAuth2 server MUST adhere to [OAuthPublic].¶

Notably, the Dynamic Client Registration MUST be implemented and return a working Client ID in response HTTP calls defined by the specification.¶

The OAuth2 scopes defined in [OAuthPublic] MUST be included and MUST give access to the servers returned in the JSON configuration described in Section 4.¶

A single token MUST work for all servers in the JSON configuration, such that a single user login is sufficient for all services. For that purpose, the client will include all relevant scopes in the authentication requests.¶

7.1. Mistyped Domain Names

As part of the first step of the mechanism described in this document, the user enters their email address. If the user mistyped the domain part of their email address, and if the mistyped domain exists and supports the mechanism described in this document, the user could expose their credentials to the owner of that domain. An attacker could use this in an attempt to gain knowledge of the user’s credentials.¶

As a result, user agents need to carefully design their user interface and user experience as to let the user know which domain is being used. It would make sense to display this very clearly to the user, before they enter any credentials.¶

The user agent would want to display a list of all second-level domains (SLDs) for all the servers that it intends to use. The user can then confirm these.¶

When the mechanism described in this document uses OAuth, it would make sense to ask the user to confirm the domains of the servers that will be used and additionally confirm the domains of¶

• the URL to retrieve the OAuth Authorization Server Metadata and/or¶
• the authorization request URL.¶

When asking the user to confirm these domains, it would make sense to only display the second-level domain (SLD) of those domains. This would make it more difficult for an attacker to do URL obfuscation and use subdomain phishing.¶

When using a browser for OAuth, the user agent would want to display the second-level domain (SLD) that the browser is currently displaying, and update this when redirects happen or new pages are loaded.¶

7.2. Attacker Controlled JSON Configuration

If an attacker can direct the user agent to use an attacker-controlled JSON configuration, the attacker would be able to direct the user to servers of the attacker's choosing.¶

In Section 7.1 some mechanisms to limit this attack vector are described.¶

However, the user agent needs to combine this with a conservative trust policy for its TLS when retrieving the JSON configuration.¶

7.3. DNS

If the user agent uses the DNS mechanisms described in Section 5.2.1.2, care needs to be taken to make sure that an attacker hasn't altered the DNS response. Using DNSSEC is one method of improving the security aspects of this approach. Alternatively, user agents MAY choose not use the DNS based mechanisms described in Section 5.2.1.2 at all.¶

7.4. Transport Security Validation

Whenever secure transport is used (including TLS for HTTPS connections and QUIC's TLS-based security layer for HTTP/3), user agents MUST check the certificates presented by the server. This certificate MUST not be expired and MUST chain to a root CA that is trusted by the user agent. The certificate MUST have a subject alternative name (SAN) ([RFC5280]) with a DNS-ID ([RFC6125]) matching the hostname, per the rules given in [RFC6125]. The certificate MAY also be checked for revocation via OCSP ([RFC6960]), CRLs ([RFC6818]), or some other mechanism. The general TLS usage guidance in [RFC7525] SHOULD be followed.¶

If these checks fail or the server certificate is otherwise invalid, the user agent MUST disconnect and MUST NOT use any configuration retrieved from that URI.¶

Certificate validation failures represent significant security risks, as they may indicate attempts to redirect users' credentials to an attacker. User agents SHOULD NOT allow users to override certificate validation checks.¶

User agents MAY implement more restrictive transport security policies for configuration retrieval than those typically required for web browsing, in order to provide stronger security guarantees. For TLS connections, user agents MAY want to limit the allowed protocol version(s) to recent versions, and MAY similarly want to restrict the allowed cipher suites. For QUIC connections, user agents MAY apply similar restrictions to the underlying TLS handshake parameters.¶

The HTTP server serving the Well-Known resource described in Section 5.2.1.1 MUST have support for TLS 1.3 ([RFC8446]) or higher.¶

7.5. Updating the Configuration

The mechanism described in this document can be used to upgrade a user's configuration. The user agent could check for configurations even when it has a working configuration for an account. If the user agent finds a configuration that is better (in some way) than the already existing configuration, it could then upgrade the existing configuration.¶

But in doing so, the user agent would increase the attack window that a potential attacker has. Instead of only giving an attacker the opportunity when the user configures their user agent for the first time, the attacker would now have an opportunity each time the user agent checks for a better configuration. That could be undesirable.¶

7.6. Provider Information

Image parsers are a common attack vector, and clients MUST NOT display the logo images described in Section 4.4.1 unless they can do so in a way that doesn't expose the client to such attacks.¶

8.1. The User-Agent Auto-Configuration Protocol Registry

This document establishes the user-agent auto-configuration protocol registry.¶

User-agent auto-configuration protocols are registered on the advice of one or more Designated Experts (appointed by the IESG or their delegate), with a Specification Required (using terminology from [RFC8126]). However, to allow for the allocation of values prior to publication, the Designated Expert(s) may approve registration once they are satisfied that such a specification will be published.¶

Registration requests are sent to the ____@ietf.org mailing list for review and comment, with an appropriate subject (e.g., "Request for well-known URI: example").¶

Before a period of 14 days has passed, the Designated Expert(s) will either approve or deny the registration request, communicating this decision both to the review list and to IANA. Denials should include an explanation and, if applicable, suggestions as to how to make the request successful. Registration requests that are undetermined for a period longer than 21 days can be brought to the IESG's attention (using the iesg@iesg.org mailing list) for resolution.¶

Registry Name:

User-Agent Auto-Configuration Protocols¶

Registration Procedure:

Specification Required (per [RFC8126])¶

8.2. Registration