prosody-modules: mod_http_roster_admin/README.markdown annotate

annotate mod_http_roster_admin/README.markdown @ 5424:b45d9a81b3da

mod_http_oauth2: Revert role selector, going to try something else Back out f2c7bb3af600 Allowing only a single role to be encoded into the grant takes away the possibility of having multiple roles in the grant, one of which is selected when issuing an access token. It also takes away the ability to have zero roles granted, which could be useful e.g. when you only need OIDC scopes.

author	Kim Alvefur <zash@zash.se>
date	Sun, 07 May 2023 19:40:57 +0200
parents	af1b3cef52e1
children

rev	line source
2311 73967121cf5e Add labels JC Brand <jcbrand@minddistrict.com> parents: 2310 diff changeset	1 ---
73967121cf5e Add labels JC Brand <jcbrand@minddistrict.com> parents: 2310 diff changeset	2 labels:
73967121cf5e Add labels JC Brand <jcbrand@minddistrict.com> parents: 2310 diff changeset	3 - 'Stage-Beta'
73967121cf5e Add labels JC Brand <jcbrand@minddistrict.com> parents: 2310 diff changeset	4 summary: Delegate roster management to an external service
73967121cf5e Add labels JC Brand <jcbrand@minddistrict.com> parents: 2310 diff changeset	5 ...
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	6
2312 234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	7 NOTE: THIS MODULE IS RELEASED UNDER THE MOZILLA PUBLIC LICENSE VERSION 2.
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	8
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	9 Normally the XMPP server will store and maintain the users' contact
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	10 rosters. This module lets you delegate roster management to an external
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	11 service.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	12
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	13 Prosody will make an HTTP request to fetch the roster from the external
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	14 service. The service will need to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	15 changes, so that Prosody can fetch a new roster for that user.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	16
2312 234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	17 ## Configuring this module
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	18
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	19 This module relies on `mod_storage_memory` and `mod_block_subscriptions`.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	20
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	21 In `.parts/prosody/etc/prosody/prosody.cfg.lua`, where your particular
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	22 `VirtualHost` is being configured, add the following:
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	23
3007 af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	24 ``` lua
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	25 modules_enabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	26 "http_roster_admin",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	27 "block_subscriptions",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	28 "storage_memory",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	29 "http_files"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	30 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	31 modules_disabled = {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	32 -- Prosody will get the roster from the backend app,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	33 -- so we disable the default roster module.
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	34 "roster"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	35 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	36 storage = { roster = "memory" }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	37 http_roster_url = "http://localhost/contacts/%s" -- %s will be replaced by an URL-encoded username
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	38 ```
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	39
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	40 The `http_roster_url` parameter needs to be configured to point to the
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	41 URL in the backend application which returns users' contacts rosters.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	42
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	43 In this URL, the pattern `%s` is replaced by an URL-encoded username.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	44
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	45 When the user john then connects to Prosody, and `http_roster_url` is
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	46 set to “http://app.example.org/contacts/%s”, then Prosody will make a
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	47 GET request to http://app.example.org/contacts/john
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	48
3006 e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	49 ## Protocol
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	50
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	51 ### Fetching rosters (Prosody to web app)
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	52
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	53 Prosody considers the web application to always hold the most accurate and up-to-date
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	54 version of the user's roster. When a user first connects, Prosody fetches the roster
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	55 from the web application and caches it internally.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	56
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	57 Prosody will make a GET request to the URL specified in Prosody's configuration parameter
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	58 'http_roster_url'. In this URL, the pattern '%s' is replaced by an URL-encoded username.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	59
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	60 For example, when the user 'john' connects to Prosody, and http_roster_url is set
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	61 to "http://app.example.com/contacts/%s", Prosody will make a GET request to "http://app.example.com/contacts/john".
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	62
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	63 The web app must return a JSON object, where each key is the JID of a contact, and the corresponding
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	64 value is data about that contact.
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	65
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	66 If the user 'john' has friends 'marie' and 'michael', the web app would return a HTTP '200 OK' response
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	67 with the following contents:
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	68
3007 af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	69 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	70 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	71 "marie@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	72 "name": "Marie"
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	73 },
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	74
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	75 "michael@example.com": {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	76 "name": "Michael"
3006 e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	77 }
3007 af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	78 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	79 ```
3006 e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	80
e6f91e00b507 mod_http_roster_admin: Add missing protocol docs Matthew Wild <mwild1@gmail.com> parents: 2312 diff changeset	81 ### Notifying Prosody of roster changes
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	82
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	83 The external service needs to notify Prosody whenever a user's roster
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	84 changes. To do this, it must make an HTTP POST request to either:
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	85
2312 234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	86 - http://localhost:5280/roster_admin/refresh
234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	87 - https://localhost:5281/roster_admin/refresh
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	88
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	89 Make sure that the "http_files" module is enabled in Prosody's configuration,
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	90 for the above URLs to served.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	91
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	92 Ports 5280/5281 can be firewalled and the web server (i.e. Apache or Nginx)
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	93 can be configured to reverse proxy those URLs to for example
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	94 https://example.org/http-bind.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	95
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	96 The contents of the POST should be a JSON encoded array of usernames whose
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	97 rosters have changed.
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	98
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	99 For example, if user ‘john’ became friends with ‘aaron’, both john’s
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	100 contact list and aaron’s contact lists have changed:
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	101
3007 af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	102 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	103 ["john", "aaron"]
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	104 ```
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	105
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	106 When the operation is complete Prosody will reply with a summary of the
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	107 operation - a JSON object containing:
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	108
2312 234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	109 - status: either “ok” (success) or “error” (operation completely failed)
234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	110 - message: A human-readable message (for logging and debugging purposes)
234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	111 - updated: The number of rosters successfully updated
234d679076c4 Proper markdown syntax JC Brand <jcbrand@minddistrict.com> parents: 2311 diff changeset	112 - errors: The number of rosters that failed to update
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	113
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	114 Example:
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	115
3007 af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	116 ``` json
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	117 {
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	118 "status": "ok",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	119 "message": "roster update complete",
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	120 "updated": 2,
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	121 "errors": 0
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	122 }
af1b3cef52e1 mod_http_roster_admin: Add syntax highlighting hints Kim Alvefur <zash@zash.se> parents: 3006 diff changeset	123 ```
2161 95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	124
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	125 Prosody may also return status codes `400` or `500` in case of errors (such
95a9f2d234da Add mod_http_roster_admin JC Brand <jc@opkode.com> parents: diff changeset	126 as a missing/malformed body).

Mercurial > prosody-modules

annotate mod_http_roster_admin/README.markdown @ 5424:b45d9a81b3da