prosody-hg: core/usermanager.lua history

usermanager: More consistent method behaviour, errors, and (pre-)events

Thu, 25 Sep 2025 16:53:35 +0100

usermanager: More consistent method behaviour, errors, and (pre-)events

This commit refactors most of the exported usermanager methods substantially
to ensure that all of them correctly check for the presence of the host and
method they are calling and return consistent errors if either is incorrect or
missing.

It also unifies the event and logging code, so as a result there are more
events being fired than before this commit (it also adds pre- events so that
modules can block an action from going ahead).

We don't have good test coverage of this API, but some manual testing suggests
it seems to be working okay...

core.usermanager: Fix COMPAT layer for legacy is_admin() function

Sat, 22 Mar 2025 11:53:15 +0100

core.usermanager: Fix COMPAT layer for legacy is_admin() function

Thanks ctrlaltca

Fixes #1912

usermanager: Add info logging for all usermanager account changes

Mon, 10 Mar 2025 11:52:55 +0000

usermanager: Add info logging for all usermanager account changes

usermanager: Include role_name in event for consistency with the 'removed' event

Thu, 13 Feb 2025 15:31:37 +0000

usermanager: Include role_name in event for consistency with the 'removed' event

usermanager, mod_auth_internal_hashed: Support metadata when disabling a user

Thu, 30 Nov 2023 09:47:00 +0000

usermanager, mod_auth_internal_hashed: Support metadata when disabling a user

This allows us to store a time, actor, comment and/or reason why an account
was disabled, which seems a generally useful thing to support.

usermanager: Add create_user_with_role() method to atomically set initial role

Thu, 29 Jun 2023 15:31:46 +0100

usermanager: Add create_user_with_role() method to atomically set initial role

core.usermanager: Correct formatting of not implemented error

Sun, 26 Mar 2023 16:51:33 +0200

core.usermanager: Correct formatting of not implemented error

Spaces, no hyphen, apparently.

core: Prefix module imports with prosody namespace

Fri, 17 Mar 2023 16:23:07 +0100

core: Prefix module imports with prosody namespace

authz: Add method for retrieving all roles

Sat, 04 Mar 2023 18:40:43 +0100

authz: Add method for retrieving all roles

Some of the OAuth stuff highlights a small need to retrieve a list of
roles somehow. Handy if you ever need a role selector in adhoc or
something.

Unless there's some O(n) thing we were avoiding?

core.usermanager: Fire events when enabling and disabling users

Thu, 23 Feb 2023 16:25:31 +0100

core.usermanager: Fire events when enabling and disabling users

Allow modules to act on this state change, e.g. kick accounts etc.

core.usermanager: Add methods for enabling and disabling users

Thu, 23 Feb 2023 16:24:41 +0100

core.usermanager: Add methods for enabling and disabling users

Calling into the auth module, where available.

core.usermanager: Link to docs for new role API to make warning more actionable

Sat, 27 Aug 2022 17:01:36 +0200

core.usermanager: Link to docs for new role API to make warning more actionable

core.usermanager: Update argument name in authz fallback method

Thu, 18 Aug 2022 15:42:07 +0200

core.usermanager: Update argument name in authz fallback method

It's not plural

core.usermanager: Remove obsolete authz fallback method

Thu, 18 Aug 2022 15:38:18 +0200

core.usermanager: Remove obsolete authz fallback method

core.usermanager: Add missing methods to fallback authz provider

Thu, 18 Aug 2022 14:10:21 +0200

core.usermanager: Add missing methods to fallback authz provider

core.usermanager: Add scoped luacheck ignore rule to reduce clutter

Thu, 18 Aug 2022 14:07:54 +0200

core.usermanager: Add scoped luacheck ignore rule to reduce clutter

mod_authz_internal: Expose convenience method to test if user can assume role

Thu, 18 Aug 2022 10:37:59 +0100

mod_authz_internal: Expose convenience method to test if user can assume role

mod_authz_internal, and more: New iteration of role API

Wed, 17 Aug 2022 16:38:53 +0100

mod_authz_internal, and more: New iteration of role API

These changes to the API (hopefully the last) introduce a cleaner separation
between the user's primary (default) role, and their secondary (optional)
roles.

To keep the code sane and reduce complexity, a data migration is needed for
people using stored roles in 0.12. This can be performed with

prosodyctl mod_authz_internal migrate

usermanager: Add back temporary is_admin to warn about deprecated API usage

Mon, 15 Aug 2022 15:25:07 +0100

usermanager: Add back temporary is_admin to warn about deprecated API usage

Goal: Introduce role-auth with minimal disruption

is_admin() is unsafe in a system with per-session permissions, so it has been
deprecated.

Roll-out approach:

1) First, log a warning when is_admin() is used. It should continue to
function normally, backed by the new role API. Nothing is really using
per-session authz yet, so there is minimal security concern.

The 'strict_deprecate_is_admin' global setting can be set to 'true' to
force a hard failure of is_admin() attempts (it will log an error and
always return false).

2) In some time (at least 1 week), but possibly longer depending on the number
of affected deployments: switch 'strict_deprecate_is_admin' to 'true' by
default. It can still be disabled for systems that need it.

3) Further in the future, before the next release, the option will be removed
and is_admin() will be permanently disabled.

usermanager: Remove concept of global authz provider

Fri, 12 Aug 2022 16:21:57 +0100

usermanager: Remove concept of global authz provider

Rationale:

- Removes a bunch of code!
- We don't have many cases where an actor is not bound to one of our hosts
- A notable exception is the admin shell, but if we ever attempt to lock those
sessions down, there is a load of other work that also has to be done. And
it's not clear if we would need a global authz provider for that anyway.
- Removes an extra edge case from the necessary mental model for operators
- Sessions that aren't bound to a host generally are anonymous or have an
alternative auth model (such as by IP addres).
- With the encapsulation now provided by util.roles, ad-hoc "detached roles"
can still be created anyway by code that needs them.

usermanager: Fix method name of global authz provider (thanks Zash)

Fri, 12 Aug 2022 11:58:25 +0100

usermanager: Fix method name of global authz provider (thanks Zash)

usermanager: Remove obsolete function from global authz provider

Thu, 11 Aug 2022 16:56:59 +0100

usermanager: Remove obsolete function from global authz provider

usermanager: Handle local JIDs being passed to get/set_jid_role()

Mon, 01 Aug 2022 20:26:00 +0100

usermanager: Handle local JIDs being passed to get/set_jid_role()

There is no reasonable fallback for set_jid_role() because users may have
multiple roles, so that's an error.

core.usermanager: Add missing stub authz methods to global authz provider

Wed, 20 Jul 2022 13:10:47 +0200

core.usermanager: Add missing stub authz methods to global authz provider

Except, should we have a global authz provider at all?

mod_authz_internal: Use util.roles, some API changes and config support

Tue, 19 Jul 2022 18:02:02 +0100

mod_authz_internal: Use util.roles, some API changes and config support

This commit was too awkward to split (hg record didn't like it), so:

- Switch to the new util.roles lib to provide a consistent representation of
a role object.

- Change API method from get_role_info() to get_role_by_name() (touches
sessionmanager and usermanager)

- Change get_roles() to get_user_roles(), take a username instead of a JID
This is more consistent with all other usermanager API methods.

- Support configuration of custom roles and permissions via the config file
(to be documented).

usermanager, mod_auth_*: Add get_account_info() returning creation/update time

Tue, 12 Jul 2022 13:14:47 +0100

usermanager, mod_auth_*: Add get_account_info() returning creation/update time

This is useful for a number of things. For example, listing users that need to
rotate their passwords after some event. It also provides a safer way for code
to determine that a user password has changed without needing to set a handler
for the password change event (which is a more fragile approach).

Switch to a new role-based authorization framework, removing is_admin()

Wed, 15 Jun 2022 12:15:01 +0100

Switch to a new role-based authorization framework, removing is_admin()

We began moving away from simple "is this user an admin?" permission checks
before 0.12, with the introduction of mod_authz_internal and the ability to
dynamically change the roles of individual users.

The approach in 0.12 still had various limitations however, and apart from
the introduction of roles other than "admin" and the ability to pull that info
from storage, not much actually changed.

This new framework shakes things up a lot, though aims to maintain the same
functionality and behaviour on the surface for a default Prosody
configuration. That is, if you don't take advantage of any of the new
features, you shouldn't notice any change.

The biggest change visible to developers is that usermanager.is_admin() (and
the auth provider is_admin() method) have been removed. Gone. Completely.

Permission checks should now be performed using a new module API method:

module:may(action_name, context)

This method accepts an action name, followed by either a JID (string) or
(preferably) a table containing 'origin'/'session' and 'stanza' fields (e.g.
the standard object passed to most events). It will return true if the action
should be permitted, or false/nil otherwise.

Modules should no longer perform permission checks based on the role name.
E.g. a lot of code previously checked if the user's role was prosody:admin
before permitting some action. Since many roles might now exist with similar
permissions, and the permissions of prosody:admin may be redefined
dynamically, it is no longer suitable to use this method for permission
checks. Use module:may().

If you start an action name with ':' (recommended) then the current module's
name will automatically be used as a prefix.

To define a new permission, use the new module API:

module:default_permission(role_name, action_name)
module:default_permissions(role_name, { action_name[, action_name...] })

This grants the specified role permission to execute the named action(s) by
default. This may be overridden via other mechanisms external to your module.

The built-in roles that developers should use are:

- prosody:user (normal user)
- prosody:admin (host admin)
- prosody:operator (global admin)

The new prosody:operator role is intended for server-wide actions (such as
shutting down Prosody).

Finally, all usage of is_admin() in modules has been fixed by this commit.
Some of these changes were trickier than others, but no change is expected to
break existing deployments.

EXCEPT: mod_auth_ldap no longer supports the ldap_admin_filter option. It's
very possible nobody is using this, but if someone is then we can later update
it to pull roles from LDAP somehow.

usermanager, mod_saslauth: Default to internal_hashed if no auth module specified

Thu, 10 Feb 2022 19:54:14 +0000

usermanager, mod_saslauth: Default to internal_hashed if no auth module specified

The default config was updated in this way long ago, but if no option was
present in the config, Prosody would load internal_plain.

This change can result in changes (for the better) for people using very old
configuration files lacking an 'authentication' setting.

core.usermanager: Implement noop role writes on global authz provider

Mon, 06 Dec 2021 22:38:27 +0100

core.usermanager: Implement noop role writes on global authz provider

So that the methods are there and don't cause an error.

usermanager: Fire user-roles-changed event when updating roles of a local user

Fri, 12 Nov 2021 13:25:09 +0000

usermanager: Fire user-roles-changed event when updating roles of a local user

usermanager, mod_authz_internal: Add methods to fetch users/JIDs of given role

Thu, 26 Aug 2021 16:35:43 +0100

usermanager, mod_authz_internal: Add methods to fetch users/JIDs of given role

usermanager: expose set_roles through API

Mon, 22 Mar 2021 21:24:57 +0100

usermanager: expose set_roles through API

usermanager: Fix traceback when checking admin status of host-only JIDs (fixes #1508)

Thu, 19 Mar 2020 14:12:40 +0000

usermanager: Fix traceback when checking admin status of host-only JIDs (fixes #1508)

usermanager, mod_authz_*: Merge mod_authz_config and mod_authz_internal into the latter

Sun, 23 Feb 2020 12:38:43 +0000

usermanager, mod_authz_*: Merge mod_authz_config and mod_authz_internal into the latter

usermanager: Add get_roles() function

Wed, 05 Feb 2020 17:41:14 +0000

usermanager: Add get_roles() function

mod_authz_internal, usermanager: Rename to mod_authz_config

Mon, 27 Jan 2020 22:28:52 +0000

mod_authz_internal, usermanager: Rename to mod_authz_config

usermanager: Load authz providers on components also

Mon, 27 Jan 2020 22:09:19 +0000

usermanager: Load authz providers on components also

usermanager, mod_authz_internal: Move admin-checking functionality into a module. Fixes #517 (ish).

Mon, 27 Jan 2020 21:54:59 +0000

usermanager, mod_authz_internal: Move admin-checking functionality into a module. Fixes #517 (ish).

Note: Removes the ability for mod_auth_* providers to determine user admin status. Such
modules will need to have their is_admin methods ported to be a mod_authz_* provider.

core: Use prosody.hosts instead of _G.hosts for consistency

Thu, 29 Mar 2018 16:58:06 +0200

core: Use prosody.hosts instead of _G.hosts for consistency

vairious: Add annotation when an empty environment is set [luacheck]

Wed, 28 Feb 2018 20:06:26 +0100

vairious: Add annotation when an empty environment is set [luacheck]

core.usermanager, various modules: Disconnect other resources on password change (thanks waqas) (fixes #512)

Fri, 28 Jul 2017 13:15:29 +0200

core.usermanager, various modules: Disconnect other resources on password change (thanks waqas) (fixes #512)

usermanager: Shortcircuit user existence check if they have existing sessions

Sun, 21 Feb 2016 19:30:45 +0100

usermanager: Shortcircuit user existence check if they have existing sessions

core.usermanager: Return as soon as possible once admin status is known

Sun, 06 Dec 2015 23:47:47 +0100

core.usermanager: Return as soon as possible once admin status is known

core.*: Remove use of module() function

Sat, 21 Feb 2015 10:42:19 +0100

core.*: Remove use of module() function

portmanager, s2smanager, sessionmanager, stanza_router, storagemanager, usermanager, util.xml: Add luacheck annotations

Wed, 06 May 2015 19:20:07 +0100

portmanager, s2smanager, sessionmanager, stanza_router, storagemanager, usermanager, util.xml: Add luacheck annotations

usermanager: Capitalize log message

Sat, 25 Apr 2015 14:22:59 +0200

usermanager: Capitalize log message

usermanager: Remove unused import of pairs()

Tue, 13 Aug 2013 19:38:05 +0100

usermanager: Remove unused import of pairs()

Remove all trailing whitespace

Fri, 09 Aug 2013 17:48:21 +0200

Remove all trailing whitespace

core.*: Complete removal of all traces of the "core" section and section-related code.

Sat, 23 Mar 2013 02:33:15 +0100

core.*: Complete removal of all traces of the "core" section and section-related code.

usermanager: Add support for iterating over accounts

Fri, 21 Sep 2012 17:26:25 +0200

usermanager: Add support for iterating over accounts

storagemanager: Add purge() for purging user data from all backends in use

Sun, 16 Sep 2012 02:18:07 +0200

storagemanager: Add purge() for purging user data from all backends in use

core.usermanager: Don't close sessions ourselves when deleting users. Instead, fire an event that modules can hook.

Sat, 25 Aug 2012 01:20:13 +0200

core.usermanager: Don't close sessions ourselves when deleting users. Instead, fire an event that modules can hook.

usermanager: Add method for deleting a user

Sat, 28 Jul 2012 21:55:05 +0200

usermanager: Add method for deleting a user

usermanager: Pass session on to auth provider (missing half of commit 0545a574667b) (thanks Zash)

Sat, 07 Jul 2012 02:32:39 +0100

usermanager: Pass session on to auth provider (missing half of commit 0545a574667b) (thanks Zash)

usermanager: Add log error for use of COMPAT config option 'anonymous_login'. To be removed in next version.

Sat, 28 Apr 2012 14:35:52 +0100

usermanager: Add log error for use of COMPAT config option 'anonymous_login'. To be removed in next version.

usermanager: Prep admin JIDs (fixes issue#276).

Wed, 14 Dec 2011 07:19:58 +0500

usermanager: Prep admin JIDs (fixes issue#276).

usermanager: Check host exists before trying to look up admins for it

Tue, 05 Apr 2011 13:26:19 +0100

usermanager: Check host exists before trying to look up admins for it

usermanager: Add delete_user method

Tue, 04 Jan 2011 17:11:51 +0000

usermanager: Add delete_user method

usermanager: Have methods not implemented in the active provider fall back to the null provider (later we can add support for chains of providers)

Tue, 04 Jan 2011 17:11:37 +0000

usermanager: Have methods not implemented in the active provider fall back to the null provider (later we can add support for chains of providers)

usermanager: Change dummy provider method to return an error string also (method not implemented)

Tue, 04 Jan 2011 17:10:56 +0000

usermanager: Change dummy provider method to return an error string also (method not implemented)