|
|
|
@ -431,13 +431,12 @@ User-Interactive Authentication API
|
|
|
|
|
Overview
|
|
|
|
|
<<<<<<<<
|
|
|
|
|
|
|
|
|
|
Some API endpoints require authentication that
|
|
|
|
|
interacts with the user. The homeserver may provide many different ways of
|
|
|
|
|
authenticating, such as user/password auth, login via a social network (OAuth2),
|
|
|
|
|
login by confirming a token sent to their email address, etc. This specification
|
|
|
|
|
does not define how homeservers should authorise their users but instead
|
|
|
|
|
defines the standard interface which implementations should follow so that ANY
|
|
|
|
|
client can login to ANY homeserver.
|
|
|
|
|
Some API endpoints require authentication that interacts with the user. The
|
|
|
|
|
homeserver may provide many different ways of authenticating, such as
|
|
|
|
|
user/password auth, login via a single-sign-on server (SSO), etc. This
|
|
|
|
|
specification does not define how homeservers should authorise their users but
|
|
|
|
|
instead defines the standard interface which implementations should follow so
|
|
|
|
|
that ANY client can login to ANY homeserver.
|
|
|
|
|
|
|
|
|
|
The process takes the form of one or more 'stages'. At each stage the client
|
|
|
|
|
submits a set of data for a given authentication type and awaits a response
|
|
|
|
@ -663,11 +662,9 @@ Authentication types
|
|
|
|
|
This specification defines the following auth types:
|
|
|
|
|
- ``m.login.password``
|
|
|
|
|
- ``m.login.recaptcha``
|
|
|
|
|
- ``m.login.oauth2``
|
|
|
|
|
- ``m.login.sso``
|
|
|
|
|
- ``m.login.email.identity``
|
|
|
|
|
- ``m.login.msisdn``
|
|
|
|
|
- ``m.login.token``
|
|
|
|
|
- ``m.login.dummy``
|
|
|
|
|
|
|
|
|
|
Password-based
|
|
|
|
@ -744,66 +741,6 @@ To use this authentication type, clients should submit an auth dict as follows:
|
|
|
|
|
"session": "<session ID>"
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
Token-based
|
|
|
|
|
<<<<<<<<<<<
|
|
|
|
|
:Type:
|
|
|
|
|
``m.login.token``
|
|
|
|
|
:Description:
|
|
|
|
|
The client submits a login token.
|
|
|
|
|
|
|
|
|
|
To use this authentication type, clients should submit an auth dict as follows:
|
|
|
|
|
|
|
|
|
|
.. code:: json
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"type": "m.login.token",
|
|
|
|
|
"token": "<token>",
|
|
|
|
|
"txn_id": "<client generated nonce>",
|
|
|
|
|
"session": "<session ID>"
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A client may receive a login ``token`` via some external service, such as email
|
|
|
|
|
or SMS. Note that a login token is separate from an access token, the latter
|
|
|
|
|
providing general authentication to various API endpoints.
|
|
|
|
|
|
|
|
|
|
Additionally, the server must encode the user ID in the ``token``; there is
|
|
|
|
|
therefore no need for the client to submit a separate username.
|
|
|
|
|
|
|
|
|
|
The ``txn_id`` should be a random string generated by the client for the
|
|
|
|
|
request. The same ``txn_id`` should be used if retrying the request. The
|
|
|
|
|
``txn_id`` may be used by the server to disallow other devices from using the
|
|
|
|
|
token, thus providing "single use" tokens while still allowing the device to
|
|
|
|
|
retry the request. This would be done by tying the token to the ``txn_id``
|
|
|
|
|
server side, as well as potentially invalidating the token completely once the
|
|
|
|
|
device has successfully logged in (e.g. when we receive a request from the
|
|
|
|
|
newly provisioned access_token).
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
OAuth2-based
|
|
|
|
|
<<<<<<<<<<<<
|
|
|
|
|
:Type:
|
|
|
|
|
``m.login.oauth2``
|
|
|
|
|
:Description:
|
|
|
|
|
Authentication is supported via OAuth2 URLs. This login consists of multiple
|
|
|
|
|
requests.
|
|
|
|
|
:Parameters:
|
|
|
|
|
``uri``: Authorization Request URI OR service selection URI. Both contain an
|
|
|
|
|
encoded ``redirect URI``.
|
|
|
|
|
|
|
|
|
|
The homeserver acts as a 'confidential' client for the purposes of OAuth2. If
|
|
|
|
|
the uri is a ``service selection URI``, it MUST point to a webpage which prompts
|
|
|
|
|
the user to choose which service to authorize with. On selection of a service,
|
|
|
|
|
this MUST link through to an ``Authorization Request URI``. If there is only one
|
|
|
|
|
service which the homeserver accepts when logging in, this indirection can be
|
|
|
|
|
skipped and the "uri" key can be the ``Authorization Request URI``.
|
|
|
|
|
|
|
|
|
|
The client then visits the ``Authorization Request URI``, which then shows the
|
|
|
|
|
OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the ``redirect URI`` with
|
|
|
|
|
the auth code. Homeservers can choose any path for the ``redirect URI``. Once
|
|
|
|
|
the OAuth flow has completed, the client retries the request with the session
|
|
|
|
|
only, as above.
|
|
|
|
|
|
|
|
|
|
Single Sign-On
|
|
|
|
|
<<<<<<<<<<<<<<
|
|
|
|
|
:Type:
|
|
|
|
|