diff --git a/content/client-server-api/_index.md b/content/client-server-api/_index.md index 2460776f..58f23d9d 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.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=` 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" %}} diff --git a/data/api/client-server/definitions/sso_login_flow.yaml b/data/api/client-server/definitions/sso_login_flow.yaml index 0996511e..2f395c3a 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: 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'] diff --git a/data/api/client-server/sso_login_redirect.yaml b/data/api/client-server/sso_login_redirect.yaml index 9f9d758b..c9ab99b9 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.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.