A Rich Authorization Request Framework for Groupware Services using OAuth 2.0

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

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

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

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

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

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

Appendix A. JSON Schema for Authorization Details

This appendix provides non-normative JSON Schema definitions for the authorization_details objects defined in this document.¶

{
  "$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": {
        "send_as_aliases": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "required": [
    "type",
    "actions",
    "datatypes"
  ]
}

{
  "$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",
      "items": {
        "type": "string",
        "enum": [
          "calendar",
          "event",
          "freebusy"
        ]
      }
    },
    "collections": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "type",
    "actions",
    "datatypes"
  ]
}

{
  "$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",
          "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.¶
• 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