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": "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]¶

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.¶

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]¶

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.¶

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 issuer identifier. 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 client extracts the domain part of the user’s email address according to Section 3.4.1 of [RFC5322]. For example¶

https://{domain}/.well-known/user-agent-configuration

https://foo.example.com/.well-known/user-agent-configuration

C: GET /.well-known/user-agent-configuration 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: ...

;; QUESTION SECTION:
;_ua-auto-config._https.foo.example.com.        IN    SRV

;; ANSWER SECTION:
_ua-auto-config._https.foo.example.com. 7200 IN    SRV    10 60 443 qux.example.com.

https://qux.example.com/.well-known/user-agent-configuration

;; QUESTION SECTION:
;foo.example.com.        IN    MX

;; ANSWER SECTION:
foo.example.com.    3600    IN    MX    10 mail1.example.com.
foo.example.com.    3600    IN    MX    20 mail2.example.com.

;; QUESTION SECTION:
;_ua-auto-config._https.mail1.example.com.        IN    SRV

;; ANSWER SECTION:
_ua-auto-config._https.mail1.example.com. 7200 IN    SRV    10 60 443 mail.example.com.

https://mail.example.com/.well-known/user-agent-configuration

5.3. Configuration Validation

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

User agents SHOULD process only the properties that they support and SHOULD 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 retrieving 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 covers 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 could influence the user agent's protocol selection. This probing process also 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, and any such decision is very specific to the implementation at hand.¶

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

"oauth-public" : {
    "issuer" : "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"

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.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.2 at all.¶

7.4. TLS Validation

Whenever TLS is used, clients MUST validate TLS certificates and ensure that certificates are valid for the hostnames specified in the configuration. If certificate validation fails or the TLS certificate is otherwise invalid, the client 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. Clients SHOULD NOT allow users to override TLS certificate validation checks.¶

Clients MAY implement more restrictive TLS policies for configuration retrieval than those typically required for web browsing, in order to provide stronger security guarantees. Clients MAY want to limit the allowed protocol version(s) to recent versions, and MAY similarly want to restrict the allowed cipher suites.¶

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.¶

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