convert IS endpoints to Swagger (#1427)
This commit is contained in:
Hubert Chathi
GitHub
parent
292d334509
commit
cd4fed509c
5 changed files with 587 additions and 134 deletions
|
|
@ -114,100 +114,15 @@ session, within a 24 hour period since its most recent modification. Any
|
|||
attempts to perform these actions after the expiry will be rejected, and a new
|
||||
session should be created and used instead.
|
||||
|
||||
Creating a session
|
||||
Email associations
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A client makes a call to::
|
||||
{{email_associations_is_http_api}}
|
||||
|
||||
POST https://my.id.server:8090/_matrix/identity/api/v1/validate/email/requestToken
|
||||
General
|
||||
~~~~~~~
|
||||
|
||||
client_secret=monkeys_are_GREAT&
|
||||
email=foo@bar.com&
|
||||
send_attempt=1
|
||||
|
||||
It may also optionally specify next_link. If next_link is specified, when the
|
||||
validation is completed, the identity service will redirect the user to that
|
||||
URL.
|
||||
|
||||
This will create a new "session" on the identity service, identified by an
|
||||
``sid``.
|
||||
|
||||
The identity service will send an email containing a token. If that token is
|
||||
presented to the identity service in the future, it indicates that that user was
|
||||
able to read the email for that email address, and so we validate ownership of
|
||||
the email address.
|
||||
|
||||
We return the ``sid`` generated for this session to the caller, in a JSON object
|
||||
containing the ``sid`` key.
|
||||
|
||||
If a send_attempt is specified, the server will only send an email if the
|
||||
send_attempt is a number greater than the most recent one which it has seen (or
|
||||
if it has never seen one), scoped to that email address + client_secret pair.
|
||||
This is to avoid repeatedly sending the same email in the case of request
|
||||
retries between the POSTing user and the identity service. The client should
|
||||
increment this value if they desire a new email (e.g. a reminder) to be sent.
|
||||
|
||||
Note that Home Servers offer APIs that proxy this API, adding additional
|
||||
behaviour on top, for example, ``/register/email/requestToken`` is designed
|
||||
specifically for use when registering an account and therefore will inform
|
||||
the user if the email address given is already registered on the server.
|
||||
|
||||
Validating ownership of an email
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A user may make either a ``GET`` or a ``POST`` request to
|
||||
``/_matrix/identity/api/v1/validate/email/submitToken`` with the following
|
||||
parameters (either as query parameters or URL-encoded POST parameters):
|
||||
- ``sid`` the sid for the session, generated by the ``requestToken`` call.
|
||||
- ``client_secret`` the client secret which was supplied to the ``requestToken`` call.
|
||||
- ``token`` the token generated by the ``requestToken`` call, and emailed to the user.
|
||||
|
||||
If these three values are consistent with a set generated by a ``requestToken``
|
||||
call, ownership of the email address is considered to have been validated. This
|
||||
does not publish any information publicly, or associate the email address with
|
||||
any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding.
|
||||
|
||||
Otherwise, an error will be returned.
|
||||
|
||||
Checking non-published 3pid ownership
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
A client can check whether ownership of a 3pid was validated by making an
|
||||
HTTP GET request to ``/_matrix/identity/api/v1/3pid/getValidated3pid``, passing
|
||||
the ``sid`` and ``client_secret`` as query parameters from the ``requestToken``
|
||||
call.
|
||||
|
||||
It will return something of either the form::
|
||||
|
||||
{"medium": "email", "validated_at": 1457622739026, "address": "foo@bar.com"}
|
||||
|
||||
or::
|
||||
|
||||
{"errcode": "M_SESSION_NOT_VALIDATED", "error": "This validation session has not yet been completed"}
|
||||
|
||||
If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
|
||||
an error will be returned.
|
||||
|
||||
Publishing a validated association
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An association between a session and a Matrix user ID can be published by making
|
||||
a URL-encoded HTTP POST request to ``/_matrix/identity/api/v1/3pid/bind`` with
|
||||
the following parameters::
|
||||
|
||||
sid=sid&
|
||||
client_secret=monkeys_are_GREAT&
|
||||
mxid=@foo:bar.com
|
||||
|
||||
If the session is still valid, this will publish an association between the
|
||||
3pids validated on that session and the passed Matrix user ID. Future calls
|
||||
to ``/lookup`` for any of the session's 3pids will return this association.
|
||||
|
||||
If the 3pid has not yet been validated, the HTTP request will be rejected, and
|
||||
the association will not be established.
|
||||
|
||||
If the ``sid`` and ``client_secret`` were not recognised, or were not correct,
|
||||
an error will be returned.
|
||||
{{associations_is_http_api}}
|
||||
|
||||
Invitation Storage
|
||||
------------------
|
||||
|
|
@ -216,32 +131,6 @@ An identity service can store pending invitations to a user's 3pid, which will
|
|||
be retrieved and can be either notified on or look up when the 3pid is
|
||||
associated with a Matrix user ID.
|
||||
|
||||
If one makes a ``POST`` request to ``/_matrix/identity/api/v1/store-invite`` with the following URL-encoded POST parameters:
|
||||
|
||||
- ``medium`` (string, required): The literal string ``email``.
|
||||
- ``address`` (string, required): The email address of the invited user.
|
||||
- ``room_id`` (string, required): The Matrix room ID to which the user is invited.
|
||||
- ``sender`` (string, required): The matrix user ID of the inviting user.
|
||||
|
||||
An arbitrary number of other parameters may also be specified. These may be used in the email generation described below.
|
||||
|
||||
The service will look up whether the 3pid is bound to a Matrix user ID. If it is, the request will be rejected with a 400 status code.
|
||||
|
||||
If the medium is something other than the literal string ``email``, the request will be rejected with a 400 status code.
|
||||
|
||||
Otherwise, the service will then generate a random string called ``token``, and an ephemeral public key.
|
||||
|
||||
The service also generates a ``display_name`` for the inviter, which is a redacted version of ``address`` which does not leak the full contents of the ``address``.
|
||||
|
||||
The service records persistently all of the above information.
|
||||
|
||||
It also generates an email containing all of this data, sent to the ``address`` parameter, notifying them of the invitation.
|
||||
|
||||
The response body is then populated as the JSON-encoded dictionary containing the following fields:
|
||||
- ``token`` (string): The generated token.
|
||||
- ``public_keys`` ([string]): A list of [server's long-term public key, generated ephemeral public key].
|
||||
- ``display_name`` (string): The generated (redacted) display_name.
|
||||
|
||||
At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
|
||||
|
||||
POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
|
||||
|
|
@ -273,7 +162,7 @@ At a later point, if the owner of that particular 3pid binds it with a Matrix us
|
|||
|
||||
Where the signature is produced using a long-term private key.
|
||||
|
||||
Also, the generated ephemeral public key will be listed as valid on requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``.
|
||||
{{store_invite_is_http_api}}
|
||||
|
||||
Ephemeral invitation signing
|
||||
----------------------------
|
||||
|
|
@ -281,23 +170,7 @@ Ephemeral invitation signing
|
|||
To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
|
||||
This is less secure than the client doing it itself, but may be useful where this isn't possible.
|
||||
|
||||
The identity service will happily sign invitation details with a request-specified ed25519 private key for you, if you want it to. It takes URL-encoded POST parameters:
|
||||
- mxid (string, required)
|
||||
- token (string, required)
|
||||
- private_key (string, required): The private key, encoded as `Unpadded base64`_.
|
||||
|
||||
It will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. It will then respond with JSON which looks something like::
|
||||
|
||||
{
|
||||
"mxid": "@foo:bar.com",
|
||||
"sender": "@baz:bar.com",
|
||||
"signatures" {
|
||||
"my.id.server": {
|
||||
"ed25519:0": "def987"
|
||||
}
|
||||
},
|
||||
"token": "abc123"
|
||||
}
|
||||
{{invitation_signing_is_http_api}}
|
||||
|
||||
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
|
||||
.. _`3PID Types`: ../appendices.html#pid-types
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue