64 lines
1.8 KiB
ReStructuredText
64 lines
1.8 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@test",
|
||
|
|
"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()
|