Mercurial > prosody-modules

comparison mod_rest/README.markdown @ 5908:dcea4b4c415d

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Tweaking documentation to clarify that Oauth2 can be used for VirtualHosts and Component installations.
author Ben Smith <bens@effortlessis.com>
date Tue, 14 May 2024 07:31:34 -0700
parents d194d1012fd3
children
comparison
equal deleted inserted replaced
5907:d194d1012fd3 5908:dcea4b4c415d
19 use cases from [mod_http_rest] and [mod_component_http] and other such 19 use cases from [mod_http_rest] and [mod_component_http] and other such
20 modules floating around the Internet. 20 modules floating around the Internet.
21 21
22 # Usage 22 # Usage
23 23
24 You make a choice: install via VirtualHosts or as a Component. 24 You make a choice: install via VirtualHosts or as a Component. User authentication can
25 be used when installed via VirtualHost, and OAuth2 can be used for either.
25 26
26 ## On VirtualHosts 27 ## On VirtualHosts
27 28
28 This enables rest on the VirtualHost domain, enabling user authentication to secure 29 This enables rest on the VirtualHost domain, enabling user authentication to secure
29 the endpoint. Make sure that the modules_enabled section is immediately below the 30 the endpoint. Make sure that the modules_enabled section is immediately below the
32 ```lua 33 ```lua
33 VirtualHost "chat.example.com" 34 VirtualHost "chat.example.com"
34 modules_enabled = {"rest"} 35 modules_enabled = {"rest"}
35 ``` 36 ```
36 37
37 ### User authentication 38 ## As a Component
39
40 If you install this as a component, you won't be able to use user authentication above,
41 and must use OAuth2 authentication outlined below.
42
43 ``` {.lua}
44 Component "chat.example.com" "rest"
45 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
46 modules_enabled = {"http_oauth2"}
47 ```
48
49 ## User authentication
38 50
39 To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG: 51 To enable user authentication, edit the "admins = { }" section in prosody.cfg.lua, EG:
40 52
41 ```lua 53 ```lua
42 admins = { "admin@chat.example.com" } 54 admins = { "admin@chat.example.com" }
56 -k \ 68 -k \
57 --user admin \ 69 --user admin \
58 -H 'Accept: application/json' 70 -H 'Accept: application/json'
59 ``` 71 ```
60 72
61 ## As a Component 73 ## OAuth2
62
63 If you install this as a component, you won't be able to use user authentication above,
64 and must use OAuth2 authentication outlined below.
65
66 ``` {.lua}
67 Component "chat.example.com" "rest"
68 component_secret = "dmVyeSBzZWNyZXQgdG9rZW4K"
69 modules_enabled = {"http_oauth2"}
70 ```
71
72 ### OAuth2
73 74
74 [mod_http_oauth2] can be used to grant bearer tokens which are accepted 75 [mod_http_oauth2] can be used to grant bearer tokens which are accepted
75 by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer 76 by mod_rest. Tokens can be passed to `curl` like `--oauth2-bearer
76 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`. 77 dmVyeSBzZWNyZXQgdG9rZW4K` instead of using `--user`.
77 78