Network Working Group C. Bunch Internet-Draft Emerald Groupware Project Intended status: Experimental 20 July 2025 Expires: 21 January 2026 A Rich Authorization Request Framework for Groupware Services using OAuth 2.0 draft-bunch-groupware-scopes-01 Abstract The OAuth 2.0 authorization framework is widely used to provide clients with delegated access to user data. However, the core specification 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 framework that combines a minimal set of standardized OAuth 2.0 scopes with a detailed structure for use with OAuth 2.0 Rich Authorization Requests (RAR). This hybrid approach provides a simple baseline for legacy clients while enabling powerful, granular, and privacy-preserving authorization for modern clients. It defines RAR type values, actions, datatypes, and custom fields for specifying fine-grained permissions for groupware resources. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 21 January 2026. Bunch Expires 21 January 2026 [Page 1] Internet-Draft OAuth Groupware Auth July 2025 Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Requirements Language . . . . . . . . . . . . . . . . . . 3 2. Groupware Scopes . . . . . . . . . . . . . . . . . . . . . . 3 3. Rich Authorization Request Types for Groupware . . . . . . . 4 3.1. Custom Authorization Details Fields . . . . . . . . . . . 4 3.2. The 'mail' Authorization Type . . . . . . . . . . . . . . 4 3.3. The 'calendar' Authorization Type . . . . . . . . . . . . 5 3.4. The 'contacts' Authorization Type . . . . . . . . . . . . 5 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 5.1. OAuth Scope Registry . . . . . . . . . . . . . . . . . . 6 5.1.1. urn:ietf:params:oauth:scope:mail . . . . . . . . . . 6 5.1.2. urn:ietf:params:oauth:scope:calendar . . . . . . . . 6 5.1.3. urn:ietf:params:oauth:scope:contacts . . . . . . . . 7 5.2. OAuth Authorization Details Types Registry . . . . . . . 7 5.2.1. urn:ietf:params:oauth:auth-type:mail . . . . . . . . 7 5.2.2. urn:ietf:params:oauth:auth-type:calendar . . . . . . 7 5.2.3. urn:ietf:params:oauth:auth-type:contacts . . . . . . 8 6. Normative References . . . . . . . . . . . . . . . . . . . . 8 Appendix A. JSON Schema for Authorization Details . . . . . . . 8 A.1. Mail Authorization Details Schema . . . . . . . . . . . . 8 A.2. Calendar Authorization Details Schema . . . . . . . . . . 10 A.3. Contacts Authorization Details Schema . . . . . . . . . . 11 Appendix B. Changes from Version -00 . . . . . . . . . . . . . . 12 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 13 Bunch Expires 21 January 2026 [Page 2] Internet-Draft OAuth Groupware Auth July 2025 1. Introduction While OAuth 2.0 [RFC6749] is ubiquitous, its reliance on provider- defined scopes has created a fragmented ecosystem for groupware. A client application cannot automatically configure itself for a new mail or calendar provider, as it has no standard way to request specific permissions like "read-only access to the 'Work' calendar." This document specifies a solution that leverages the recent OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] standard to define structured, granular permissions. To maintain backward compatibility and provide a simple path for basic clients, this detailed RAR structure is paired with a minimal set of three high-level scopes. This allows a client to request simple access (e.g., scope=mail) or to make a much more specific request, such as asking for permission to read and delete messages only from the "INBOX" folder and send email as a specific alias. This improves both security and user privacy by adhering to the principle of least privilege. 1.1. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 2. Groupware Scopes This specification proposes three aggregate scope values to represent high-level access to a user's groupware data. These scopes are intended as a baseline for simple clients or as a companion to more detailed Rich Authorization Requests. urn:ietf:params:oauth:scope:mail Requests access to the user's email. The specific level of access SHOULD be further specified using a Rich Authorization Request of type urn:ietf:params:oauth:auth-type:mail. If RAR is not used, this scope implies full access. urn:ietf:params:oauth:scope:calendar Requests access to the user's calendar data. Granular permissions SHOULD be requested via a Rich Authorization Request of type urn:ietf:params:oauth:auth-type:calendar. Bunch Expires 21 January 2026 [Page 3] Internet-Draft OAuth Groupware Auth July 2025 urn:ietf:params:oauth:scope:contacts Requests access to the user's contact data. Granular permissions SHOULD be requested via a Rich Authorization Request of type urn:ietf:params:oauth:auth-type:contacts. 3. Rich Authorization Request Types for Groupware This document defines a set of type values and associated fields for use within the authorization_details array of an OAuth 2.0 Rich Authorization Request. 3.1. Custom Authorization Details Fields This specification defines the following new fields for use within the authorization_details object to provide granular control over groupware resources. collections (array of strings): This field specifies the names or unique identifiers of the collections (e.g., mail folders, calendars) to which the request is scoped. The special value "*" indicates all collections of the specified datatypes. To solve the initial client bootstrapping problem, the special string value "__default" (two underscores) may be used. If provided, the Authorization Server SHOULD grant access to the user's primary or default collection for the given type (e.g., the INBOX for mail, the default calendar for CalDAV). If this field is omitted entirely, access SHOULD be treated as if no collections were granted. To prevent ambiguity, Resource Servers SHOULD NOT allow users to create collections with names that begin with two underscores. type_specific_details (object): This object contains parameters that are unique to a specific authorization type and do not fit into the other standard fields. 3.2. The 'mail' Authorization Type This type is used to request granular access to a user's email. type: urn:ietf:params:oauth:auth-type:mail Associated Scope: urn:ietf:params:oauth:scope:mail Defined datatypes: folder, message, flag Bunch Expires 21 January 2026 [Page 4] Internet-Draft OAuth Groupware Auth July 2025 Defined actions: list, create, read, update, delete Contents of type_specific_details: send_as_aliases (array of strings): Specifies the email addresses the client is permitted to use in the From: header when performing a send action. The value "*" indicates any of the user's available sending addresses. 3.3. The 'calendar' Authorization Type This type is used to request granular access to a user's calendars. type: urn:ietf:params:oauth:auth-type:calendar Associated Scope: urn:ietf:params:oauth:scope:calendar Defined datatypes: calendar, event, freebusy Defined actions: list, create, read, update, delete 3.4. The 'contacts' Authorization Type This type is used to request granular access to a user's address books. type: urn:ietf:params:oauth:auth-type:contacts Associated Scope: urn:ietf:params:oauth:scope:contacts Defined datatypes: addressbook, contact Defined actions: list, create, read, update, delete Bunch Expires 21 January 2026 [Page 5] Internet-Draft OAuth Groupware Auth July 2025 4. Security Considerations The principle of least privilege SHOULD be followed. A client application SHOULD use Rich Authorization Requests to request the narrowest set of permissions required for their functionality. For example, a scheduling assistant application that only needs to find open time slots should request only the freebusy datatype and the list and read actions for the calendar type, limited to specific calendars if possible. Authorization servers MUST ensure that a user has explicitly consented to the scopes and rich authorization details requested by a client. Resource Servers are responsible for parsing the access token and correctly enforcing the authorized permissions. 5. IANA Considerations This document requests the registration of new values in several IANA-managed registries. 5.1. OAuth Scope Registry This document requests registration of the following three values in the "OAuth Scope Registry". 5.1.1. urn:ietf:params:oauth:scope:mail Name: urn:ietf:params:oauth:scope:mail Description: Requests access to a user's email. Change Controller: IETF Reference: This document. 5.1.2. urn:ietf:params:oauth:scope:calendar Name: urn:ietf:params:oauth:scope:calendar Description: Requests access to a user's calendar data. Bunch Expires 21 January 2026 [Page 6] Internet-Draft OAuth Groupware Auth July 2025 Change Controller: IETF Reference: This document. 5.1.3. urn:ietf:params:oauth:scope:contacts Name: urn:ietf:params:oauth:scope:contacts Description: Requests access to a user's contact data. Change Controller: IETF Reference: This document. 5.2. OAuth Authorization Details Types Registry This document requests registration of the following three values in the "OAuth Authorization Details Types Registry". 5.2.1. urn:ietf:params:oauth:auth-type:mail Name: urn:ietf:params:oauth:auth-type:mail Description: Authorization details for accessing email resources. Change Controller: IETF Reference: This document. 5.2.2. urn:ietf:params:oauth:auth-type:calendar Name: urn:ietf:params:oauth:auth-type:calendar Description: Authorization details for accessing calendar resources. Bunch Expires 21 January 2026 [Page 7] Internet-Draft OAuth Groupware Auth July 2025 Change Controller: IETF Reference: This document. 5.2.3. urn:ietf:params:oauth:auth-type:contacts Name: urn:ietf:params:oauth:auth-type:contacts Description: Authorization details for accessing contact resources. Change Controller: IETF Reference: This document. 6. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, May 2023, . Appendix A. JSON Schema for Authorization Details This appendix provides non-normative JSON Schema definitions for the authorization_details objects defined in this document. A.1. Mail Authorization Details Schema Bunch Expires 21 January 2026 [Page 8] Internet-Draft OAuth Groupware Auth July 2025 { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Mail Authorization Details", "type": "object", "properties": { "type": { "const": "urn:ietf:params:oauth:auth-type:mail" }, "locations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "list", "create", "read", "update", "delete" ] } }, "datatypes": { "type": "array", "items": { "type": "string", "enum": [ "folder", "message", "flag" ] } }, "collections": { "type": "array", "items": { "type": "string" } }, "type_specific_details": { "type": "object", "properties": { Bunch Expires 21 January 2026 [Page 9] Internet-Draft OAuth Groupware Auth July 2025 "send_as_aliases": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "type", "actions", "datatypes" ] } A.2. Calendar Authorization Details Schema { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Calendar Authorization Details", "type": "object", "properties": { "type": { "const": "urn:ietf:params:oauth:auth-type:calendar" }, "locations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "list", "create", "read", "update", "delete" ] } }, "datatypes": { "type": "array", Bunch Expires 21 January 2026 [Page 10] Internet-Draft OAuth Groupware Auth July 2025 "items": { "type": "string", "enum": [ "calendar", "event", "freebusy" ] } }, "collections": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "actions", "datatypes" ] } A.3. Contacts Authorization Details Schema { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Contacts Authorization Details", "type": "object", "properties": { "type": { "const": "urn:ietf:params:oauth:auth-type:contacts" }, "locations": { "type": "array", "items": { "type": "string", "format": "uri" } }, "actions": { "type": "array", "items": { "type": "string", "enum": [ "list", "create", "read", Bunch Expires 21 January 2026 [Page 11] Internet-Draft OAuth Groupware Auth July 2025 "update", "delete" ] } }, "datatypes": { "type": "array", "items": { "type": "string", "enum": [ "addressbook", "contact" ] } }, "collections": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "actions", "datatypes" ] } Appendix B. Changes from Version -00 This version represents a significant revision based on initial community feedback. The core focus has shifted from defining a large set of granular scopes to a more flexible and modern framework that combines a minimal set of aggregate scopes with the structured data model of OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396]. Major changes include: * The document title has been updated to reflect the new focus on Rich Authorization Requests. * The number of proposed scopes has been reduced to three primary aggregate scopes (mail, calendar, contacts) to provide a simple baseline for all clients. Bunch Expires 21 January 2026 [Page 12] Internet-Draft OAuth Groupware Auth July 2025 * A new major section has been added defining RAR type values, actions, datatypes, and custom fields (collections, type_specific_details) that allow for fine-grained permission requests. * The specification is now more closely aligned with the structure and intent of RFC 9396, including the use of URIs in the locations field. * An appendix has been added with non-normative JSON Schema definitions for the proposed authorization_details objects. Author's Address Clinton Bunch Emerald Groupware Project Email: cdbunch@emeraldgroupware.org Bunch Expires 21 January 2026 [Page 13]