Mercurial > prosody-modules
changeset 5314:7c123d3285de
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 (20 months ago) |
parents | 80ecba092027 |
children | 8501baa7ef3f |
files | mod_client_management/README.md |
diffstat | 1 files changed, 114 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- a/mod_client_management/README.md Thu Apr 06 17:24:16 2023 +0100 +++ b/mod_client_management/README.md Thu Apr 06 19:31:29 2023 +0100 @@ -26,7 +26,121 @@ When `enforce_client_ids` is enabled, clients that don't support SASL2 and provide a client id will be denied access. +## Shell usage + +You can use this module via the Prosody shell. For example, to list a user's +clients: + +```shell +prosodyctl shell user clients user@example.com +``` + ## Compatibility Requires Prosody trunk (as of 2023-03-29). Not compatible with Prosody 0.12 and earlier. + +## Developers + +### Protocol + +#### Listing clients + +To list clients that have access to the user's account, send the following +stanza: + +```xml +<iq id="p" type="get"> + <list xmlns="xmpp:prosody.im/protocol/manage-clients"/> +</iq> +``` + +The server will respond with a list of clients: + +```xml +<iq id="p" to="mattj-gajim@auth2.superxmpp.com/gajim.UYJKBHKT" type="result" xmlns="jabber:client"> + <clients xmlns="xmpp:prosody.im/protocol/manage-clients"> + <client connected="true" id="client/zeiP41HLglIu" type="session"> + <first-seen>2023-04-06T14:26:08Z</first-seen> + <last-seen>2023-04-06T14:37:25Z</last-seen> + <auth> + <password/> + </auth> + <user-agent> + <software>Gajim</software> + <uri>https://gajim.org/</uri> + <device>Juliet's laptop</device> + </user-agent> + </client> + <client connected="false" id="grant/HjEEr45_LQr" type="access"> + <first-seen>2023-03-27T15:16:09Z</first-seen> + <last-seen>2023-03-27T15:37:24Z</last-seen> + <user-agent> + <software>REST client</software> + </user-agent> + </client> + </clients> +</iq> +``` + +On the `<client/>` tag most things are self-explanatory. The following attributes +are defined: + +- 'connected': a boolean that reflects whether this client has an active session +on the server (i.e. this includes connected and "hibernating" sessions). +- 'id': an opaque reference for the client, which can be used to revoke access. +- 'type': either `"session"` if this client is known to have an active or inactive + client session on the server, or "access" if no session has been established (e.g. + it may have been granted access to the account, but only used non-XMPP APIs or + never logged in). + +The `<first-seen/>` and `<last-seen/>` elements contain timestamps that reflect +when a client was first granted access to the user's account, and when it most +recently used that access. For active sessions, it may reflect the current +time or the time of the last login. + +The `<user-agent/>` element contains information about the client software. It +may contain any of three optional child elements, each containing text content: + +- `<software/>` - the name of the software +- `<uri/>` - a URI/URL for the client, such as a homepage +- `<device/>` - a human-readable identifier/name for the device where the client + runs + +The `<auth/>` element lists the known authentication methods that the client +has used to gain access to the account. The following elements are defined: + +- `<password/>` - the client has presented a valid password +- `<grant/>` - the client has a valid authorization grant (e.g. via OAuth) +- `<fast/>` - the client has active FAST tokens + +#### Revoking access + +To revoke a client's access, send a `<revoke/>` element with an 'id' attribute +containing one of the client ids fetched from the list: + +```xml +<iq id="p" type="set"> + <revoke xmlns="xmpp:prosody.im/protocol/manage-clients" id="grant/HjEEr45_LQr" /> +</iq> +``` + +The server will respond with an empty result if the revocation succeeds: + +```xml +<iq id="p" type="result" /> +``` + +If the client has previously authenticated with a password, there is no way to +revoke access except by changing the user's password. If you request +revocation of such a client, the server will respond with a 'service-unavailable' +error, with the 'password-reset-required' application error: + +```xml +<iq id="p" type="error"> + <error type="cancel"> + <service-unavailable xmlns="xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'"> + <password-reset-required xmlns="xmpp:prosody.im/protocol/manage-clients"/> + </error> +</iq> +```