Emerald Groupware Project

cdbunch@emeraldgroupware.org

Security OAuth scope mail calendar contacts CalDAV CardDAV JMAP freebusy The OAuth 2.0 authorization framework is widely used to provide clients with delegated access to user data. However, the core specification, The OAuth 2.0 Authorization Framework, leaves the definition of access scopes to individual service providers. This has led to a fragmented ecosystem for common groupware services (Mail, Calendaring, Contacts), where each provider uses proprietary, non-interoperable scope identifiers. Client applications, such as desktop mail clients, are forced to hardcode configurations for a small number of large providers, stifling innovation and harming open ecosystems. This document proposes a standardized set of scope values, using the IETF-controlled URN namespace, to represent granular and aggregate permissions for common mail (IMAP/POP/SMTP/JMAP), calendar (CalDAV), and contact (CardDAV) operations. Adopting these standard scopes would significantly improve interoperability between clients and servers, enabling automatic client configuration and a more seamless user experience.

The OAuth 2.0 Authorization Framework defines the "scope" parameter as a mechanism for limiting an application's access to a user's account. While effective, the lack of standardized scope values for fundamental internet services like email and calendaring has led to a situation where every major provider (Google, Microsoft, etc.) has defined their own proprietary scope URIs. This forces client implementers to create and maintain a hardcoded list of provider-specific configurations, creating a high barrier to entry for new service providers and preventing seamless discovery and configuration for end-users. A user of a new groupware server, for example, cannot expect their favorite desktop client to "just work." This document aims to rectify this by defining a set of common, interoperable scopes for groupware functions. These scopes are intended to be published by Authorization Servers in their metadata documents as defined in , allowing clients to discover them and request appropriate permissions dynamically.

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 when, and only when, they appear in all capitals, as shown here.

This specification proposes the following scope values. They are defined within the urn:ietf:params:oauth:scope namespace, which is the appropriate registry for IETF-defined OAuth parameters.

These scopes are intended to grant access to a user's mailbox via protocols such as IMAP , POP3 , or JMAP , and to send mail via SMTP SUBMIT .

urn:ietf:params:oauth:scope:mail:read

Grants read-only access to the user's email. This includes listing mailboxes, fetching messages and headers, and searching. It MUST NOT grant permission to modify or delete messages.

urn:ietf:params:oauth:scope:mail:send

Grants permission to send email on the user's behalf. This typically applies to SMTP SUBMIT or the JMAP equivalent.

urn:ietf:params:oauth:scope:mail:modify

Grants permission to modify and delete email. This includes actions such as setting flags (e.g., \Seen), moving messages between mailboxes, and expunging messages.

urn:ietf:params:oauth:scope:mail

An aggregate scope. Granting this scope MUST be considered equivalent to granting mail:read, mail:send, and mail:modify simultaneously. Clients needing full access SHOULD request this scope for simplicity.

These scopes are intended to grant access to a user's calendar data, typically via the CalDAV protocol or a JMAP-for-Calendars equivalent.

urn:ietf:params:oauth:scope:calendar:freebusy

Grants read-only access to a user's availability information (free/busy times). This scope MUST NOT grant access to sensitive event details such as summary, description, location, or attendees.

urn:ietf:params:oauth:scope:calendar:read

Grants read-only access to the user's calendars and the full details of all events. This scope implies the permissions of calendar:freebusy.

urn:ietf:params:oauth:scope:calendar:update

Grants permission to create, modify, and delete calendars and events on the user's behalf.

urn:ietf:params:oauth:scope:calendar

An aggregate scope. Granting this scope MUST be considered equivalent to granting calendar:freebusy, calendar:read, and calendar:update simultaneously.

These scopes are intended to grant access to a user's address book data, typically via the CardDAV protocol or a JMAP-for-Contacts equivalent.

urn:ietf:params:oauth:scope:contacts:read

Grants read-only access to the user's address books and contacts.

urn:ietf:params:oauth:scope:contacts:update

Grants permission to create, modify, and delete address books and contacts on the user's behalf.

urn:ietf:params:oauth:scope:contacts

An aggregate scope. Granting this scope MUST be considered equivalent to granting contacts:read and contacts:update simultaneously.

The principle of least privilege SHOULD be followed. A client application SHOULD request the most granular scope necessary for its function. For example, a scheduling assistant application that only needs to find open time slots should only request urn:ietf:params:oauth:scope:calendar:freebusy. Authorization servers MUST validate requested scopes and MUST NOT issue access tokens containing scopes that the user has not explicitly authorized for the client. The interpretation and enforcement of these scopes is the responsibility of the Resource Server (e.g., the IMAP or CalDAV server).

This document requests the registration of eleven new values in the "OAuth Scope Registry" under the "OAuth Parameters" registry.

The following scopes are to be registered.

Name:

urn:ietf:params:oauth:scope:mail:read

Description:

Grants read-only access to a user's email.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:mail:send

Description:

Grants permission to send email on a user's behalf.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:mail:modify

Description:

Grants permission to modify and delete email in a user's mailbox.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:mail

Description:

Aggregate scope for full read, send, and modify access to email.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:calendar:freebusy

Description:

Grants read-only access to a user's availability (free/busy) information.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:calendar:read

Description:

Grants read-only access to full calendar and event details.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:calendar:update

Description:

Grants permission to create, modify, and delete calendar data.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:calendar

Description:

Aggregate scope for full read and update access to calendar data.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:contacts:read

Description:

Grants read-only access to a user's contact data.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:contacts:update

Description:

Grants permission to create, modify, and delete contact data.

Change Controller:

IETF

Reference:

This document.

Name:

urn:ietf:params:oauth:scope:contacts

Description:

Aggregate scope for full read and update access to contact data.

Change Controller:

IETF

Reference:

This document.

Normative References Informative References