From f0d8f60b66d93d5a7342bc38ffeda2966b691351 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Wed, 10 Jun 2020 13:42:20 -0700 Subject: [PATCH] help: Add basic documentation of organization owners. --- docs/production/security-model.md | 33 ++++--- templates/zerver/help/change-a-users-role.md | 24 +++-- .../zerver/help/export-your-organization.md | 8 +- templates/zerver/help/include/admin-only.md | 2 +- .../zerver/help/roles-and-permissions.md | 15 ++- templates/zerver/help/stream-permissions.md | 93 ++++++++++--------- templates/zerver/security.md | 6 +- 7 files changed, 106 insertions(+), 75 deletions(-) diff --git a/docs/production/security-model.md b/docs/production/security-model.md index f8c76cc7b7..d80a2d9374 100644 --- a/docs/production/security-model.md +++ b/docs/production/security-model.md @@ -12,7 +12,7 @@ announcement). ## Secure your Zulip server like your email server * It's reasonable to think about security for a Zulip server like you - do security for a team email server -- only trusted administrators + do security for a team email server -- only trusted individuals within an organization should have shell access to the server. In particular, anyone with root access to a Zulip application server @@ -102,11 +102,12 @@ strength allowed is controlled by two settings in without joining the stream. Guests can only access streams that another user adds them to. - * Organization admins can see and modify most aspects of a private - stream, including the membership and estimated traffic. Admins - generally cannot see messages sent to private streams or do things - that would indirectly give them access to those messages, like - adding members or changing the stream privacy settings. + * Organization owners and administrators can see and modify most + aspects of a private stream, including the membership and + estimated traffic. Owners and administrators generally cannot see + messages sent to private streams or do things that would + indirectly give them access to those messages, like adding members + or changing the stream privacy settings. * Non-admins cannot easily see which private streams exist, or interact with them in any way until they are added. Given a stream name, they can @@ -124,8 +125,8 @@ strength allowed is controlled by two settings in * Message content can only ever be modified by the original author. - * Any message visible to an organization administrator can be deleted at - any time by that administrator. + * Any message visible to an organization owner or administrator can + be deleted at any time by that administrator. * See [Configuring message editing and deletion](https://zulip.com/help/configure-message-editing-and-deletion) @@ -133,19 +134,21 @@ strength allowed is controlled by two settings in ## Users and Bots -* There are four types of users in a Zulip organization: Organization - Administrators, Members (normal users), Guests, and Bots. +* There are several types of users in a Zulip organization: Organization + Owners, Organization Administrators, Members (normal users), Guests, + and Bots. -* Administrators have the ability to deactivate and reactivate other - human and bot users, delete streams, add/remove administrator - privileges, as well as change configuration for the organization. +* Owners and Administrators have the ability to deactivate and + reactivate other human and bot users, delete streams, add/remove + administrator privileges, as well as change configuration for the + organization. Being an organization administrator does not generally provide the ability to read other users' private messages or messages sent to private streams to which the administrator is not subscribed. There are two exceptions: - * Administrators may get access to private messages via some types of + * Organization owners may get access to private messages via some types of [data export](https://zulip.com/help/export-your-organization). * Administrators can change the ownership of a bot. If a bot is subscribed @@ -189,7 +192,7 @@ strength allowed is controlled by two settings in integrations like the Jabber, IRC, and Zephyr mirrors. API super user bots cannot be created by Zulip users, including - organization administrators. They can only be created on the command + organization owners. They can only be created on the command line (via `manage.py knight --permission=api_super_user`). ## User-uploaded content diff --git a/templates/zerver/help/change-a-users-role.md b/templates/zerver/help/change-a-users-role.md index 399999f937..9e4fafbeb2 100644 --- a/templates/zerver/help/change-a-users-role.md +++ b/templates/zerver/help/change-a-users-role.md @@ -2,13 +2,23 @@ {!admin-only.md!} -Users join as -[administrators, members, or guests](/help/roles-and-permissions), depending -on how they were invited. +Users join as [owners, administrators, members, or +guests](/help/roles-and-permissions), depending on how they were +invited. -An organization administrator can change the role of any other user. -An admin can revoke their own administrative privileges if there is at least one -other administrator in the organization. +An organization owner can change the role of any user. An +organization administrator can change the role of most users, but +cannot create or demote an organization owner. + +You can can revoke your own owner or administrative privileges if +there is at least one other owner in the organization (Consider +promoting a new owner or [deactivating the +organization](/help/deactivate-your-organization) instead). + +**Changes** Organization owners were introduced in Zulip 2.2; users +that were marked as administrators in older Zulip instances are +automatically converted during the upgrade to Zulip 2.2 into owners +(who have the same permissions as administrators did previously). ### Change a user's role @@ -19,7 +29,7 @@ other administrator in the organization. 1. Find the user you would like to manage. Click the **pencil** () to the right of their name. -1. Under **User role**, select **Administrator**, **Member** or **Guest**. +1. Under **User role**, select **Owner**, **Administrator**, **Member** or **Guest**. 1. Click **Save changes**. The new rights will take effect immediately. diff --git a/templates/zerver/help/export-your-organization.md b/templates/zerver/help/export-your-organization.md index b5d5621474..ee9fba9369 100644 --- a/templates/zerver/help/export-your-organization.md +++ b/templates/zerver/help/export-your-organization.md @@ -1,7 +1,5 @@ # Export your organization -{!admin-only.md!} - !!! warn "" These instructions are specific to the hosted Zulip Cloud service. If you're running your own server, you may be looking for our @@ -23,6 +21,8 @@ Zulip Standard customers have access to **full export without member consent**. ## Public export +{!admin-only.md!} + {start_tabs} {settings_tab|data-exports-admin} @@ -41,6 +41,8 @@ with lots of messages or uploaded files. ## Full export with member consent +{!owner-only.md!} + {start_tabs} 1. Email support@zulip.com with your organization's zulip.com URL, asking for @@ -69,6 +71,8 @@ import. ## Full export without member consent +{!owner-only.md!} + This export is limited to paid Zulip Standard customers, though in rare cases may be available to other organizations in case of due legal process. diff --git a/templates/zerver/help/include/admin-only.md b/templates/zerver/help/include/admin-only.md index 67cd3ee90f..59b3e6e505 100644 --- a/templates/zerver/help/include/admin-only.md +++ b/templates/zerver/help/include/admin-only.md @@ -1,2 +1,2 @@ !!! warn "" - This feature is only available to organization administrators. + This feature is only available to organization owners and administrators. diff --git a/templates/zerver/help/roles-and-permissions.md b/templates/zerver/help/roles-and-permissions.md index fe4ae2800c..ea336874d4 100644 --- a/templates/zerver/help/roles-and-permissions.md +++ b/templates/zerver/help/roles-and-permissions.md @@ -1,21 +1,30 @@ # Roles and permissions -There are several roles in a Zulip organization. +There are several possible roles in a Zulip organization. + +* **Organization Owner**: Can manage users, public streams, + organization settings, and billing. * **Organization Administrator**: Can manage users, public streams, - organization settings, and billing. + organization settings, and billing. Cannot create or demote + organization owners. * **Member**: Has access to all public streams. This is the default role for most users. * **Guest**: Can only access streams they've been added to. Cannot create - new streams. + new streams or invite other users. For details of the access control model, see [Stream permissions](/help/stream-permissions). You can decide what role to invite a user as when you [send them an invitation](/help/invite-new-users#send-invitations). +Organization owners can do anything an organization administrator can +do. For brevity, we may sometimes refer to "organization +administrators" being able to do something; unless stated explicitly, +this means "organization owners and administrators" can do that thing. + ## Billing and guests Guests are only available on Zulip on-premise and on paid plans for Zulip diff --git a/templates/zerver/help/stream-permissions.md b/templates/zerver/help/stream-permissions.md index 76991ec40a..855388a982 100644 --- a/templates/zerver/help/stream-permissions.md +++ b/templates/zerver/help/stream-permissions.md @@ -16,73 +16,78 @@ determine who receives a message. There are three types of streams in Zulip. At a high level: -* Organization admins can see and modify most aspects of a private stream, - including the membership and estimated traffic. Admins generally cannot see stream - messages or do things that would indirectly give them access to stream - messages, like adding members or changing the stream privacy settings. +* Organization owners and administrators can see and modify most + aspects of a private stream, including the membership and estimated + traffic. Owners and administrators generally cannot see private + stream messages or do things that would give them access to private + stream messages, like adding new subscribers or changing the stream + privacy settings. -* Non-admin members cannot easily see which private streams exist, or interact with - them in any way until they are added. Given a stream name, they can figure - out whether a stream with that name exists, but cannot see any other +* [Organization members](/help/roles-and-permissions) cannot easily + see which private streams exist, or interact with them in any way + until they are added. Given a stream name, they can figure out + whether a stream with that name exists, but cannot see any other details about the stream. * From the perspective of a guest, all streams are private streams, and they additionally can't add other members to the streams they are subscribed to. -There are two situations in which an organization administrator can access -private stream messages: +There are two situations in which an organization owner or +administrator can access private stream messages: * Via some types of [data export](/help/export-your-organization). -* Administrators can change the ownership of a bot. If a bot is subscribed - to a private stream, then an administrator can get access to that stream by - taking control of the bot, though the access will be limited to what the - bot can do. (E.g. incoming webhook bots cannot read messages.) +* Owners and administrators can change the ownership of a bot. If a + bot is subscribed to a private stream, then an administrator can get + access to that stream by taking control of the bot, though the + access will be limited to what the bot can do. (E.g. incoming + webhook bots cannot read messages.) ## Detailed permissions ### Public streams -| | Org admins | Members | Guests -|--- |--- |--- |--- -| Join | ✔ | ✔ | -| Unsubscribe | ◾ | ◾ | ◾ -| Add others | ✔ | ✔ | -| See subscriber list | ✔ | ✔ | ◾ -| See full history | ✔ | ✔ | ◾ -| See estimated traffic | ✔ | ✔ | ◾ -| Post | ✔ | ✶ | ✶ -| Change the privacy | ✔ | | -| Rename | ✔ | | -| Edit the description | ✔ | | -| Remove others | ✔ | | -| Delete | ✔ | | +| | Owners and admins | Members | Guests +|--- |--- |--- |--- +| Join | ✔ | ✔ | +| Unsubscribe | ◾ | ◾ | ◾ +| Add others | ✔ | ✔ | +| See subscriber list | ✔ | ✔ | ◾ +| See full history | ✔ | ✔ | ◾ +| See estimated traffic | ✔ | ✔ | ◾ +| Post | ✔ | ✶ | ✶ +| Change the privacy | ✔ | | +| Rename | ✔ | | +| Edit the description | ✔ | | +| Remove others | ✔ | | +| Delete | ✔ | | ✔ Always ◾   If subscribed to the stream -✶ [Configurable](/help/stream-sending-policy). Org admins and -Members can, by default, post to any public stream, and Guests can -only post to public streams if they are subscribed. +✶ [Configurable](/help/stream-sending-policy). Owners, +Administrators, and Members can, by default, post to any public +stream, and Guests can only post to public streams if they are +subscribed. ### Private streams -| | Org admins | Members | Guests -|--- |--- |--- |--- -| Join | | | -| Unsubscribe | ◾ | ◾ | ◾ -| Add others | ◾ | ◾ | -| See subscriber list | ✔ | ◾ | ◾ -| See full history | ✶ | ✶ | ✶ -| See estimated traffic | ✔ | ◾ | ◾ -| Post | ◾ | ✶ | ✶ -| Change the privacy | ◾ | | -| Rename | ✔ | | -| Edit the description | ✔ | | -| Remove others | ✔ | | -| Delete | ✔ | | +| | Owners and admins | Members | Guests +|--- |--- |--- |--- +| Join | | | +| Unsubscribe | ◾ | ◾ | ◾ +| Add others | ◾ | ◾ | +| See subscriber list | ✔ | ◾ | ◾ +| See full history | ✶ | ✶ | ✶ +| See estimated traffic | ✔ | ◾ | ◾ +| Post | ◾ | ✶ | ✶ +| Change the privacy | ◾ | | +| Rename | ✔ | | +| Edit the description | ✔ | | +| Remove others | ✔ | | +| Delete | ✔ | | ✔ Always diff --git a/templates/zerver/security.md b/templates/zerver/security.md index b7b4c0fbe2..f9d0567700 100644 --- a/templates/zerver/security.md +++ b/templates/zerver/security.md @@ -36,7 +36,7 @@ priority. streams with any number of subscribers, as well as public streams available to all organization members. We also support guest accounts, which only have access to a fixed set of streams, and announcement - streams, where only organization administrators can post. + streams, where only organization owners and administrators can post. - By default, users can maintain their own names and email addresses, but Zulip also supports [restricting changes](/help/restrict-name-and-email-changes) and @@ -78,7 +78,7 @@ priority. - Users can rotate their accounts’ credentials, blocking further access from any compromised Zulip credentials. With Zulip on-premise, server administrators can additionally revoke and reset any user’s credentials. -- Administrators can deactivate any +- Owners and administrators can deactivate any [user](/help/deactivate-or-reactivate-a-user), [bot, or integration](/help/deactivate-or-reactivate-a-bot). - With Zulip on-premise, @@ -90,7 +90,7 @@ priority. ## Integrity and auditing -- Zulip administrators can configure users’ +- Zulip owners and administrators can configure users’ [ability to edit or delete messages](/help/configure-message-editing-and-deletion), and whether deleted messages are retained in the database or deleted permanently. Zulip by default stores the complete history of all message