wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Formatting fixes for the authentication section

Browse source
This commit is contained in:
Will 2021-01-24 11:29:41 -08:00
parent fd658f674f
commit ea9fced092
No known key found for this signature in database
GPG key ID: 385872BB265E8BF8
1 changed files with 58 additions and 79 deletions
Download patch file Download diff file Expand all files Collapse all files

137
content/client-server-api/_index.md
View file

@ -402,8 +402,8 @@ what authentication data it requires via the body of an HTTP 401
response, and the client submits that authentication data via the `auth` response, and the client submits that authentication data via the `auth`
request parameter. request parameter.
A client should first make a request with no `auth` parameter[1]. The A client should first make a request with no `auth` parameter.
homeserver returns an HTTP 401 response, with a JSON body, as follows: The homeserver returns an HTTP 401 response, with a JSON body, as follows:
HTTP/1.1 401 Unauthorized HTTP/1.1 401 Unauthorized
Content-Type: application/json Content-Type: application/json
@ -429,15 +429,14 @@ homeserver returns an HTTP 401 response, with a JSON body, as follows:
In addition to the `flows`, this object contains some extra information: In addition to the `flows`, this object contains some extra information:
params * `params`: This section contains any information that the client will
This section contains any information that the client will need to know need to know in order to use a given type of authentication. For each
in order to use a given type of authentication. For each authentication authentication type presented, that type may be present as a key in this
type presented, that type may be present as a key in this dictionary. dictionary. For example, the public part of an OAuth client ID could be
For example, the public part of an OAuth client ID could be given here. given here.
session * `session`: This is a session identifier that the client must pass back
This is a session identifier that the client must pass back to the to the homeserver, if one is provided, in subsequent attempts to authenticate
homeserver, if one is provided, in subsequent attempts to authenticate
in the same API call. in the same API call.
The client then chooses a flow and attempts to complete the first stage. The client then chooses a flow and attempts to complete the first stage.
@ -556,7 +555,14 @@ to complete an auth state normally, i.e. the request will either
complete or request auth, with the presence or absence of that auth type complete or request auth, with the presence or absence of that auth type
in the 'completed' array indicating whether that stage is complete. in the 'completed' array indicating whether that stage is complete.
##### Example {{% boxes/note %}}
A request to an endpoint that uses User-Interactive Authentication never
succeeds without auth. Homeservers may allow requests that don't require
auth by offering a stage with only the `m.login.dummy` auth type, but they
must still give a 401 response to requests with no auth data.
{{% /boxes/note %}}
#### Example
At a high level, the requests made for an API call completing an auth At a high level, the requests made for an API call completing an auth
flow with three stages will resemble the following diagram: flow with three stages will resemble the following diagram:
@ -598,7 +604,7 @@ flow with three stages will resemble the following diagram:
|_______________________| |_______________________|
``` ```
##### Authentication types #### Authentication types
This specification defines the following auth types: This specification defines the following auth types:
- `m.login.password` - `m.login.password`
@ -608,14 +614,12 @@ This specification defines the following auth types:
- `m.login.msisdn` - `m.login.msisdn`
- `m.login.dummy` - `m.login.dummy`
#### Password-based ##### Password-based
Type
`m.login.password`
Description | Type | Description |
The client submits an identifier and secret password, both sent in |--------------------|--------------------------------------------------------------------------------|
plain-text. | `m.login.password` | The client submits an identifier and secret password, both sent in plain-text. |
To use this authentication type, clients should submit an auth dict as To use this authentication type, clients should submit an auth dict as
follows: follows:
@ -669,13 +673,11 @@ explicitly as follows:
In the case that the homeserver does not know about the supplied 3PID, In the case that the homeserver does not know about the supplied 3PID,
the homeserver must respond with 403 Forbidden. the homeserver must respond with 403 Forbidden.
#### Google ReCaptcha ##### Google ReCaptcha
Type | Type | Description |
`m.login.recaptcha` |---------------------|------------------------------------------------------|
| `m.login.recaptcha` | The user completes a Google ReCaptcha 2.0 challenge. |
Description
The user completes a Google ReCaptcha 2.0 challenge
To use this authentication type, clients should submit an auth dict as To use this authentication type, clients should submit an auth dict as
follows: follows:
@ -688,27 +690,21 @@ follows:
} }
``` ```
#### Single Sign-On ##### Single Sign-On
Type | Type | Description |
`m.login.sso` |---------------|--------------------------------------------------------------------------------------|
| `m.login.sso` | Authentication is supported by authorising with an external single sign-on provider. |
Description
Authentication is supported by authorising with an external single
sign-on provider.
A client wanting to complete authentication using SSO should use the A client wanting to complete authentication using SSO should use the
[Fallback](#fallback) mechanism. See [SSO during User-Interactive [Fallback](#fallback) mechanism. See [SSO during User-Interactive
Authentication](#sso-during-user-interactive-authentication) for more information. Authentication](#sso-during-user-interactive-authentication) for more information.
#### Email-based (identity / homeserver) ##### Email-based (identity / homeserver)
Type | Type | Description |
`m.login.email.identity` |--------------------------|------------------------------------------------------------------------------------------------------------------|
| `m.login.email.identity` | Authentication is supported by authorising an email address with an identity server, or homeserver if supported. |
Description
Authentication is supported by authorising an email address with an
identity server, or homeserver if supported.
Prior to submitting this, the client should authenticate with an Prior to submitting this, the client should authenticate with an
identity server (or homeserver). After authenticating, the session identity server (or homeserver). After authenticating, the session
@ -735,14 +731,11 @@ follows:
Note that `id_server` (and therefore `id_access_token`) is optional if Note that `id_server` (and therefore `id_access_token`) is optional if
the `/requestToken` request did not include them. the `/requestToken` request did not include them.
#### Phone number/MSISDN-based (identity / homeserver) ##### Phone number/MSISDN-based (identity / homeserver)
Type | Type | Description |
`m.login.msisdn` |------------------|----------------------------------------------------------------------------------------------------------------|
| `m.login.msisdn` | Authentication is supported by authorising a phone number with an identity server, or homeserver if supported. |
Description
Authentication is supported by authorising a phone number with an
identity server, or homeserver if supported.
Prior to submitting this, the client should authenticate with an Prior to submitting this, the client should authenticate with an
identity server (or homeserver). After authenticating, the session identity server (or homeserver). After authenticating, the session
@ -769,14 +762,13 @@ follows:
Note that `id_server` (and therefore `id_access_token`) is optional if Note that `id_server` (and therefore `id_access_token`) is optional if
the `/requestToken` request did not include them. the `/requestToken` request did not include them.
#### Dummy Auth ##### Dummy Auth
Type | Type | Description |
`m.login.dummy` |------------------|------------------------------------------------------------------------|
| `m.login.dummy` | Dummy authentication always succeeds and requires no extra parameters. |
Description The purpose of dummy authentication is to allow servers to not require any form of
Dummy authentication always succeeds and requires no extra parameters.
Its purpose is to allow servers to not require any form of
User-Interactive Authentication to perform a request. It can also be User-Interactive Authentication to perform a request. It can also be
used to differentiate flows where otherwise one flow would be a subset used to differentiate flows where otherwise one flow would be a subset
of another flow. e.g. if a server offers flows `m.login.recaptcha` and of another flow. e.g. if a server offers flows `m.login.recaptcha` and
@ -796,7 +788,7 @@ just the type and session, if provided:
} }
``` ```
##### Fallback #### Fallback
Clients cannot be expected to be able to know how to process every Clients cannot be expected to be able to know how to process every
single login type. If a client does not know how to handle a given login single login type. If a client does not know how to handle a given login
@ -837,7 +829,7 @@ with just the session ID:
} }
``` ```
#### Example ##### Example
A client webapp might use the following JavaScript to open a popup A client webapp might use the following JavaScript to open a popup
window which will handle unknown login types: window which will handle unknown login types:
@ -893,7 +885,7 @@ function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onCo
} }
``` ```
##### Identifier types #### Identifier types
Some authentication mechanisms use a user identifier object to identify Some authentication mechanisms use a user identifier object to identify
a user. The user identifier object has a `type` field to indicate the a user. The user identifier object has a `type` field to indicate the
@ -906,13 +898,11 @@ This specification defines the following identifier types:
- `m.id.thirdparty` - `m.id.thirdparty`
- `m.id.phone` - `m.id.phone`
#### Matrix User ID ##### Matrix User ID
Type | Type | Description |
`m.id.user` |-------------|--------------------------------------------|
| `m.id.user` | The user is identified by their Matrix ID. |
Description
The user is identified by their Matrix ID.
A client can identify a user using their Matrix ID. This can either be A client can identify a user using their Matrix ID. This can either be
the fully qualified Matrix user ID, or just the localpart of the user the fully qualified Matrix user ID, or just the localpart of the user
@ -925,14 +915,11 @@ ID.
} }
``` ```
#### Third-party ID ##### Third-party ID
Type | Type | Description |
`m.id.thirdparty` |-------------------|---------------------------------------------------------------------------|
| `m.id.thirdparty` | The user is identified by a third-party identifier in canonicalised form. |
Description
The user is identified by a third-party identifier in canonicalised
form.
A client can identify a user using a 3PID associated with the user's A client can identify a user using a 3PID associated with the user's
account on the homeserver, where the 3PID was previously associated account on the homeserver, where the 3PID was previously associated
@ -948,13 +935,11 @@ ID media.
} }
``` ```
#### Phone number ##### Phone number
Type | Type | Description |
`m.id.phone` |--------------|-------------------------------------------|
| `m.id.phone` | The user is identified by a phone number. |
Description
The user is identified by a phone number.
A client can identify a user using a phone number associated with the A client can identify a user using a phone number associated with the
user's account, where the phone number was previously associated using user's account, where the phone number was previously associated using
@ -1958,12 +1943,6 @@ return a standard error response of the form:
The `retry_after_ms` key SHOULD be included to tell the client how long The `retry_after_ms` key SHOULD be included to tell the client how long
they have to wait in milliseconds before they can try again. they have to wait in milliseconds before they can try again.
[1] A request to an endpoint that uses User-Interactive Authentication
never succeeds without auth. Homeservers may allow requests that don't
require auth by offering a stage with only the `m.login.dummy` auth
type, but they must still give a 401 response to requests with no auth
data.
## Modules ## Modules
Modules are parts of the Client-Server API which are not universal to Modules are parts of the Client-Server API which are not universal to