diff --git a/changelogs/client_server/newsfragments/2272.feature b/changelogs/client_server/newsfragments/2272.feature new file mode 100644 index 000000000..34b6a493e --- /dev/null +++ b/changelogs/client_server/newsfragments/2272.feature @@ -0,0 +1 @@ +Add OAuth 2.0 aware clients, as per [MSC3824](https://github.com/matrix-org/matrix-spec-proposals/pull/3824). diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2460776f1..5a611587e 100644 --- a/content/client-server-api/_index.md +++ b/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.18" %}} +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) @@ -1513,6 +1520,11 @@ client supports it, the client should redirect the user to the is complete, the client will need to submit a `/login` request matching `m.login.token`. +{{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) +MUST only offer the `m.login.sso` flow to the user when `oauth_aware_preferred` +is set to `true` and MUST add the `action=login` parameter to the SSO redirect +endpoint. + {{% added-in v="1.7" %}} Already-authenticated clients can additionally generate a token for their user ID if supported by the homeserver using [`POST /login/get_token`](/client-server-api/#post_matrixclientv1loginget_token). @@ -1603,6 +1615,72 @@ MAY reject weak passwords with an error code `M_WEAK_PASSWORD`. {{% http-api spec="client-server" api="account_deactivation" %}} +#### OAuth 2.0 aware clients + +{{% added-in v="1.18" %}} + +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=` 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 MAY: + +* 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" %}} diff --git a/data/api/client-server/account_deactivation.yaml b/data/api/client-server/account_deactivation.yaml index 467af659a..2275fdff1 100644 --- a/data/api/client-server/account_deactivation.yaml +++ b/data/api/client-server/account_deactivation.yaml @@ -35,6 +35,14 @@ paths: Unlike other endpoints, this endpoint does not take an `id_access_token` parameter because the homeserver is expected to sign the request to the identity server instead. + + {{% boxes/warning %}} + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available, and MAY use the `action=org.matrix.account_deactivate` + parameter. + {{% /boxes/warning %}} security: - {} - accessTokenQuery: [] diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 0996511eb..714cbcab9 100644 --- a/data/api/client-server/definitions/sso_login_flow.yaml +++ b/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: boolean + x-addedInMatrixVersion: "1.18" + 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'] diff --git a/data/api/client-server/device_management.yaml b/data/api/client-server/device_management.yaml index 1b245e78d..1f66f8565 100644 --- a/data/api/client-server/device_management.yaml +++ b/data/api/client-server/device_management.yaml @@ -142,6 +142,13 @@ paths: Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). {{% /boxes/warning %}} + + {{% boxes/warning %}} + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available, with the `action=org.matrix.device_delete` and `device_id={deviceId}` parameters. + {{% /boxes/warning %}} operationId: deleteDevice security: - accessTokenQuery: [] @@ -199,6 +206,13 @@ paths: Since this endpoint uses User-Interactive Authentication, it cannot be used when the access token was obtained via the [OAuth 2.0 API](/client-server-api/#oauth-20-api). {{% /boxes/warning %}} + + {{% boxes/warning %}} + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server supports the [OAuth 2.0 API](/client-server-api/#oauth-20-api). + Instead they MUST refer the user to the [account management URL](/client-server-api/#oauth-20-account-management), + if available. + {{% /boxes/warning %}} operationId: deleteDevices security: - accessTokenQuery: [] diff --git a/data/api/client-server/registration.yaml b/data/api/client-server/registration.yaml index e7ede5616..0e88870ac 100644 --- a/data/api/client-server/registration.yaml +++ b/data/api/client-server/registration.yaml @@ -60,6 +60,14 @@ paths: Any user ID returned by this API must conform to the grammar given in the [Matrix specification](/appendices/#user-identifiers). + + {{% boxes/warning %}} + {{% added-in v="1.18" %}} [OAuth 2.0 aware clients](/client-server-api/#oauth-20-aware-clients) + MUST NOT use this endpoint when the server offers the [`m.login.sso` + authentication flow](/client-server-api/#client-login-via-sso) with + `oauth_aware_preferred` set to `true`. Instead they MUST add the + `action=register` parameter to the SSO redirect endpoint. + {{% /boxes/warning %}} operationId: register parameters: - in: query diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 9f9d758bc..ec110aa79 100644 --- a/data/api/client-server/sso_login_redirect.yaml +++ b/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.18" + 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.18" + 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.