centersl/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-03-27 13:38:39 +07:00
Code Issues Packages Projects Releases Wiki Activity

docs(admin): improve property scope coverage

Browse Source 
Signed-off-by: Josh Richards <josh.t.richards@gmail.com>
This commit is contained in:
Josh Richards
2026-03-11 00:53:30 -04:00
parent e5d1abc95e
commit f06db6001a
1 changed files with 166 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

179
admin_manual/configuration_user/profile_configuration.rst
View File

@@ -49,20 +49,157 @@ all available ``config.php`` options.
Property scopes
---------------
User properties (Full name, Address, Website, Role, …) have specific visibility scopes (Private, Local, Federated, Published).
User properties (Full name, Address, Website, Role, …) have visibility scopes:
Private, Local, Federated, Published.
The visibility scopes are explained below:
These scopes are evaluated per attribute. A profile being reachable does not imply
that all its attributes are visible.
The visibility scopes are:
:Private:
Contact details visible locally only
:Local:
Contact details visible locally and through public link access on local instance
:Federated:
Contact details visible locally, through public link access and on trusted federated servers.
:Published:
Contact details visible locally, through public link access, on trusted federated servers and published to the public lookup server.
Most restrictive scope. Not exposed through public profile contexts, federation,
or the public lookup server.
The default values for each property for each new user is listed below, but you should consult the declaration of the ``DEFAULT_SCOPES`` constant in the ``OC\Accounts\AccountManager`` class (`see the code <https://github.com/nextcloud/server/blob/master/lib/private/Accounts/AccountManager.php>`_) to make sure these are up-to-date.
On local-instance user-to-user surfaces, ``Private`` data is not generally visible
to all local users. Visibility requires an authenticated requester and a
server-recognized known-user relationship with the target user.
:Local:
Contact details visible on the local instance and through public share-links
(where profile/account attributes are inherently required - i.e. as file
owner/uploader metadata, etc.). Not shared to federated servers and not published
to the public lookup server.
:Federated:
Contact details visible on the local instance, through local public-link contexts,
and on trusted federated servers.
:Published:
Contact details visible on the local instance, through local public-link contexts,
on trusted federated servers, and published to the public lookup server.
.. important::
A reachable profile does not mean all attributes are public. Each attribute is
filtered by its own scope, and effective visibility can also depend on the
consuming feature.
.. important::
On profile surfaces, the effective visibility is the more restrictive of
profile-visibility settings and property scope.
Scope audience overview
~~~~~~~~~~~~~~~~~~~~~~~
+------------+-------------------+-------------------------------------------------------------+--------------------+---------------------+----------------------+
| Scope | User themself (*) | Other users on same local instance | Public link/public | Trusted federation | Public lookup server |
+============+===================+=============================================================+====================+=====================+======================+
| Private | Yes | Limited: authenticated + known-user relation required | No | No | No |
+------------+-------------------+-------------------------------------------------------------+--------------------+---------------------+----------------------+
| Local | Yes | Yes | Yes | No | No |
+------------+-------------------+-------------------------------------------------------------+--------------------+---------------------+----------------------+
| Federated | Yes | Yes | Yes | Yes | No |
+------------+-------------------+-------------------------------------------------------------+--------------------+---------------------+----------------------+
| Published | Yes | Yes | Yes | Yes | Yes |
+------------+-------------------+-------------------------------------------------------------+--------------------+---------------------+----------------------+
(*) Scope primarily governs exposure to others; owner access follows account/endpoint behavior.
Known-user relation (for ``Private``)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For ``Private`` properties, Nextcloud may allow visibility on specific local feature
paths only when the requester is considered a *known user* of the target user.
In practical terms, this relation is derived by server contact-matching logic and is
directional (A known to B does not imply B known to A). Users are always known to
themselves.
What local users can see
~~~~~~~~~~~~~~~~~~~~~~~~
A common question is what one user can see about another user on the same instance.
In general, profile visibility is controlled by each property's scope, but the
exact UI/API surface depends on the consuming feature (for example profile page,
share dialogs, search, mentions, Contacts, and other integrations).
For local users on the same instance:
- ``Private``: not generally visible to all local users; visibility is restricted
to authenticated users that satisfy the known-user relation for that feature path.
- ``Local``: visible on the local instance.
- ``Federated``: visible on the local instance (and also shared with trusted federated servers).
- ``Published``: visible on the local instance (and also federated + public lookup).
Verification workflow for administrators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Because effective visibility can vary by feature path, administrators should verify
scope behavior in their own deployment.
Recommended test procedure:
1. Create test users:
- ``alice`` (target profile owner)
- ``bob`` (authenticated local user)
- ``charlie`` (second local user for control)
2. As ``alice``, set distinct test values for profile fields and assign different
scopes (Private, Local, Federated, Published).
3. Verify as ``alice``:
- Confirm owner-visible values as expected.
4. Verify as ``bob`` (authenticated local user):
- Check the feature paths used in your instance (for example profile page,
user card, share dialog, search, mentions, Contacts integrations).
- Confirm ``Local/Federated/Published`` fields are visible where expected.
- Confirm ``Private`` fields are visible only on paths that satisfy the known-user
relation and other feature constraints.
5. Verify as unauthenticated user (private browser session):
- Confirm only public-appropriate fields are visible.
6. Verify federation/publication behavior (if enabled):
- From a trusted federated server, confirm Federated/Published behavior.
- Confirm only Published fields are exposed to the public lookup server.
7. Re-test with a newly created user after changing
``account_manager.default_property_scope``:
- Confirm new defaults apply only to newly initialized accounts.
- Confirm existing users retain stored scopes unless explicitly changed.
.. tip::
Keep one "scope matrix" test account in staging and re-run this checklist after upgrades.
Scope defaults and precedence
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Visibility is determined per property using this order:
1. **Server defaults** from ``OC\Accounts\AccountManager::DEFAULT_SCOPES``.
2. **Administrator default override** via ``account_manager.default_property_scope``.
3. **User-set value** in personal/profile settings (subject to server-side constraints).
Practical implications:
- Admin overrides in ``account_manager.default_property_scope`` are applied at account
initialization and therefore affect **new users**.
- Existing users keep already stored scopes unless changed explicitly.
- ``PROPERTY_DISPLAYNAME`` and ``PROPERTY_EMAIL`` cannot be ``Private``; server-side
validation/enforcement requires at least ``Local``.
Default scope values
~~~~~~~~~~~~~~~~~~~~
Default values are defined in server code and may change over time. The authoritative
source is the ``DEFAULT_SCOPES`` constant in ``OC\Accounts\AccountManager``. The latest
version is `here <https://github.com/nextcloud/server/blob/master/lib/private/Accounts/AccountManager.php>`_).
Example defaults (verify against your deployed version):
+--------------+--------------------------+
| Property | Default visibility scope |
@@ -81,6 +218,10 @@ The default values for each property for each new user is listed below, but you
+--------------+--------------------------+
| Twitter | Local |
+--------------+--------------------------+
| Bluesky | Local |
+--------------+--------------------------+
| Fediverse | Local |
+--------------+--------------------------+
| Organisation | Local |
+--------------+--------------------------+
| Role | Local |
@@ -89,14 +230,26 @@ The default values for each property for each new user is listed below, but you
+--------------+--------------------------+
| Biography | Local |
+--------------+--------------------------+
| Birthdate | Local |
+--------------+--------------------------+
| Pronouns | Federated |
+--------------+--------------------------+
If you'd like to override the value for one or several default visibility scopes, use the ``account_manager.default_property_scope`` ``config.php`` configuration key, which defaults to an empty array:
Override defaults in ``config.php``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To override one or several default visibility scopes for *new users*, use
``account_manager.default_property_scope`` (default: empty array):
.. code-block:: php
'account_manager.default_property_scope' => [
\OCP\Accounts\IAccountManager::PROPERTY_PHONE => \OCP\Accounts\IAccountManager::SCOPE_PRIVATE,
\OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_FEDERATED
\OCP\Accounts\IAccountManager::PROPERTY_ROLE => \OCP\Accounts\IAccountManager::SCOPE_FEDERATED,
]
In the above example, the phone and role properties are respectively overwritten to the private and federated scopes. Note that these changes will only apply to *new* users, not existing ones.
In the above example, phone and role are overwritten to ``Private`` and
``Federated`` respectively.
.. note::
Use ``\OCP\Accounts\IAccountManager`` constants for both property keys and scope values.