XEP-0494: Client Access Management

A common feature of secure online services today is the ability for users to monitor and manage what software and services have access to their account. This is especially relevant for XMPP - a diverse ecosystem of software around an interoperable standard can lead to many and various types of applications having access to a user’s account.

This specification provides a standard protocol to let a user view and manage what has access to their account.

2. Requirements¶

3. Use Cases¶

3.1 Listing clients¶

To list clients that have access to the user’s account, send a <list/> payload element inside an <iq/> of type 'get':

Example 1. Client requests list of clients from server¶

<iq id="5468616e6b73" type="get">
  <list xmlns="urn:xmpp:cam:0"/>
</iq>

The server will respond with a list of clients:

Example 2. Client receives list of clients from server¶

<iq id="5468616e6b73" to="user@example.com/UYJKBHKT" type="result" xmlns="jabber:client">
  <clients xmlns="urn:xmpp:cam:0">
    <client connected="true" id="zeiP41HLglIu" type="session">
      <first-seen>2023-04-06T14:26:08Z</first-seen>
      <last-seen>2023-04-06T14:37:25Z</last-seen>
      <auth>
        <password/>
      </auth>
      <permission status="unrestricted"/>
      <user-agent>
        <software>Gajim</software>
        <uri>https://gajim.org/</uri>
        <device>Juliet's laptop</device>
      </user-agent>
    </client>
    <client connected="false" id="HjEEr45_LQr" type="access">
      <first-seen>2023-03-27T15:16:09Z</first-seen>
      <last-seen>2023-03-27T15:37:24Z</last-seen>
      <auth>
          <grant/>
      </auth>
      <permission status="normal"/>
      <user-agent>
        <software>REST client</software>
      </user-agent>
    </client>
  </clients>
</iq>

The following attributes are defined on the <client/> tag:

'connected': a boolean that reflects whether this client has an active session on the server ("active" includes connected and sessions that may be disconnected but may yet be reconnected, e.g. using Stream Management (XEP-0198) [1]).
'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 MUST be included, and lists the known authentication methods that the client has used to gain access to the account. The following child elements are defined:

<password/> - the client has presented a valid password
<grant/> - the client has a valid authorization grant (e.g. via OAuth). The <grant/> element may also contain details of the grant and the associated permissions (described below)
<fast/> - the client has active FAST tokens

The <auth/> element is explicitly extensible - alternative/future authentication mechanisms may be included under appropriate namespaces.

The <permission/> element MUST also be present, and contains details of the client’s level of access to the user’s account. The 'status' attribute of the permission element MUST be present and MUST be one of the following values:

"unrestricted" - the client has full unlimited access to the account.
"normal" - the client has general access to the account, but some security-relevant features may be restricted (such as managing account access and changing the account password).
"restricted" - the client has additional restrictions in place. In such a case the details of these restrictions SHOULD be included in an appropriate format (and namespace) within the <permission/> element.

3.2 Revoking access¶

To revoke a client’s access, send a <revoke/> payload element with an 'id' attribute containing one of the client ids fetched from the list:

Example 3. Client requests revocation of another client's access¶

<iq id="4e4c6e6574" type="set">
  <revoke xmlns="urn:xmpp:cam:0" id="HjEEr45_LQr" />
</iq>

The server will respond with an empty result if the revocation succeeds:

Example 4. Server confirms successful revocation¶

<iq id="4e4c6e6574" type="result" />

If the identified 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:

Example 5. Server indicates password reset required¶

<iq id="4e4c6e6574" type="error">
  <error type="cancel">
    <service-unavailable xmlns="xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'">
    <password-reset-required xmlns="urn:xmpp:cam:0"/>
  </error>
</iq>

Changing the user’s password can be performed using In-Band Registration (XEP-0077) [2].

4. Accessibility Considerations¶

This XEP is not deemed to require any additional accessibility considerations beyond those normally required for implementations.

5. Security Considerations¶

Servers MUST ensure that the provided client listing is an accurate representation of what has access to the user’s account. It MUST ensure that the protocol described here is protected from unauthorized access by third parties, to avoid information leaks and denial of service.

In addition to the account owner, implementations MAY provide functionality for server administrators to view and revoke access on behalf of users. For example, if a popular third-party client is discovered to be compromised, an administrator may want to immediately revoke its access to all accounts on their server.

6. Privacy Considerations¶

This specification provides methods designed to enhance privacy, by allowing revocation of account access when it is no longer needed.

To allow users to make an informed decision, the client listing needs to contain useful information that can help them to identify clients that are suspicious, unwanted, or no longer needed. This may involve the server storing additional information about client sessions than it would otherwise. Implementations MUST make it possible for a deployment to choose whether to keep certain information, and how long for. This ensures that deployments can adapt to their own requirements, the needs and wishes of their users, and the jurisdictions they operate in.

The defaults should aim to strike a balance between privacy and security, and keep client session information for no longer than necessary.

7. IANA Considerations¶

8. XMPP Registrar Considerations¶

9. Acknowledgements¶

Thanks to Kim Alvefur for assisting in the review of this protocol, and the associated prototype implemention. Thanks to NLnet for providing the funding to work on XMPP authentication improvements.

Appendices

Appendix A: Document Information¶

Appendix B: Author Information¶

Matthew Wild

Appendix C: Legal Notices¶

Copyright

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).

Visual Presentation

The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.

Appendix D: Relation to XMPP¶

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Appendix F: Requirements Conformance¶

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".