You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

334 lines
11 KiB

8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
8 years ago
  1. # Building go-neb
  2. Go-neb is built using `gb` (https://getgb.io/). To build go-neb:
  3. ```bash
  4. # Install gb
  5. go get github.com/constabulary/gb/...
  6. # Clone the go-neb repository
  7. git clone https://github.com/matrix-org/go-neb
  8. cd go-neb
  9. # Build go-neb
  10. gb build github.com/matrix-org/go-neb
  11. ```
  12. # Running go-neb
  13. Go-neb uses environment variables to configure its database and bind address.
  14. To run go-neb:
  15. BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db BASE_URL=https://public.facing.endpoint bin/go-neb
  16. Go-neb needs to connect as a matrix user to receive messages. Go-neb can listen
  17. for messages as multiple matrix users. The users are configured using an
  18. HTTP API and the config is stored in the database. Go-neb will automatically
  19. start syncing matrix messages when the user is configured. To create a user:
  20. curl -X POST localhost:4050/admin/configureClient --data-binary '{
  21. "UserID": "@goneb:localhost:8448",
  22. "HomeserverURL": "http://localhost:8008",
  23. "AccessToken": "<access_token>"
  24. }'
  25. {
  26. "OldClient": {},
  27. "NewClient": {
  28. "UserID": "@goneb:localhost:8448",
  29. "HomeserverURL": "http://localhost:8008",
  30. "AccessToken": "<access_token>"
  31. }
  32. }
  33. Services in go-neb listen for messages in particular rooms using a given matrix
  34. user. Services are configured using an HTTP API and the config is stored in the
  35. database. Services use one of the matrix users configured on go-neb to receive
  36. matrix messages. Each service is configured to listen for messages in a set
  37. of rooms. Go-neb will automatically join the service to its rooms when it is
  38. configured. To start an echo service:
  39. curl -X POST localhost:4050/admin/configureService --data-binary '{
  40. "Type": "echo",
  41. "Id": "myserviceid",
  42. "Config": {
  43. "UserID": "@goneb:localhost:8448",
  44. "Rooms": ["!QkdpvTwGlrptdeViJx:localhost:8448"]
  45. }
  46. }'
  47. {
  48. "Type": "echo",
  49. "Id": "myserviceid",
  50. "OldConfig": {},
  51. "NewConfig": {
  52. "UserID": "@goneb:localhost:8448",
  53. "Rooms": ["!QkdpvTwGlrptdeViJx:localhost:8448"]
  54. }
  55. }
  56. To retrieve an existing Service:
  57. curl -X POST localhost:4050/admin/getService --data-binary '{
  58. "Id": "myserviceid"
  59. }'
  60. {
  61. "Type": "echo",
  62. "Id": "myserviceid",
  63. "Config": {
  64. "UserID": "@goneb:localhost:8448",
  65. "Rooms": ["!QkdpvTwGlrptdeViJx:localhost:8448"]
  66. }
  67. }
  68. Go-neb has a heartbeat listener that returns 200 OK so that load balancers can
  69. check that the server is still running.
  70. curl -X GET localhost:4050/test
  71. {}
  72. ## Architecture
  73. ```
  74. HOMESERVER
  75. |
  76. +=============================================================+
  77. | | Go-NEB |
  78. | +---------+ |
  79. | | Clients | |
  80. | +---------+ |
  81. | | |
  82. | +---------+ +------------+ +--------------+ |
  83. | | Service |-------| Auth Realm |------| Auth Session |-+ |
  84. | +---------+ +------------+ +--------------+ | |
  85. | ^ ^ +---------------+ |
  86. | | | |
  87. +=============================================================+
  88. | |
  89. WEBHOOK REDIRECT
  90. REQUEST REQUEST
  91. Clients = A thing which can talk to homeservers and listen for events.
  92. Service = An individual bot, configured by a user.
  93. Auth Realm = A place where a user can authenticate with.
  94. Auth Session = An individual authentication session
  95. ```
  96. Some `AuthRealms` support "Starter Links". These are HTTP URLs which knowledgeable clients should use to *start* the auth process. They are commonly returned as metadata to `!commands`.
  97. These links require the client to prove that they own a given user ID by appending a token
  98. to the Starter Link. This token will be used to verify the client's identity by making an
  99. Open ID request to the user's Homeserver via federation.
  100. ## Starting a Github Service
  101. ### Register a Github realm
  102. This API allows for an optional `StarterLink` value.
  103. ```
  104. curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{
  105. "ID": "mygithubrealm",
  106. "Type": "github",
  107. "Config": {
  108. "ClientSecret": "YOUR_CLIENT_SECRET",
  109. "ClientID": "YOUR_CLIENT_ID",
  110. "StarterLink": "https://example.com/requestGithubOAuthToken"
  111. }
  112. }'
  113. ```
  114. Returns:
  115. ```
  116. {
  117. "ID":"mygithubrealm",
  118. "Type":"github",
  119. "OldConfig":null,
  120. "NewConfig":{
  121. "ClientSecret":"YOUR_CLIENT_SECRET",
  122. "ClientID":"YOUR_CLIENT_ID",
  123. "StarterLink": "https://example.com/requestGithubOAuthToken"
  124. }
  125. }
  126. ```
  127. ### Make a request for Github Auth
  128. ```
  129. curl -X POST localhost:4050/admin/requestAuthSession --data-binary '{
  130. "RealmID": "mygithubrealm",
  131. "UserID": "@your_user_id:localhost",
  132. "Config": {
  133. "RedirectURL": "https://optional-url.com/to/redirect/to/after/auth"
  134. }
  135. }'
  136. ```
  137. Returns:
  138. ```
  139. {
  140. "URL":"https://github.com/login/oauth/authorize?client_id=$ID\u0026client_secret=$SECRET\u0026redirect_uri=$REDIRECT_BASE_URI%2Frealms%2Fredirects%2Fmygithubrealm\u0026state=$RANDOM_STRING"
  141. }
  142. ```
  143. Follow this link and grant access for NEB to act on your behalf.
  144. ### Create a github bot
  145. ```
  146. curl -X POST localhost:4050/admin/configureService --data-binary '{
  147. "Type": "github",
  148. "Id": "mygithubserviceid",
  149. "Config": {
  150. "RealmID": "mygithubrealm",
  151. "BotUserID": "@goneb:localhost",
  152. "ClientUserID": "@example:localhost",
  153. "Rooms": {
  154. "!EmwxeXCVubhskuWvaw:localhost": {
  155. "Repos": {
  156. "owner/repo": {
  157. "Events": ["push","issues"]
  158. }
  159. }
  160. }
  161. }
  162. }
  163. }'
  164. ```
  165. This request will make `BotUserID` join the `Rooms` specified and create webhooks for the `owner/repo` projects given.
  166. ## Starting a JIRA Service
  167. ### Register a JIRA realm
  168. Generate an RSA private key: (JIRA does not support key sizes >2048 bits)
  169. ```bash
  170. openssl genrsa -out privkey.pem 2048
  171. cat privkey.pem
  172. ```
  173. This API allows for an optional `StarterLink` value. Create the realm:
  174. ```
  175. curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{
  176. "ID": "jirarealm",
  177. "Type": "jira",
  178. "Config": {
  179. "JIRAEndpoint": "matrix.org/jira/",
  180. "StarterLink": "https://example.com/requestJIRAOAuthToken",
  181. "ConsumerName": "goneb",
  182. "ConsumerKey": "goneb",
  183. "ConsumerSecret": "random_long_string",
  184. "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTWBDGWygVYzbcONOlqEOTJUN\r\n8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIvbUem3QnDDqghu0gfqXHMlQr5R8ZP\r\norTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69WuefoW5v55b5YZV283v2jROjxHuj\r\ngAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwItkHwhZ\/fG9i4H8\/aOyr3WlaWbVeKX\r\n+m38lmYZvzQFRAk5ab1vzCGz4cyc\r\nTk2qmZpcjHRd1ijcOkgC23KF8lHWF5Zx0tySR+DWL1JeGm8NJxKMRJZuE8MIkJYF\r\nryE7kjspNItk6npkA3\/A4PWwElhddI4JpiuK+29mMNipRcYYy9e0vH\/igejv7ayd\r\nPLCRMQKBgBDSNWlZT0nNd2DXVqTW9p+MG72VKhDgmEwFB1acOw0lpu1XE8R1wmwG\r\nZRl\/xzri3LOW2Gpc77xu6fs3NIkzQw3v1ifYhX3OrVsCIRBbDjPQI3yYjkhGx24s\r\nVhhZ5S\/TkGk3Kw59bDC6KGqAuQAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
  185. }
  186. }'
  187. ```
  188. The following keys will be modified/added:
  189. - `JIRAEndpoint` in canonicalised form.
  190. - `Server` and `Version` keys which are purely informational for the caller.
  191. - `PublicKeyPEM` which the caller needs a human to insert into the JIRA Application Links web form.
  192. Returns:
  193. ```json
  194. {
  195. "ID": "jirarealm",
  196. "Type": "jira",
  197. "OldConfig": null,
  198. "NewConfig": {
  199. "JIRAEndpoint": "https://matrix.org/jira/",
  200. "StarterLink": "https://example.com/requestJIRAOAuthToken",
  201. "Server": "Matrix.org",
  202. "Version": "6.3.5a",
  203. "ConsumerName": "goneb",
  204. "ConsumerKey": "goneb",
  205. "ConsumerSecret": "random_long_string",
  206. "PublicKeyPEM": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA39UhbOvQHEkBP9fGnhU+\neSObTWBDGWygVYzbcONOlqEOTJUN8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIv\nbUem3QnDDqghu0gfqXHMlQr5R8ZPorTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69\nWuefoW5v55b5YZV283v2jROjxHujgAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwIt\nkHwhZ/fG9i4H8/aOyr3WlaWbVeKX+m38lmYZvzQFRd7UPU7DuO6Aiqj7RxrbAvqq\ndPeoAvo6+V0TRPZ8YzKp2yQmDcGH69IbuKJ2BG1Qx8znZAvghKQ6P9Im+M4c7j9i\ndwIDAQAB\n-----END PUBLIC KEY-----\n",
  207. "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTWBDGWygVYzbcONOlqEOTJUN\r\n8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIvbUem3QnDDqghu0gfqXHMlQr5R8ZP\r\norTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69WuefoW5v55b5YZV283v2jROjxHuj\r\ngAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwItkHwhZ/fG9i4H8/aOyr3WlaWbVeKX\r\n+m38lmYZvzQFRd7UPU7DuO6Aiqj7RxrbAvqqdPeoAvo6+V0TRPZ8YzKp2yQmDcGH\r\n69IbuKJ2BG1Qx8znZAvghKQ6P9Im+M4c7j9iMG72VKhDgmEwFB1acOw0lpu1XE8R1wmwG\r\nZRl/xzri3LOW2Gpc77xu6fs3NIkzQw3v1ifYhX3OrVsCIRBbDjPQI3yYjkhGx24s\r\nVhhZ5S/TkGk3Kw59bDC6KGqAuQAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
  208. }
  209. }
  210. ```
  211. The `ConsumerKey`, `ConsumerSecret`, `ConsumerName` and `PublicKeyPEM` must be manually inserted
  212. into the "Application Links" section under JIRA Admin Settings by a JIRA admin on the target
  213. JIRA installation. Once that is complete, users can OAuth on the target JIRA installation.
  214. ### Make a request for JIRA Auth
  215. ```
  216. curl -X POST localhost:4050/admin/requestAuthSession --data-binary '{
  217. "RealmID": "jirarealm",
  218. "UserID": "@example:localhost",
  219. "Config": {
  220. }
  221. }'
  222. ```
  223. Returns:
  224. ```json
  225. {
  226. "URL":"https://jira.somewhere.com/plugins/servlet/oauth/authorize?oauth_token=7yeuierbgweguiegrTbOT"
  227. }
  228. ```
  229. Follow this link and grant access for NEB to act on your behalf.
  230. ### Create a JIRA bot
  231. ```
  232. curl -X POST localhost:4050/admin/configureService --data-binary '{
  233. "Type": "jira",
  234. "Id": "jid",
  235. "Config": {
  236. "BotUserID": "@goneb:localhost",
  237. "ClientUserID": "@example:localhost",
  238. "Rooms": {
  239. "!EmwxeXCVubhskuWvaw:localhost": {
  240. "Realms": {
  241. "jira_realm_id": {
  242. "Projects": {
  243. "BOTS": {
  244. "Expand": true,
  245. "Track": true
  246. }
  247. }
  248. }
  249. }
  250. }
  251. }
  252. }
  253. }'
  254. ```
  255. # Developing on go-neb.
  256. There's a bunch more tools this project uses when developing in order to do
  257. things like linting. Some of them are bundled with go (fmt and vet) but some
  258. are not. You should install the ones which are not:
  259. ```bash
  260. go get github.com/golang/lint/golint
  261. go get github.com/fzipp/gocyclo
  262. ```
  263. You can then install the pre-commit hook:
  264. ```bash
  265. ./hooks/install.sh
  266. ```
  267. ## Viewing the API docs.
  268. ```
  269. # Start a documentation server listening on :6060
  270. GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &
  271. # Open up the documentation for go-neb in a browser.
  272. sensible-browser http://localhost/pkg/github.com/matrix-org/go-neb
  273. ```