@ -141,9 +141,7 @@ return with a status of 401 and the error code, ``M_MISSING_TOKEN`` or
User-Interactive Authentication API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _sect: auth-api:
Some API endpoints such as `` login `` or `` register `` require authentication that
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
@ -194,7 +192,7 @@ information:
params
This section contains any information that the client will need to know in
order to use a given type of authentication. For each login stage type
order to use a given type of authentication. For each login type
presented, that type may be present as a key in this dictionary. For example,
the public part of an OAuth client ID could be given here.
session
@ -203,12 +201,12 @@ session
API call.
The client then chooses a flow and attempts to complete one of the stages. It
does this by resubmitting the same request with the addition of an 'auth'
does this by resubmitting the same request with the addition of an `` auth ``
key in the object that it submits. This dictionary contains a `` type `` key whose
value is the name of the stage type that the client is attempting to complete.
It must also contains a `` session `` key with the value of the session key given
value is the name of the login type that the client is attempting to complete.
It must also contain a `` session `` key with the value of the session key given
by the homeserver, if one was given. It also contains other keys dependent on
the stage type being attempted. For example, if the client is attempting to
the login type being attempted. For example, if the client is attempting to
complete login type `` example.type.foo `` , it might submit something like this:
.. code :: json
@ -226,7 +224,7 @@ complete login type ``example.type.foo``, it might submit something like this:
If the homeserver deems the authentication attempt to be successful but still
requires more stages to be completed, it returns HTTP status 401 along with the
same object as when no authentication was attempted, with the addition of the
`` completed `` key which is an array of stage type the client has completed
`` completed `` key which is an array of login types the client has completed
successfully:
.. code :: json
@ -272,7 +270,7 @@ clicks on the link in the email. In this case, the client retries the request
with an auth dict containing only the session key. The response to this will be
the same as if the client were attempting to complete an auth state normally,
i.e. 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 type in the 'completed' array indicating whether
that stage is complete.
Example
@ -282,7 +280,7 @@ three stages will resemble the following diagram::
_______________________
| Stage 1 |
| type: "<stage type1>" |
| type: "<login type1>" |
| ___________________ |
| |_Request_1_________| | <-- Returns "session" key which is used throughout.
| ___________________ |
@ -292,7 +290,7 @@ three stages will resemble the following diagram::
|
_________V_____________
| Stage 2 |
| type: "<stage type2>" |
| type: "<login type2>" |
| ___________________ |
| |_Request_1_________| |
| ___________________ |
@ -304,11 +302,15 @@ three stages will resemble the following diagram::
|
_________V_____________
| Stage 3 |
| type: "<stage type3>" |
| type: "<login type3>" |
| ___________________ |
| |_Request_1_________| | <-- Returns API response
|_______________________|
Login types
+++++++++++
This specification defines the following login types:
- `` m.login.password ``
- `` m.login.recaptcha ``
@ -318,7 +320,7 @@ This specification defines the following login types:
- `` m.login.dummy ``
Password-based
++++++++++++++
<<<<<<<<<<<<<<
:Type:
`` m.login.password ``
:Description:
@ -357,7 +359,7 @@ homeserver must respond with 403 Forbidden.
weak passwords with an error code `` M_WEAK_PASSWORD `` .
Google ReCaptcha
++++++++++++++++
<<<<<<<<<<<<<<<<
:Type:
`` m.login.recaptcha ``
:Description:
@ -373,7 +375,7 @@ To respond to this type, reply with an auth dict as follows:
}
Token-based
+++++++++++
<<<<<<<<<<<
:Type:
`` m.login.token ``
:Description:
@ -406,7 +408,7 @@ newly provisioned access_token).
The `` token `` must be a macaroon.
OAuth2-based
++++++++++++
<<<<<<<<<<<<
:Type:
`` m.login.oauth2 ``
:Description:
@ -430,7 +432,7 @@ the OAuth flow has completed, the client retries the request with the session
only, as above.
Email-based (identity server)
+++++++++++++++++++++++++++++
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
:Type:
`` m.login.email.identity ``
:Description:
@ -457,7 +459,7 @@ To respond to this type, reply with an auth dict as follows:
}
Dummy Auth
++++++++++
<<<<<<<<<<
:Type:
`` m.login.dummy ``
:Description:
@ -476,7 +478,7 @@ if provided:
Fallback
++++++++
<<<<<<<<
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 type, it can direct
the user to a web browser with the URL of a fallback page which will allow the
@ -492,16 +494,42 @@ This MUST return an HTML page which can perform this authentication stage. This
page must attempt to call the JavaScript function `` window.onAuthDone `` when
the authentication has been completed.
API calls using the User-Interactive Authentication mechanism
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. _User-Interactive Authentication: `sect:auth-api`_
Login
~~~~~
{{registration_cs_http_api}}
A client can obtain access tokens using the `` /login `` API.
For a simple username/password login, a client should submit an auth dict as
follows:
.. code :: json
{
"type": "m.login.password",
"user": "<user_id or user localpart>",
"password": "<password>"
}
Alternatively, a client can use a 3pid bound to the user's account on the
homeserver using the |/account/3pid|_ API rather then giving the `` user ``
explicitly, as follows:
.. code :: json
{
"type": "m.login.password",
"medium": "<The medium of the third party identifier. Must be 'email'>",
"address": "<The third party address of the user>",
"password": "<password>"
}
In the case that the homeserver does not know about the supplied 3pid, the
homeserver must respond with 403 Forbidden.
{{login_cs_http_api}}
Login Fallback
++++++++++++++
<<<<<<<<<<<<<<
If a client does not recognize any or all login flows it can use the fallback
login API::
@ -512,30 +540,23 @@ This returns an HTML and JavaScript page which can perform the entire login
process. The page will attempt to call the JavaScript function
`` window.onLogin `` when login has been successfully completed.
Changing Password
+++++++++++++++++
Request::
POST /_matrix/client/%CLIENT_MAJOR_VERSION%/account/password
This API endpoint uses the User-Interactive Authentication API. An access token
should be submitted to this endpoint if the client has an active session. The
homeserver may change the flows available depending on whether a valid access
token is provided.
Account registration and management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The body of the POST request is a JSON object containing:
{{registration_cs_http_api}}
new_password
The new password for the account.
Notes on password management
++++++++++++++++++++++++++++
On success, an empty JSON object is returned.
.. WARNING ::
Clients SHOULD enforce that the password provided is suitably complex. The
password SHOULD include a lower-case letter, an upper-case letter, a number
and a symbol and be at a minimum 8 characters in length. Servers MAY reject
weak passwords with an error code `` M_WEAK_PASSWORD `` .
The error code M_NOT_FOUND is returned if the user authenticated with a third
party identifier but the homeserver could not find a matching account in its
database.
Adding Account Administrative Contact Information
+++++++++++++++++++++++++++++++++++++++++++++++++
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A homeserver may keep some contact information for administrative use.
This is independent of any information kept by any Identity Servers.
Richard van der Hoff
10 years ago