Mercurial > prosody-modules

comparison mod_client_management/README.md @ 5650:0eb2d5ea2428

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
merge
author Stephen Paul Weber <singpolyma@singpolyma.net>
date Sat, 06 May 2023 19:40:23 -0500
parents 7c123d3285de
children e9af6abf2b1e
comparison
equal deleted inserted replaced
5649:2c69577b28c2 5650:0eb2d5ea2428
1 ---
2 labels:
3 - Stage-Beta
4 summary: "Manage clients with access to your account"
5 rockspec:
6 dependencies:
7 - mod_sasl2_fast
8 ---
9
10 This module allows a user to identify what currently has access to their
11 account.
12
13 This module depends on [mod_sasl2_fast] and mod_tokenauth (bundled with
14 Prosody). Both will be automatically loaded if this module is loaded.
15
16 ## Configuration
17
18 | Name | Description | Default |
19 |---------------------------|--------------------------------------------------------|-----------------|
20 | enforce_client_ids | Only allow SASL2-compatible clients | `false` |
21
22 When `enforce_client_ids` is not enabled, the client listing may be less accurate due to legacy clients,
23 which can only be tracked by their resource, which is public information, not necessarily unique to a
24 client instance, and is also exposed to other XMPP entities the user communicates with.
25
26 When `enforce_client_ids` is enabled, clients that don't support SASL2 and provide a client id will be
27 denied access.
28
29 ## Shell usage
30
31 You can use this module via the Prosody shell. For example, to list a user's
32 clients:
33
34 ```shell
35 prosodyctl shell user clients user@example.com
36 ```
37
38 ## Compatibility
39
40 Requires Prosody trunk (as of 2023-03-29). Not compatible with Prosody 0.12
41 and earlier.
42
43 ## Developers
44
45 ### Protocol
46
47 #### Listing clients
48
49 To list clients that have access to the user's account, send the following
50 stanza:
51
52 ```xml
53 <iq id="p" type="get">
54 <list xmlns="xmpp:prosody.im/protocol/manage-clients"/>
55 </iq>
56 ```
57
58 The server will respond with a list of clients:
59
60 ```xml
61 <iq id="p" to="mattj-gajim@auth2.superxmpp.com/gajim.UYJKBHKT" type="result" xmlns="jabber:client">
62 <clients xmlns="xmpp:prosody.im/protocol/manage-clients">
63 <client connected="true" id="client/zeiP41HLglIu" type="session">
64 <first-seen>2023-04-06T14:26:08Z</first-seen>
65 <last-seen>2023-04-06T14:37:25Z</last-seen>
66 <auth>
67 <password/>
68 </auth>
69 <user-agent>
70 <software>Gajim</software>
71 <uri>https://gajim.org/</uri>
72 <device>Juliet's laptop</device>
73 </user-agent>
74 </client>
75 <client connected="false" id="grant/HjEEr45_LQr" type="access">
76 <first-seen>2023-03-27T15:16:09Z</first-seen>
77 <last-seen>2023-03-27T15:37:24Z</last-seen>
78 <user-agent>
79 <software>REST client</software>
80 </user-agent>
81 </client>
82 </clients>
83 </iq>
84 ```
85
86 On the `<client/>` tag most things are self-explanatory. The following attributes
87 are defined:
88
89 - 'connected': a boolean that reflects whether this client has an active session
90 on the server (i.e. this includes connected and "hibernating" sessions).
91 - 'id': an opaque reference for the client, which can be used to revoke access.
92 - 'type': either `"session"` if this client is known to have an active or inactive
93 client session on the server, or "access" if no session has been established (e.g.
94 it may have been granted access to the account, but only used non-XMPP APIs or
95 never logged in).
96
97 The `<first-seen/>` and `<last-seen/>` elements contain timestamps that reflect
98 when a client was first granted access to the user's account, and when it most
99 recently used that access. For active sessions, it may reflect the current
100 time or the time of the last login.
101
102 The `<user-agent/>` element contains information about the client software. It
103 may contain any of three optional child elements, each containing text content:
104
105 - `<software/>` - the name of the software
106 - `<uri/>` - a URI/URL for the client, such as a homepage
107 - `<device/>` - a human-readable identifier/name for the device where the client
108 runs
109
110 The `<auth/>` element lists the known authentication methods that the client
111 has used to gain access to the account. The following elements are defined:
112
113 - `<password/>` - the client has presented a valid password
114 - `<grant/>` - the client has a valid authorization grant (e.g. via OAuth)
115 - `<fast/>` - the client has active FAST tokens
116
117 #### Revoking access
118
119 To revoke a client's access, send a `<revoke/>` element with an 'id' attribute
120 containing one of the client ids fetched from the list:
121
122 ```xml
123 <iq id="p" type="set">
124 <revoke xmlns="xmpp:prosody.im/protocol/manage-clients" id="grant/HjEEr45_LQr" />
125 </iq>
126 ```
127
128 The server will respond with an empty result if the revocation succeeds:
129
130 ```xml
131 <iq id="p" type="result" />
132 ```
133
134 If the client has previously authenticated with a password, there is no way to
135 revoke access except by changing the user's password. If you request
136 revocation of such a client, the server will respond with a 'service-unavailable'
137 error, with the 'password-reset-required' application error:
138
139 ```xml
140 <iq id="p" type="error">
141 <error type="cancel">
142 <service-unavailable xmlns="xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'">
143 <password-reset-required xmlns="xmpp:prosody.im/protocol/manage-clients"/>
144 </error>
145 </iq>
146 ```