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

Clarify n-factor auth and add the diagram back in as an example

Browse source
This commit is contained in:
David Baker 2015-04-24 13:42:02 +01:00
parent e7d334c5cd
commit 3343b7f84d
1 changed files with 47 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

55
specification/10_client_server_api.rst
View file

@ -48,14 +48,15 @@ Authentication works by client and server exchanging dictionaries. This
specification covers how this is done over JSON HTTP POST. specification covers how this is done over JSON HTTP POST.
For each endpoint, a server offers one of more 'flows' that the client can use For each endpoint, a server offers one of more 'flows' that the client can use
to authenticate itself. Each flow comprises one or more 'stages'. When all to authenticate itself. Each flow comprises one or more 'stages'. Flows may have
stages are complete, authentication is complete and the API call succeeds. To more than one stage to implement n-factor auth. When all stages are complete,
establish what flows a server supports for an endpoint, a client sends the authentication is complete and the API call succeeds. To establish what flows a
request with no authentication. A request to an endpoint that uses server supports for an endpoint, a client sends the request with no
User-Interactive Authentication never succeeds without auth. Home Servers may authentication. A request to an endpoint that uses User-Interactive
allow requests that don't require auth by offering a stage with only the Authentication never succeeds without auth. Home Servers may allow requests that
``m.login.dummy`` auth type. The home server returns a response with HTTP status don't require auth by offering a stage with only the ``m.login.dummy`` auth
401 and a JSON object as folows:: type. The home server returns a response with HTTP status 401 and a JSON object
as folows::
{ {
"flows": [ "flows": [
@ -138,6 +139,10 @@ message in the standard format::
"error": "Something was wrong" "error": "Something was wrong"
} }
Individual stages may require more than one request to complete, in which case
the response will be as if the request was unauthenticated with the addition of
any other keys as defined by the login type.
If the client has completed all stages of a flow, the home server performs the If the client has completed all stages of a flow, the home server performs the
API call and returns the result as normal. API call and returns the result as normal.
@ -150,6 +155,40 @@ ie. the request will either complete or request auth, with the presence or
absence of that login stage type in the 'completed' array indicating whether absence of that login stage type in the 'completed' array indicating whether
that stage is complete. that stage is complete.
Example
~~~~~~~
At a high level, the requests made for an API call completing an auth flow with
three stages will resemble the following diagram::
_______________________
| Stage 1 |
| type: "<stage type1>" |
| ___________________ |
| |_Request_1_________| | <-- Returns "session" key which is used throughout.
| ___________________ |
| |_Request_2_________| |
|_______________________|
|
|
_________V_____________
| Stage 2 |
| type: "<stage type2>" |
| ___________________ |
| |_Request_1_________| |
| ___________________ |
| |_Request_2_________| |
| ___________________ |
| |_Request_3_________| |
|_______________________|
|
|
_________V_____________
| Stage 3 |
| type: "<stage type3>" |
| ___________________ |
| |_Request_1_________| | <-- Returns API response
|_______________________|
This specification defines the following login types: This specification defines the following login types:
- ``m.login.password`` - ``m.login.password``
- ``m.login.recaptcha`` - ``m.login.recaptcha``