mirror of
https://github.com/element-hq/synapse
synced 2024-08-21 12:30:21 +00:00
Presumably this is the intention anyways. I've also updated the domain part to be something more along the lines of what people might expect.
63 lines
1.9 KiB
ReStructuredText
63 lines
1.9 KiB
ReStructuredText
Shared-Secret Registration
|
|
==========================
|
|
|
|
This API allows for the creation of users in an administrative and
|
|
non-interactive way. This is generally used for bootstrapping a Synapse
|
|
instance with administrator accounts.
|
|
|
|
To authenticate yourself to the server, you will need both the shared secret
|
|
(``registration_shared_secret`` in the homeserver configuration), and a
|
|
one-time nonce. If the registration shared secret is not configured, this API
|
|
is not enabled.
|
|
|
|
To fetch the nonce, you need to request one from the API::
|
|
|
|
> GET /_matrix/client/r0/admin/register
|
|
|
|
< {"nonce": "thisisanonce"}
|
|
|
|
Once you have the nonce, you can make a ``POST`` to the same URL with a JSON
|
|
body containing the nonce, username, password, whether they are an admin
|
|
(optional, False by default), and a HMAC digest of the content.
|
|
|
|
As an example::
|
|
|
|
> POST /_matrix/client/r0/admin/register
|
|
> {
|
|
"nonce": "thisisanonce",
|
|
"username": "pepper_roni",
|
|
"password": "pizza",
|
|
"admin": true,
|
|
"mac": "mac_digest_here"
|
|
}
|
|
|
|
< {
|
|
"access_token": "token_here",
|
|
"user_id": "@pepper_roni:localhost",
|
|
"home_server": "test",
|
|
"device_id": "device_id_here"
|
|
}
|
|
|
|
The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
|
|
the shared secret and the content being the nonce, user, password, and either
|
|
the string "admin" or "notadmin", each separated by NULs. For an example of
|
|
generation in Python::
|
|
|
|
import hmac, hashlib
|
|
|
|
def generate_mac(nonce, user, password, admin=False):
|
|
|
|
mac = hmac.new(
|
|
key=shared_secret,
|
|
digestmod=hashlib.sha1,
|
|
)
|
|
|
|
mac.update(nonce.encode('utf8'))
|
|
mac.update(b"\x00")
|
|
mac.update(user.encode('utf8'))
|
|
mac.update(b"\x00")
|
|
mac.update(password.encode('utf8'))
|
|
mac.update(b"\x00")
|
|
mac.update(b"admin" if admin else b"notadmin")
|
|
|
|
return mac.hexdigest()
|