MSC4305: Pushed Authorization Requests (PARs) for OAuth authentication

proposals/4305-par.md

@@ -0,0 +1,60 @@
+# MSC4305: Pushed Authorization Requests (PARs) for OAuth authentication
+
+Matrix v1.15 introduced [new authentication APIs] based on OAuth 2.0. Clients can discover the
+authorization server's metadata via [`GET /_matrix/client/v1/auth_metadata`] and then use the
+`authorization_endpoint` to initiate the login process. This requires the client to pass
+authorization request parameters via URL query parameters which has [a number of downsides]
+including the inablity to ensure cryptographic integrity, authenticity and confidentiality as well
+as URL length issues.
+
+[RFC9126] introduces Pushed Authorization Requests (PARs) which let clients push authorization
+request payloads directly to the authorization server in exchange for a request URI to be used in a
+subsequent authorization request. PARs can be used in conjunction with other mechansisms such as
+[RFC9101] to address the security issues mentioned above.
+
+This proposal introduces PARs into the new Matrix authentication APIs.
+
+## Proposal
+
+Two new properties are added to the response of [`GET /_matrix/client/v1/auth_metadata`]:
+
+- `pushed_authorization_request_endpoint` (URI): The authorization server's PAR endpoint as per
+  [RFC9126].
+- `require_pushed_authorization_requests` (boolean): Whether the authorization server accepts
+  authorization requests *exclusively* via PAR. Defaults to `false` if omitted.
+
+Specifics of how PARs integrate into other OAuth APIs can be found in [RFC9126]. In particular, the
+authorization endpoint MUST accept the PAR URI in a `request_uri` query parameter. Furthermore, the
+authorization server MAY enforce the use of PARs on a per-client basis using the
+`require_pushed_authorization_requests` property within the client metadata during dynamic client
+registration.
+
+## Potential issues
+
+None.
+
+## Alternatives
+
+None.
+
+## Security considerations
+
+None beyond the [considerations] in RFC9126.
+
+## Unstable prefix
+
+Until this proposal is accepted into the spec, implementations SHOULD refer to
+`pushed_authorization_request_endpoint` and `require_pushed_authorization_requests` as
+`de.gematik.msc4305.pushed_authorization_request_endpoint` and
+`de.gematik.msc4305.require_pushed_authorization_requests`, respectively.
+
+## Dependencies
+
+None.
+
+  [new authentication APIs]: https://spec.matrix.org/v1.15/client-server-api/#oauth-20-api
+  [`GET /_matrix/client/v1/auth_metadata`]: https://spec.matrix.org/v1.15/client-server-api/#get_matrixclientv1auth_metadata
+  [a number of downsides]: https://datatracker.ietf.org/doc/html/rfc9126#name-introduction
+  [RFC9126]: https://datatracker.ietf.org/doc/html/rfc9126
+  [RFC9101]: https://datatracker.ietf.org/doc/html/rfc9101
+  [considerations]: https://datatracker.ietf.org/doc/html/rfc9126#name-security-considerations