Diff

mod_rest/README.markdown @ 5942:abd1bbe5006e draft default tip

Merge
author Trần H. Trung <xmpp:trần.h.trung@trung.fun>
date Sun, 16 Feb 2025 16:09:03 +0700 (5 days ago)
parent 5932:dcea4b4c415d
line wrap: on
line diff
--- a/mod_rest/README.markdown	Tue Feb 06 18:32:01 2024 +0700
+++ b/mod_rest/README.markdown	Sun Feb 16 16:09:03 2025 +0700
@@ -21,21 +21,55 @@
 
 # Usage
 
+You make a choice: install via VirtualHosts or as a Component. User authentication can
+be used when installed via VirtualHost, and OAuth2 can be used for either.
+
 ## On VirtualHosts
 
+This enables rest on the VirtualHost domain, enabling user authentication to secure
+the endpoint. Make sure that the modules_enabled section is immediately below the
+VirtualHost entry so that it's not under any Component sections. EG:
+
 ```lua
-VirtualHost "example.com"
+VirtualHost "chat.example.com"
 modules_enabled = {"rest"}
 ```
 
 ## As a Component
 
+If you install this as a component, you won't be able to use user authentication above,
+and must use OAuth2 authentication outlined below.
+
 ``` {.lua}
-Component "rest.example.net" "rest"
+Component "chat.example.com" "rest"
 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
 modules_enabled = {"http_oauth2"}
 ```
 
+## User authentication
+
+To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG:
+
+```lua
+admins = { "admin@chat.example.com" }
+```
+
+To set up the admin user account:
+
+```lua
+prosodyctl adduser admin@chat.example.com
+```
+
+and lastly, drop the "@host" from the username in your http queries, EG:
+
+```lua
+curl \
+  https://chat.example.com:5281/rest/version/chat.example.com \
+  -k \
+  --user admin \
+  -H 'Accept: application/json'
+```
+
 ## OAuth2
 
 [mod_http_oauth2] can be used to grant bearer tokens which are accepted
@@ -45,7 +79,7 @@
 ## Sending stanzas
 
 The API endpoint becomes available at the path `/rest`, so the full URL
-will be something like `https://your-prosody.example:5281/rest`.
+will be something like `https://conference.chat.example.com:5281/rest`.
 
 To try it, simply `curl` an XML stanza payload: