On Changing Passwords for Neuron® accounts
The TAG Neuron® hosts accounts for various types of users, and there are typically different interfaces to interact with the Neuron® and published services and connected peers for different kinds of users. This includes XMPP users, Web users, Mail users, Agent API users, etc.
XMPP
The main interface with the TAG Neuron® has been XMPP. Clients connect to a Neuron® using a XMPP Client-to-server (c2s) binding mechanism (TCP socket, HTTP, Web-socket, etc.). XMPP Brokers (other Neurons) connect other Neurons using XMPP Server-to-Server (s2s) binding mechanisms. Servers identify themselvs using X.509 certificates and mutual TLS-connections (mTLS). Clients, while able to use mutual TLS also, most often use user name and password credentials to authenticate themselves with the corresponding broker. All this process is defined in the IETF standards defining the XMPP protocol and bindings. Changing passwords is included in these standards, and is therefore an intrinsic part of XMPP.
Chat
The first interface for administrating a TAG Neuron®, has been via XMPP, more specifically, via XMPP chat. This is often called Chat Admin, which works like a terminal prompt. An administrator with chat admin privileges, can use the reset password command to reset the password of a user on the Neuron®. Passwords are automatically randomized, with no option to enter a password manually, to ensure sufficient entropy is provided.
Web
The TAG Neuron® also provides a web interface for administering the Neuron®. It is available via the /Admin.md resource. Access to this resource requires login, and available options are restricted to show only authorized options.
Session User
All users however, have access to the Change Password option under Session (on Neurons from build time 2023-07-12). Clicking this option opens a page where you can change the password of the currently logged in account.
When changing the password for the currently logged in account, you must provide the existing password again (to protect the account in case somebody else tries to change the password on an open page somebody has left open by mistake), as well as the new password twice. The new password must conform to the following rules:
- They must either be a sufficiently random BASE64-encoded binary string.
- Press the Create Random Password below to generate such passwords.
- Note: Copy password before pressing Change Password (unless you have an exceptional memory). The user will need it to login or change the password again.
- Or enter a password that:
- Is at least 12 characters long.
- Contains at least 3 letters.
- Of which at least 1 is upper-case.
- Of which at least 1 is lower-case.
- Contains at least 3 digits.
- Contains at least 3 of punctuations or symbols.
- Contains no control characters, surrogates or white-space.
Users
With a User here, is referred to a user of the TAG Neuron® directly. This can be an operator, developer, service integrator, external service, etc., that needs to be able to perform actions on the Neuron® that requires authentication and authorization. Such users can be managed by commands available under the Security header in the Admin portal of the Neuron®. An administrator would first need to create Roles, which are a collection of positive and negative privilege references. Once suitable roles are defined, users can be defined. Each user has a reference to one or more roles, which define the privileges the user has in the system. Each user can log-in to the Neuron® and change their password, according to the preceding paragraph. An operator with sufficient privileges, can also go into the Users menu (under Security), select the User and change the password manually. It is recommended this password be randomized, to avoid simple passwords that can be easily broken. Chinging the password this way, may be necessary, if the credentials are lost, forgotten or compromized.
Broker Accounts
Users that only use the Neuron® indirectly, i.e. use it as a broker to interact with other entities, use Broker Accounts. These are not considered Users of the Neuron® directly. They cannot use the credentials to login or access administrative resources on the Neuron. These Broker accounts are also managed using a separate set of commands, available under the Broker header on the Admin page, as opposed to the Security header.
Access to the Broker Accounts are typically made using XMPP. Changing the password of an account in XMPP is done in accordance with the XMPP protocol standard. Some users may access such accounts via other means, for instance, when relaying or sending/receiving e-mail messages. Such interfaces do not have an intrinsic method to change the password. If such accounts require a change of password, an operator can do so from the Admin page.
There are two types of broker accounts: Those that are created manually (i.e. an operator on the Neuron® has created the account via the Admin page), and those that have been created by the users themselves, using an API Key. While standard XMPP allows for anyone to create an account on an XMPP broker, the TAG Neuron® is restricted in this regard, and requires an API Key and Secret, to be allowed to create an account. The operator creates API Keys, and secrets, and assigns a maximum number of accounts that can be created using that API Key (this amount can be changed by the operator at a later time). Clients with access to such a key and secret can create an account accordingly. The account that is created in this way, is linked to the API Key, and operators can in this way follow the usage of keys over time. (The process of getting the API Key and Secret, when creating an account, is part of what is called the onboarding process; The key and secret is selected by an onboarding server, based on the purpose the user has, and locality information or other preferences and/or invitations.)
An operator can change the password of a broker account (or enable or disable it) via the Admin page. Manually created accounts are managed under the option Manually created accounts. Accounts created using an API Key are accessed first, by selecting the API Keys option, and then opening the corresponding API Key. On the page listing details about the API Key, there’s a field called Number of accounts created, with a link in the form of a digit. Clicking on this digit opens a page listing the accounts that have been created using that API Key. Clicking on any of the accounts in this list, will open the corresponding account, allowing the operator to change the password or enabled/disable it.
SMTP
The broker bridges the XMPP and SMTP protocols, so that an XMPP client can send e-mails to a mail client by using its e-mail address, and a mail client can send chat messages to a XMPP client, by e-mailing its JID (XMPP address). Both a Bare JID and an e-mail address have the same format: account@domain, so they can be used interchangably. If you use an account for e-mail, the principal method to change the password is still via XMPP (or let an operator do it). There is no mechanism to change the password via SMTP.
Agent API
A user of an app or service that uses the Agent API to create an account on a TAG Neuron® is basically an XMPP client, except connection with the broker is done using a REST API instead of standardized XMPP. This REST API is easier to consume and interact with, for clients and environment who are limited to using HTTP as a protocol, and Javascript or JSON as main representation format. This is often the case when developing web applications or apps based on web technologies. Even though the connection to the Neuron® is done via a Web REST API, the client still has access to the features and possibilities XMPP provides. This includes interacting with other XMPP clients seamlessly, in the federated network. It also includes the ability to perform common XMPP-tasks, such as sending Information Queries (i.e. iq stanzas) and Asynchronous Messages (i.e. message stanzas) via the Web API.
Chaning the password of the currently connected account is done, by sending an iq stanza of type set, with the following content (white-space added for readability only). The to attribute in the iq stanza, should be empty (or contain the domain name of the server), as the stanza is sent to the server itself, and not a peer.
<query xmlns='jabber:iq:register'>
<username>USERNAME</username>
<password>PASSWORD</password>
</query>
The response will either be OK or not. If OK, the password has been changed. If not OK, the contents of the response will contain the reason. It may also contain a Data Form that can be presented to the user, in order to collect additional information.
ID Apps
In the TAG ID App, and derivatives, there’s difference between network password and local password. The local password, or PIN, is the password the user uses to unlock the app, or access protected functions. This password is too weak to be used in a meaningful way on the Internet, and therefore is never used in any communication with the TAG Neuron®. Instead, the app generates an invisible random password, with sufficient entropy, that is used in any communication when the server. This password is stored in the encrypted local database of the app, and accessible only if the user provides the correct PIN to unlock it.
The user can change its PIN in the app. When doing so, the app automatically creates a new network password also, and changes the password of the underlying XMPP connection seamlessly.