Mercurial > prosody-modules

comparison mod_client_management/README.md @ 5314:7c123d3285de

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_client_management: README: Update docs to detail shell and XMPP interfaces
author Matthew Wild <mwild1@gmail.com>
date Thu, 06 Apr 2023 19:31:29 +0100
parents 385346b6c81d
children e9af6abf2b1e
comparison
equal deleted inserted replaced
5313:80ecba092027 5314:7c123d3285de
24 client instance, and is also exposed to other XMPP entities the user communicates with. 24 client instance, and is also exposed to other XMPP entities the user communicates with.
25 25
26 When `enforce_client_ids` is enabled, clients that don't support SASL2 and provide a client id will be 26 When `enforce_client_ids` is enabled, clients that don't support SASL2 and provide a client id will be
27 denied access. 27 denied access.
28 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
29 ## Compatibility 38 ## Compatibility
30 39
31 Requires Prosody trunk (as of 2023-03-29). Not compatible with Prosody 0.12 40 Requires Prosody trunk (as of 2023-03-29). Not compatible with Prosody 0.12
32 and earlier. 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 ```