tileradotorg/synapse
1
0
Fork 0
forked from MirrorHub/synapse
Code Pull requests Activity

Extended docs about the registration/login flows

Browse source
This commit is contained in:
Paul "LeoNerd" Evans 2014-09-29 18:35:56 +01:00
parent 3ee9a67aa4
commit 2d61dbc774
1 changed files with 29 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

49
docs/specification.rst
View file

@ -376,7 +376,7 @@ their home server. This is achieved via the |initialSync|_ API. This API also
returns an ``end`` token which can be used with the event stream. returns an ``end`` token which can be used with the event stream.
Registration and login Registration and Login
====================== ======================
Clients must register with a home server in order to use Matrix. After Clients must register with a home server in order to use Matrix. After
@ -391,26 +391,28 @@ home servers should authorise their users who want to login to their existing
accounts, but instead defines the standard interface which implementations accounts, but instead defines the standard interface which implementations
should follow so that ANY client can login to ANY home server. Clients login should follow so that ANY client can login to ANY home server. Clients login
using the |login|_ API. Clients register using the |register|_ API. using the |login|_ API. Clients register using the |register|_ API.
Registration follows the same procedure as login, but the path requests are Registration follows the same general procedure as login, but the path requests
sent to are different. are sent to and the details contained in them are different.
The registration/login process breaks down into the following: In both registration and login cases, the process takes the form of one or more
1. Determine the requirements for logging in. stages, where at each stage the client submits a set of data for a given stage
2. Submit the login stage credentials. type and awaits a response from the server, which will either be a final
3. Get credentials or be told the next stage in the login process and repeat success or a request to perform an additional stage. This exchange continues
step 2. until the final success.
As each home server may have different ways of logging in, the client needs to In order to determine up-front what the server's requirements are, the client
know how they should login. All distinct login stages MUST have a corresponding can request from the server a complete description of all of its acceptable
``type``. A ``type`` is a namespaced string which details the mechanism for flows of the registration or login process. It can then inspect the list of
logging in. returned flows looking for one for which it believes it can complete all of the
required stages, and perform it. As each home server may have different ways of
logging in, the client needs to know how they should login. All distinct login
stages MUST have a corresponding ``type``. A ``type`` is a namespaced string
which details the mechanism for logging in.
A client may be able to login via multiple valid login flows, and should choose A client may be able to login via multiple valid login flows, and should choose
a single flow when logging in. A flow is a series of login stages. The home a single flow when logging in. A flow is a series of login stages. The home
server MUST respond with all the valid login flows when requested:: server MUST respond with all the valid login flows when requested by a simple
``GET`` request directly to the ``/login`` or ``/register`` paths::
The client can login via 3 paths: 1a and 1b, 2a and 2b, or 3. The client should
select one of these paths.
{ {
"flows": [ "flows": [
@ -428,8 +430,12 @@ server MUST respond with all the valid login flows when requested::
] ]
} }
After the login is completed, the client's fully-qualified user ID and a new The client can now select which flow it wishes to use, and begin making
access token MUST be returned:: ``POST`` requests to the ``/login`` or ``/register`` paths with JSON body
content containing the name of the stage as the ``type`` key, along with
whatever additional parameters are required for that login or registration type
(see below). After the flow is completed, the client's fully-qualified user
ID and a new access token MUST be returned::
{ {
"user_id": "@user:matrix.org", "user_id": "@user:matrix.org",
@ -440,9 +446,10 @@ The ``user_id`` key is particularly useful if the home server wishes to support
localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as localpart entry of usernames (e.g. "user" rather than "@user:matrix.org"), as
the client may not be able to determine its ``user_id`` in this case. the client may not be able to determine its ``user_id`` in this case.
If a login has multiple requests, the home server may wish to create a session. If the flow has multiple stages to it, the home server may wish to create a
If a home server responds with a 'session' key to a request, clients MUST session to store context between requests. If a home server responds with a
submit it in subsequent requests until the login is completed:: ``session`` key to a request, clients MUST submit it in subsequent requests
until the flow is completed::
{ {
"session": "<session id>" "session": "<session id>"