Spec OAuth 2.0 aware clients

As per MSC3824.

Signed-off-by: Kévin Commaille <zecakeh@tedomum.fr>

content/client-server-api/_index.md

@@ -481,6 +481,13 @@ such as automated applications that cannot use a web browser, or
 user management by [application services](application-service-api/#server-admin-style-permissions).
 {{% /boxes/note %}}
 
+{{% boxes/note %}}
+{{% added-in v="1.17" %}}
+A compatibility layer is available to ease the transition from the legacy API to
+the OAuth 2.0 API for clients that only support the legacy API called [OAuth 2.0
+aware clients](#oauth-20-aware-clients).
+{{% /boxes/note %}}
+
 ### Authentication API discovery
 
 To discover if a homeserver supports the legacy API, the [`GET /login`](#get_matrixclientv3login)
@@ -1603,6 +1610,70 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`.
 
 {{% http-api spec="client-server" api="account_deactivation" %}}
 
+#### OAuth 2.0 aware clients
+
+This is a compatibility layer that allows clients that only support the legacy
+API to make some less-invasive changes to improve the user experience when
+talking to a homeserver that is using the OAuth 2.0 API without actually having
+to implement the full OAuth 2.0 API.
+
+##### Client behaviour
+
+For a client to be considered fully OAuth 2.0 aware it MUST:
+
+* Support the [`m.login.sso` authentication flow](#client-login-via-sso).
+* Where a `oauth_aware_preferred` value of `true` is present on an `m.login.sso`
+  flow then *only* offer that auth flow to the user.
+* Append `action=login` and `action=register` parameters to the [SSO redirect
+  endpoints](#get_matrixclientv3loginssoredirect). The client might determine
+  the value to use based on whether the user clicked a "Login" or "Register"
+  button.
+* Check and honour the [`m.3pid_changes` capability](#m3pid_changes-capability)
+  so that the user is not offered the ability to add or remove 3PIDs if the
+  homeserver says the capability is not available.
+* Determine if the homeserver is using the OAuth 2.0 API by using
+  [server metadata discovery](#get_matrixclientv1auth_metadata) from the OAuth
+  2.0 API.
+* If a homeserver is using the OAuth 2.0 API as discovered in the previous step
+  then the client MUST redirect users to manage their account at the [account
+  management URL](#oauth-20-account-management), if available, instead of
+  providing a native UI using the legacy API endpoints.
+  
+  * If the user wishes to deactivate their account then the client MUST refer
+    them to the account management URL.
+  * If the user wishes to sign out a device other than its own then the client
+    MUST deep link the user to the account management URL by adding the
+    `action=org.matrix.device_delete` and `device_id=<device_id>` parameters so
+    that the web UI knows that the user wishes to sign out a device and which
+    one it is.
+
+Optionally, an OAuth 2.0 aware client COULD:
+
+* Label the SSO button as "Continue" rather than "SSO" when
+  `oauth_aware_preferred` is `true`. This is because after redirect the server
+  may then offer a password and/or further upstream IdPs.
+* Pass other [account management URL parameters](#account-management-url-parameters)
+  for context when linking to the account web UI.
+
+##### Server behaviour
+
+For a homeserver to provide support for OAuth 2.0 aware clients it MUST:
+
+* Support the [OAuth 2.0 API](#oauth-20-api).
+* Provide an implementation of the [`m.login.sso` authentication flow](#client-login-via-sso)
+  from the legacy API.
+* If password authentication was previously enabled on the homeserver then
+  provide an implementation of the [`m.login.password` authentication flow](#legacy-login)
+  from the legacy API.
+* Indicate that the `m.login.sso` flow is preferred by setting
+  `oauth_aware_preferred` to `true`.
+* Support a value for the `action` param on the [SSO redirect endpoints](#get_matrixclientv3loginssoredirect).
+
+Additionally, the homeserver SHOULD:
+
+* Advertise the [account management URL](#oauth-20-account-management) in the
+  [server metadata](#get_matrixclientv1auth_metadata).
+
 ### OAuth 2.0 API
 
 {{% added-in v="1.15" %}}

data/api/client-server/definitions/sso_login_flow.yaml

@@ -86,5 +86,12 @@ properties:
             brand usage as intended by the server.
           example: "github"
       required: ['id', 'name']
+  oauth_aware_preferred:
+    type: bool
+    x-addedInMatrixVersion: "1.17"
+    description: |
+      Whether the `m.login.sso` flow is preferred over other flows for
+      [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
+    example: true
 
 required: ['type']

data/api/client-server/sso_login_redirect.yaml

@@ -37,6 +37,23 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.17"
+          description: |-
+            The action that the user wishes to take at the SSO redirect, for
+            [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.
@@ -75,6 +92,23 @@ paths:
           required: true
           schema:
             type: string
+        - in: query
+          name: action
+          x-addedInMatrixVersion: "1.17"
+          description: |-
+            The action that the user wishes to take at the SSO redirect, for
+            [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients).
+
+            The following values are supported:
+              * `login`: the SSO redirect is for the purposes of signing an
+                existing user in.
+              * `register`: the SSO redirect is for the purpose of registering a
+                new user account.
+          schema:
+            type: string
+            enum:
+              - login
+              - register
       responses:
         "302":
           description: A redirect to the SSO interface.