From 9826e37bcff27290e0c7c924401d3c61604c3245 Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Tue, 15 Aug 2023 17:08:03 +0200 Subject: [PATCH 1/3] Update docs for users and groups GA release --- .../concepts/projects_accounts_access.rst | 70 ++++--------------- docs/platform/howto/add-groups-projects.rst | 5 +- docs/platform/howto/manage-groups.rst | 3 - docs/platform/howto/manage-org-users.rst | 5 +- .../reference/project-member-privileges.rst | 53 +++++++++++--- docs/tools/aiven-console.rst | 6 +- .../aiven-console/howto/create-accounts.rst | 10 +-- .../howto/create-manage-teams.rst | 6 ++ 8 files changed, 75 insertions(+), 83 deletions(-) diff --git a/docs/platform/concepts/projects_accounts_access.rst b/docs/platform/concepts/projects_accounts_access.rst index 79fca5864d..8fa5b25e36 100644 --- a/docs/platform/concepts/projects_accounts_access.rst +++ b/docs/platform/concepts/projects_accounts_access.rst @@ -21,6 +21,8 @@ Grouping your projects in organizations and organizational units lets you centra * ACLs for service plans are inherited, meaning all projects within an organization or organizational unit will have the same service plan. +* Groups - User groups managed at the organization level and assigned to projects + * Teams - Specific to a single organization or organizational unit and cannot be shared between them * Support contracts - Specific to a single organization or organizational unit and cannot be shared between them @@ -38,69 +40,27 @@ Projects are collections of services and user permissions. Each project must hav * Project-based: Each project contains all the services for an internal project, with naming that highlights the relevant environment; for example: ``customer-success-prod`` and ``business-analytics-test``. -Service access management --------------------------- - -There are two ways that you can manage access to Aiven services: - -* Direct access via projects -* Indirectly via role-based access controls (RBAC) - -Smaller teams usually favor direct access, while larger teams favor RBAC to simplify complex access requirements. - -Project members and roles -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Project and service access management +-------------------------------------- -You can define different levels of access for each project member using roles: +You can grant users access to services at the project level by adding them as project members, either individually or in :doc:`groups `. -* **Administrator**: Can change and view billing information, remove members, and create, edit, and delete services. When you create a project, you automatically receive this access level. +The Aiven platform lets you use a mix of group and individual access rights for projects. One example of this is to grant read-only access to all projects in an organization or unit for a group of external contractors. -* **Operator**: Full access to services, but can't modify billing information or project members. +Groups +~~~~~~ -* **Developer**: Can manage existing services (for example, creating databases and connecting to them), but can't make any changes that would affect billing (for example, starting or stopping services). - -* **Read Only**: Can view services, but can't make any changes to them. - - -.. list-table:: - :header-rows: 1 - - * - Role - - View status - - Connect - - Deploy - - Billing/editing access - * - Administrator - - |tick| - - |tick| - - |tick| - - |tick| - * - Operator - - |tick| - - |tick| - - |tick| - - - * - Developer - - |tick| - - |tick| - - - - - * - Read Only - - |tick| - - - - - - -.. Note:: - The Read-Only role cannot view or copy service account passwords, but the Administrator, Operator and Developer roles have full access to manage service accounts. +:doc:`Organization users ` can be :doc:`added to groups `, making it easy to control access to the services in a project. When you :doc:`add a group to a project `, you also select the role for that group. This role gives all users in that group the same level of access to all services in the project. Teams ~~~~~ -You can also use teams within organizations or organizational units to control access to projects for a group of users instead of specifying them per project. When you create a team, you choose which projects to associate it to and define the roles. - -One example of this is to grant read-only access to all projects in an organization or unit for a team of external contractors. The Aiven platform lets you use a mix of team and individual access rights for projects. +.. important:: + **Teams are becoming groups** + + :doc:`Groups ` are an easier way to control access to your organization's projects and services for a group of users. -Another option is to set up :doc:`SAML single sign-on (SSO) ` for an organization that automatically adds users to a team when they sign up. For greater security, you may want to use a combination of SAML and RBAC regardless of the size of team. +You can also use teams within organizations or organizational units to control access to projects for a group of users. When you create a team, you choose which projects to add it to. Another option is to set up :doc:`SAML single sign-on (SSO) ` for an organization that automatically adds users to a team when they sign up. For greater security, you may want to use a combination of SAML and RBAC regardless of the size of team. Best practices for organizations --------------------------------- @@ -119,4 +79,4 @@ You could, for example, group projects into organizational units that correspond **Large organizations** -For large organizations, it's best to keep all of your projects in organizational units instead of organizations. By keeping all of your projects in organizational units you can define teams, support contracts, and billing groups for each group of projects. +For large organizations, it's best to keep all of your projects in organizational units instead of organizations. By keeping all of your projects in organizational units you can centrally manage things like support contracts and billing groups for each group of projects. diff --git a/docs/platform/howto/add-groups-projects.rst b/docs/platform/howto/add-groups-projects.rst index 6226f1be75..d239a1554c 100644 --- a/docs/platform/howto/add-groups-projects.rst +++ b/docs/platform/howto/add-groups-projects.rst @@ -1,9 +1,6 @@ Add groups to projects ====================== -.. important:: - Groups are available as a feature preview and must be :doc:`enabled in the user profile `. - Give :doc:`groups ` of organization users access to a project and the services in it by adding groups to it. When you add a group, you set the permission level by assigning the group a :doc:`role ` for that specific project. Add groups to a project @@ -15,7 +12,7 @@ Add groups to a project #. Select the groups that you want to add to the project. -#. Select a **Role**. This role will be assigned to all users in all selected groups. +#. Select a **Role**. This :doc:`role ` will be assigned to all users in all selected groups. #. Click **Add groups**. diff --git a/docs/platform/howto/manage-groups.rst b/docs/platform/howto/manage-groups.rst index 2a93ec14f1..71ac7d7da1 100644 --- a/docs/platform/howto/manage-groups.rst +++ b/docs/platform/howto/manage-groups.rst @@ -1,9 +1,6 @@ Create and manage groups in an organization ============================================ -.. important:: - Groups are available as a feature preview and must be :doc:`enabled in the user profile `. - Create groups of users in your organization to make it easier to :doc:`give users with similar roles access to projects `. You need to :doc:`invite users to your organization ` before adding them to a group. Create a group diff --git a/docs/platform/howto/manage-org-users.rst b/docs/platform/howto/manage-org-users.rst index 9d2c00e03a..768ad38e3d 100644 --- a/docs/platform/howto/manage-org-users.rst +++ b/docs/platform/howto/manage-org-users.rst @@ -1,9 +1,6 @@ Manage users in an organization ================================ -.. important:: - Organization users is an early availability feature. To use it, :doc:`enable the feature preview ` in your user profile. - Adding users to your organization lets you give them access to specific organizational units, projects, and services within that organization. Invite users to an organization @@ -27,7 +24,7 @@ The users receive an email with instructions to sign up (for new users) and acce Remove users from an organization ---------------------------------- -If you remove a user from an organization, they will also be removed from all teams and projects and no longer have access to any resources in the organization. +If you remove a user from an organization, they will also be removed from all groups and projects and no longer have access to any resources in the organization. To remove a user from an organization: diff --git a/docs/platform/reference/project-member-privileges.rst b/docs/platform/reference/project-member-privileges.rst index 0de0c7736b..be5dd0ed50 100644 --- a/docs/platform/reference/project-member-privileges.rst +++ b/docs/platform/reference/project-member-privileges.rst @@ -1,22 +1,17 @@ Project member roles ===================== -User permissions are assigned at the project level by role. Each user added to a project - individually or as part of a :doc:`group ` - is assigned a role for that project. +User permissions are assigned at the project level by role. Each user added to a project - individually or as part of a :doc:`group ` - becomes a project member and is assigned a role for that project. -.. important:: +You can grant different levels of access to project members using roles: - Roles can only be managed by project **Admin** users on the **Members** page. - -Project roles and their permissions ------------------------------------- - -The project roles and their permissions are: * **Admin**: Full access to the project and its services. * Do not have access to organization settings such as billing. * Are the only users allowed to add more users to the project. - + * When you create a project, you automatically have this access level. + .. note:: Every project must have at least one admin user. @@ -36,3 +31,43 @@ The project roles and their permissions are: * **Read-only**: Only allowed to view services. * Cannot make any changes to the project or its services. + + +.. list-table:: + :header-rows: 1 + + * - Role + - View services + - Create services + - Manage services + - Connect + - Power services on/off + - Edit members and roles + * - Administrator + - |tick| + - |tick| + - |tick| + - |tick| + - |tick| + - |tick| + * - Operator + - |tick| + - |tick| + - |tick| + - |tick| + - |tick| + - + * - Developer + - |tick| + - |tick| + - |tick| + - |tick| + - + - + * - Read Only + - |tick| + - + - + - + - + - diff --git a/docs/tools/aiven-console.rst b/docs/tools/aiven-console.rst index a8697db760..6b8cfdba7b 100644 --- a/docs/tools/aiven-console.rst +++ b/docs/tools/aiven-console.rst @@ -43,14 +43,14 @@ The :doc:`organization or organizational unit `. -.. note:: We strongly recommend creating an organization. It makes managing your projects much easier and comes with many additional features, such as teams (user groups), billing groups, and SAML authentication. +.. note:: We strongly recommend creating an organization. It makes managing your projects much easier and comes with many additional features, such as groups, billing groups, and SAML authentication. Organization and organizational unit settings are available on the **Admin** page. Here you can: -* :doc:`Manage your teams` +* :doc:`Manage your groups` * Create new projects under an organization or organizational unit * Configure :doc:`authentication methods for an organization ` -* View logs of activity such as the adding or removing of team members, changing authentication methods, and more +* View logs of activity such as the adding or removing of users, changing authentication methods, and more * Rename or delete an organization or organizational unit Projects and services diff --git a/docs/tools/aiven-console/howto/create-accounts.rst b/docs/tools/aiven-console/howto/create-accounts.rst index 84f9daaf1c..a85df88548 100644 --- a/docs/tools/aiven-console/howto/create-accounts.rst +++ b/docs/tools/aiven-console/howto/create-accounts.rst @@ -1,7 +1,7 @@ Create organizations and organizational units ============================================== -**Organizations** and **organizational units** (or **units**) can be used to group projects and apply common settings like authentication and teams (user groups). For details and recommendations on creating hierarchical organizations in Aiven, see :doc:`Organizations, projects, and managing access permissions `. +**Organizations** and **organizational units** (or **units**) can be used to group projects and apply common settings like authentication and access for groups of users. For details and recommendations on creating hierarchical organizations in Aiven, see :doc:`Organizations, projects, and managing access permissions `. Create an organizational unit --------------------------------- @@ -22,7 +22,7 @@ You can create an organizational unit within an organization to group your proje #. Click **Create organizational unit**. -Your organizational unit is shown in the **Organizational units** section. Click the unit name to view and manage it's teams and projects. +Your organizational unit is shown in the **Organizational units** section. Click the unit name to view and manage it's groups and projects. .. note:: Only one level of nesting is supported. This means that organizational units cannot be created within other units. @@ -34,7 +34,7 @@ Create an organization .. important:: We recommend using **only one organization** and creating organizational units to group your projects. - Creating a new organization requires you to manually configure organization-level settings again such as :doc:`billing groups, authentication settings, and teams `. + Creating a new organization requires you to manually configure organization-level settings again such as :doc:`billing groups, authentication settings, and groups `. #. Click the user information icon and select **Organizations**. @@ -46,8 +46,8 @@ Create an organization #. If you want to invite admin users to the organization, set the toggle to **Yes** and enter their email addresses. They will receive an email invitation with a confirmation link. - .. important:: When admin users accept the invitation, they are added to the default team that has full control over the organization and the projects assigned to it. + .. important:: Admin users have full control over the organization and the projects assigned to it after they accept the invitation,. #. Click **Create organization**. -The **Admin** page opens, where you can add organizational units, and manage teams, projects, and other settings. \ No newline at end of file +The **Admin** page opens, where you can add organizational units, and manage groups, projects, and other settings. \ No newline at end of file diff --git a/docs/tools/aiven-console/howto/create-manage-teams.rst b/docs/tools/aiven-console/howto/create-manage-teams.rst index 6040497980..a493912b12 100644 --- a/docs/tools/aiven-console/howto/create-manage-teams.rst +++ b/docs/tools/aiven-console/howto/create-manage-teams.rst @@ -2,6 +2,12 @@ Create and manage teams ======================= +.. important:: + **Teams are becoming groups** + + :doc:`Groups ` are an easier way to control access to your organization's projects and services for a group of users. + + **Teams** let you create user groups and assign different access levels to specific projects in your organization or org unit. When you :doc:`create an organization or organizational unit `, a team is automatically created with admin access to the organization or org unit and its projects. Users must be part of an organization before being added to a team. To create and manage teams, click **Admin** and then select **Teams**. From e18b8168471cd1138429659178b022aa2937ea12 Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Fri, 25 Aug 2023 17:53:43 +0200 Subject: [PATCH 2/3] Update teams info --- docs/platform/howto/manage-unassigned-projects.rst | 4 ++-- docs/tools/aiven-console/howto/create-manage-teams.rst | 9 +++++---- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/platform/howto/manage-unassigned-projects.rst b/docs/platform/howto/manage-unassigned-projects.rst index bdbcb4d738..676ab0cfc6 100644 --- a/docs/platform/howto/manage-unassigned-projects.rst +++ b/docs/platform/howto/manage-unassigned-projects.rst @@ -41,11 +41,11 @@ If you don't have any organization yet, you can create one: #. If you want to invite admin users to the organization, set the toggle to **Yes** and enter their email addresses. They will receive an email invitation with a confirmation link. - .. important:: When admin users accept the invitation, they are added to the default team that has full control over the organization and the projects assigned to it. + .. important:: When admin users accept the invitation, they have full control over the organization and the projects assigned to it. #. Click **Create organization**. -The **Admin** page opens, where you can add organizational units, and manage teams, projects, and other settings. +The **Admin** page opens, where you can add organizational units, and manage users, groups, and other settings. Manage unassigned projects with the API diff --git a/docs/tools/aiven-console/howto/create-manage-teams.rst b/docs/tools/aiven-console/howto/create-manage-teams.rst index a493912b12..1bd79bfd06 100644 --- a/docs/tools/aiven-console/howto/create-manage-teams.rst +++ b/docs/tools/aiven-console/howto/create-manage-teams.rst @@ -8,9 +8,7 @@ Create and manage teams :doc:`Groups ` are an easier way to control access to your organization's projects and services for a group of users. -**Teams** let you create user groups and assign different access levels to specific projects in your organization or org unit. When you :doc:`create an organization or organizational unit `, a team is automatically created with admin access to the organization or org unit and its projects. - -Users must be part of an organization before being added to a team. To create and manage teams, click **Admin** and then select **Teams**. +**Teams** let you create user groups and assign different access levels to specific projects. Users must be part of an organization before being added to a team. To create and manage teams, click **Admin** and then select **Teams**. Create a new team -------------------------- @@ -33,7 +31,10 @@ Add users to a team The user will get an email with an invitation link. Add projects and roles to a team -------------------------------------------- +---------------------------------- + +.. important:: + Teams cannot be assigned to units. For each team you can specify which projects they can access and the level of permissions: From 05ddd31fd28f9a64f905bed224a4c66ac8697aaf Mon Sep 17 00:00:00 2001 From: Stacey Salamon Date: Mon, 28 Aug 2023 12:34:34 +0200 Subject: [PATCH 3/3] Update SAML articles --- docs/platform/howto/saml/saml-authentication.rst | 2 +- docs/platform/howto/saml/setup-saml-auth0.rst | 2 +- docs/platform/howto/saml/setup-saml-azure.rst | 2 +- docs/platform/howto/saml/setup-saml-fusionauth.rst | 2 +- docs/platform/howto/saml/setup-saml-google.rst | 2 +- docs/platform/howto/saml/setup-saml-jumpcloud.rst | 2 +- docs/platform/howto/saml/setup-saml-okta.rst | 2 +- docs/platform/howto/saml/setup-saml-onelogin.rst | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/platform/howto/saml/saml-authentication.rst b/docs/platform/howto/saml/saml-authentication.rst index e273ccdf85..c165ce3b62 100644 --- a/docs/platform/howto/saml/saml-authentication.rst +++ b/docs/platform/howto/saml/saml-authentication.rst @@ -35,7 +35,7 @@ SAML Authentication methods are configured at the organization level: #. Click on **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown the two parameters needed for the SAML authentication setup in your Identity Provider: diff --git a/docs/platform/howto/saml/setup-saml-auth0.rst b/docs/platform/howto/saml/setup-saml-auth0.rst index e88580b9ba..d25b4a9832 100644 --- a/docs/platform/howto/saml/setup-saml-auth0.rst +++ b/docs/platform/howto/saml/setup-saml-auth0.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in Auth0: diff --git a/docs/platform/howto/saml/setup-saml-azure.rst b/docs/platform/howto/saml/setup-saml-azure.rst index 73eff44881..d367f56866 100644 --- a/docs/platform/howto/saml/setup-saml-azure.rst +++ b/docs/platform/howto/saml/setup-saml-azure.rst @@ -13,7 +13,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in Microsoft Azure AD: diff --git a/docs/platform/howto/saml/setup-saml-fusionauth.rst b/docs/platform/howto/saml/setup-saml-fusionauth.rst index 0df5730b00..b3d2977bd1 100644 --- a/docs/platform/howto/saml/setup-saml-fusionauth.rst +++ b/docs/platform/howto/saml/setup-saml-fusionauth.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. #. Click **Add method**. diff --git a/docs/platform/howto/saml/setup-saml-google.rst b/docs/platform/howto/saml/setup-saml-google.rst index f28a320ee0..24ed87634a 100644 --- a/docs/platform/howto/saml/setup-saml-google.rst +++ b/docs/platform/howto/saml/setup-saml-google.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in Google: diff --git a/docs/platform/howto/saml/setup-saml-jumpcloud.rst b/docs/platform/howto/saml/setup-saml-jumpcloud.rst index 01a09436db..f5ab95d303 100644 --- a/docs/platform/howto/saml/setup-saml-jumpcloud.rst +++ b/docs/platform/howto/saml/setup-saml-jumpcloud.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in JumpCloud: diff --git a/docs/platform/howto/saml/setup-saml-okta.rst b/docs/platform/howto/saml/setup-saml-okta.rst index d479bf0bdf..82aec0372b 100644 --- a/docs/platform/howto/saml/setup-saml-okta.rst +++ b/docs/platform/howto/saml/setup-saml-okta.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in Okta: diff --git a/docs/platform/howto/saml/setup-saml-onelogin.rst b/docs/platform/howto/saml/setup-saml-onelogin.rst index 2f8c5c1aec..1f0122b87a 100644 --- a/docs/platform/howto/saml/setup-saml-onelogin.rst +++ b/docs/platform/howto/saml/setup-saml-onelogin.rst @@ -12,7 +12,7 @@ Prerequisite steps in Aiven Console #. Click **Add authentication method**. -#. Enter a name and select SAML. You can also select the teams that users will be added to when they sign up or log in through this authentication method. +#. Enter a name and select SAML. You can also select the groups that users will be added to when they sign up or log in through this authentication method. You are shown two parameters needed to set up the SAML authentication in OneLogin: