register_api.rst 2.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566
  1. Shared-Secret Registration
  2. ==========================
  3. This API allows for the creation of users in an administrative and
  4. non-interactive way. This is generally used for bootstrapping a Synapse
  5. instance with administrator accounts.
  6. To authenticate yourself to the server, you will need both the shared secret
  7. (``registration_shared_secret`` in the homeserver configuration), and a
  8. one-time nonce. If the registration shared secret is not configured, this API
  9. is not enabled.
  10. To fetch the nonce, you need to request one from the API::
  11. > GET /_synapse/admin/v1/register
  12. < {"nonce": "thisisanonce"}
  13. Once you have the nonce, you can make a ``POST`` to the same URL with a JSON
  14. body containing the nonce, username, password, whether they are an admin
  15. (optional, False by default), and a HMAC digest of the content.
  16. As an example::
  17. > POST /_synapse/admin/v1/register
  18. > {
  19. "nonce": "thisisanonce",
  20. "username": "pepper_roni",
  21. "password": "pizza",
  22. "admin": true,
  23. "mac": "mac_digest_here"
  24. }
  25. < {
  26. "access_token": "token_here",
  27. "user_id": "@pepper_roni:localhost",
  28. "home_server": "test",
  29. "device_id": "device_id_here"
  30. }
  31. The MAC is the hex digest output of the HMAC-SHA1 algorithm, with the key being
  32. the shared secret and the content being the nonce, user, password, either the
  33. string "admin" or "notadmin", and optionally the user_type
  34. each separated by NULs. For an example of generation in Python::
  35. import hmac, hashlib
  36. def generate_mac(nonce, user, password, admin=False, user_type=None):
  37. mac = hmac.new(
  38. key=shared_secret,
  39. digestmod=hashlib.sha1,
  40. )
  41. mac.update(nonce.encode('utf8'))
  42. mac.update(b"\x00")
  43. mac.update(user.encode('utf8'))
  44. mac.update(b"\x00")
  45. mac.update(password.encode('utf8'))
  46. mac.update(b"\x00")
  47. mac.update(b"admin" if admin else b"notadmin")
  48. if user_type:
  49. mac.update(b"\x00")
  50. mac.update(user_type.encode('utf8'))
  51. return mac.hexdigest()