README.rst 3.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100
  1. Installation
  2. ============
  3. Dependencies can be installed using setup.py in the same way as synapse: see synapse/README.rst. For instance::
  4. sudo apt-get install build-essential python2.7-dev libffi-dev \
  5. sqlite3 libssl-dev python-virtualenv libxslt1-dev
  6. virtualenv -p python2.7 ~/.sydent
  7. source ~/.sydent/bin/activate
  8. pip install --upgrade pip
  9. pip install --upgrade setuptools
  10. pip install https://github.com/matrix-org/sydent/tarball/master
  11. Having installed dependencies, you can run sydent using::
  12. python -m sydent.sydent
  13. This will create a configuration file in sydent.conf with some defaults. You'll most likely want to change the server name and specify a mail relay.
  14. Defaults for SMS originators will not be added to the generated config file, these should be added in the form::
  15. originators.<country code> = <long|short|alpha>:<originator>
  16. Where country code is the numeric country code, or 'default' to specify the originator used for countries not listed. For example, to use a selection of long codes for the US/Canda, a short code for the UK and an alphanumertic originator for everywhere else::
  17. originators.1 = long:12125552368,long:12125552369
  18. originators.44 = short:12345
  19. originators.default = alpha:Matrix
  20. Testing
  21. =======
  22. Sydent uses matrix-is-tester (https://github.com/matrix-org/matrix-is-tester/) to provide black-box testing of its API.
  23. This can be run as follows:
  24. pip install git+https://github.com/matrix-org/matrix-is-tester.git
  25. trial matrix_is_tester
  26. The SYDENT_PYTHON enviroment variable can be set to launch sydent with a specific python binary:
  27. SYDENT_PYTHON=/path/to/python trial matrix_is_tester
  28. The matrix_is_test directory contains sydent's launcher for matrix_is_tester: this needs to be on the
  29. python path.
  30. Requests
  31. ========
  32. The requests that synapse servers and clients submit to the identity server are, briefly, as follows:
  33. Request the validation of your email address::
  34. curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/validate/email/requestToken' -H "Content-Type: application/json" -d '{"email": "matthew@arasphere.net", "client_secret": "abcd", "send_attempt": 1}'
  35. {"success": true, "sid": "1"}
  36. (Receive 943258 by mail)
  37. Use this code to validate your email address::
  38. curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/validate/email/submitToken' -H "Content-Type: application/json" -d '{"token": "943258", "sid": "1", "client_secret": "abcd"}'
  39. {"success": true}
  40. Use the validated email address to bind it to a matrix ID::
  41. curl -XPOST 'http://localhost:8090/_matrix/identity/api/v1/3pid/bind' -H "Content-Type: application/json" -d '{"sid": "1", "client_secret": "abcd", "mxid": "%40matthew%3amatrix.org"}'
  42. Lookup::
  43. curl 'http://localhost:8090/_matrix/identity/api/v1/lookup?medium=email&address=henry%40matrix.org'
  44. Fetch pubkey key for a server::
  45. curl http://localhost:8090/_matrix/identity/api/v1/pubkey/ed25519:0
  46. Internal bind api
  47. -----------------
  48. It is possible to enable an internal API which allows identifiers to be bound
  49. to matrix IDs without any validation. This is open to abuse, so is disabled by
  50. default, and when it is enabled, is available only on a separate socket which
  51. is bound to 'localhost' by default.
  52. To enable it, configure the port in the config file. For example::
  53. [http]
  54. internalapi.http.port = 8091
  55. To use it::
  56. curl -XPOST 'http://localhost:8091/_matrix/identity/internal/bind' -H "Content-Type: application/json" -d '{"address": "matthew@arasphere.net", "medium": "email", "mxid": "@matthew:matrix.org"}'
  57. The response has the same format as ``/_matrix/identity/api/v1/3pid/bind``.
  58. Replication
  59. ===========
  60. It is possible to configure a mesh of sydents which replicate identity bindings
  61. between each other. See `<docs/replication.md>`_.