Docs: Split SSO docs into HowTo/Explanation (Diátaxis)

docs/user/commercial/single-sign-on.rst

@@ -1,5 +1,5 @@
-Single Sign-On
-==============
+Choosing a Single Sign-On approach
+==================================
 
 .. include:: /shared/admonition-rtd-business.rst
 
@@ -18,123 +18,26 @@ Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the
    :depth: 2
 
 
-SSO with VCS provider (GitHub, Bitbucket or GitLab)
----------------------------------------------------
+Single Sign-on with GitHub, Bitbucket or GitLab
+-----------------------------------------------
 
 Using an identity provider that supports authentication and authorization allows you to manage
-who has access to projects on Read the Docs, directly from the provider itself.
+who has access to projects on Read the Docs,
+directly from the provider itself.
 If a user needs access to your documentation project on Read the Docs,
-that user just needs to be granted permissions in the VCS repository associated with the project.
-
-You can enable this feature in your organization by going to
-your organization's detail page > :guilabel:`Settings` > :guilabel:`Authorization`
-and selecting :guilabel:`GitHub, GitLab or Bitbucket` as provider.
-
-Note the users created under Read the Docs must have their GitHub, Bitbucket or GitLab
-:doc:`account connected </connected-accounts>` in order to make SSO work.
-You can read more about `granting permissions on GitHub`_.
-
-.. warning:: Once you enable this option, your existing Read the Docs teams will not be used.
-
-.. _granting permissions on GitHub: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization
-
-
-Grant access to read the documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By granting **read** (or more) permissions to a user in the VCS repository
-you are giving access to read the documentation of the associated project on Read the Docs to that user.
-
-
-Grant access to administrate a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By granting **write** permission to a user in the VCS repository
-you are giving access to read the documentation *and* to be an administrator
-of the associated project on Read the Docs to that user.
-
-
-Grant access to import a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When SSO with a VCS provider is enabled, only owners of the Read the Docs organization can import projects.
-Adding users as owners of your organization will give them permissions to import projects.
-
-Note that to be able to import a project, that user must have **admin** permissions in the VCS repository associated.
-
-
-Revoke access to a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If a user should not have access anymore to a project, for any reason,
-a VCS repository's admin (e.g. user with Admin role on GitHub for that specific repository)
-can revoke access to the VCS repository and this will be automatically reflected in Read the Docs.
-
-The same process is followed in case you need to remove **admin** access,
-but still want that user to have access to read the documentation.
-Instead of revoking access completely, just need lower down permissions to **read** only.
+that user just needs to be granted permissions in the git repository associated with the project.
 
+Once you enable this option,
+your existing Read the Docs teams will not be used.
+All authentication will be done using your git provider,
+including any two-factor authentication and additional Single Sign-on that they support.
 
 SSO with Google Workspace
 -------------------------
 
 .. note:: Google Workspace was formerly called G Suite
 
-Using your company's Google email address (e.g. ``[email protected]``) allows you to
-manage authentication for your organization's members.
-As this identity provider does not provide authorization over each repositories/projects per user,
+This feature allows you to restrict access to users with a specific email address (e.g. ``[email protected]``),
+provided by Google.
+As this identity provider does not provide authorization over each project a user has access to,
 permissions are managed by the :ref:`internal Read the Docs's teams <commercial/organizations:Team Types>` authorization system.
-
-By default, users that sign up with a Google account do not have any permissions over any project.
-However, you can define which teams users matching your company's domain email address will auto-join when they sign up.
-Read the following sections to learn how to grant read and admin access.
-
-You can enable this feature in your organization by going to
-your organization's detail page > :guilabel:`Settings` > :guilabel:`Authorization`
-and selecting :guilabel:`Google` as provider and specifying your Google Workspace domain in the :guilabel:`Domain` field.
-
-
-Grant access to read a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can add a user under a read-only team to grant **read** permissions to all the projects under that team.
-This can be done under your organization's detail page > :guilabel:`Teams` > :guilabel:`Read Only` > :guilabel:`Invite Member`.
-
-To avoid this repetitive task for each employee of your company,
-the owner of the Read the Docs organization can mark one or many teams for users matching the company's domain email
-to join these teams automaically when they sign up.
-
-For example, you can create a team with the projects that all employees of your company should have access to
-and mark it as :guilabel:`Auto join users with an organization's email address to this team`.
-Then all users that sign up with their ``[email protected]`` email will automatically join this team and have **read** access to those projects.
-
-
-Grant access to administer a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can add a user under an admin team to grant **admin** permissions to all the projects under that team.
-This can be done under your organization's detail page > :guilabel:`Teams` > :guilabel:`Admins` > :guilabel:`Invite Member`.
-
-
-Grant access to users to import a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Making the user member of any admin team under your organization (as mentioned in the previous section),
-they will be granted access to import a project.
-
-Note that to be able to import a project, that user must have **admin** permissions in the GitHub, Bitbucket or GitLab repository associated,
-and their social account connected with Read the Docs.
-
-
-Revoke user's access to a project
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To revoke access to a project for a particular user, you should remove that user from the team that contains that project.
-This can be done under your organization's detail page > :guilabel:`Teams` > :guilabel:`Read Only` and click :guilabel:`Remove` next to the user you want to revoke access.
-
-
-Revoke user's access to all the projects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-By disabling the Google Workspace account with email ``[email protected]``,
-you revoke access to all the projects that user had access and disable login on Read the Docs completely for that user.

docs/user/guides/administrators.rst

@@ -22,3 +22,6 @@ have a look at our :doc:`/tutorial/index`.
    importing-private-repositories
    Setup Build Notifications <build-notifications>
    Configure Pull Request Builds <pull-requests>
+   setup-single-sign-on-github-gitlab-bitbucket
+   setup-single-sign-on-google-email
+   manage-read-the-docs-teams

docs/user/guides/manage-read-the-docs-teams.rst

@@ -0,0 +1,37 @@
+How to manage Read the Docs teams
+=================================
+
+Adding a user to a team
+-----------------------
+
+Adding a user to a team gives them all the permissions available to that team,
+whether it's *read-only* or *admin*.
+This can be done by:
+
+* Navigating to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Username name>` > :guilabel:`Teams` > :guilabel:`<Team name>`
+* Clicking :guilabel:`Invite Member`.
+* Input the user's Read the Docs username or email address.
+* Clicking :guilabel:`Add member`.
+
+Removing a user from a team
+----------------------------
+
+Removing a user to a team removes all permissions that team gave them
+
+* Navigating to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Username name>` > :guilabel:`Teams` > :guilabel:`<Team name>`
+* Clicking :guilabel:`Remove` next to the user.
+
+
+Grant access to users to import a project
+-----------------------------------------
+
+Make the user a member of any team with *admin* permissions,
+they will be granted access to import a project.
+
+Automating this process
+-----------------------
+
+You can manage teams more easily using our :doc:`/commercial/single-sign-on` features.
+
+
+.. seealso:: Our infomation on :doc:`/commercial/organizations`.

docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst

@@ -0,0 +1,86 @@
+How to setup Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket
+===================================================================
+
+.. include:: /shared/admonition-rtd-business.rst
+
+This how-to guide will provide instructions on how to enable :abbr:`SSO (Single Sign-on)` with GitHub, GitLab, or Bitbucket.
+If you want more information on this feature,
+please read :doc:`/commercial/single-sign-on`
+
+Prerequisites
+-------------
+
+Organization permissions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change your Organization's settings,
+you need to be an *owner* of that organization.
+
+You can validate your ownership of the Organization with these steps:
+
+* Navigate to :guilabel:`Username dropdown` > :guilabel:`Organizations` > :guilabel:`<Organization name>`
+* Look at the **Owners** UI elements on the right menu.
+
+If you'd like to to modify this setting and are not an owner,
+you can ask an existing organization owner to follow this guide.
+
+User setup
+~~~~~~~~~~
+
+Users in your organization must have their GitHub, Bitbucket, or GitLab
+:doc:`account connected </connected-accounts>`,
+otherwise they will lose access to all repositories.
+
+Enabling SSO
+------------
+
+You can enable this feature in your organization by:
+* Navigate to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Username name>` > :guilabel:`Settings` > :guilabel:`Authorization`
+* Select :guilabel:`GitHub, GitLab or Bitbucket` on the *Provider* dropdown.
+* Select :guilabel:`Save`
+
+The users in your organization **must connect**  their GitHub, Bitbucket or GitLab
+:doc:`account connected </connected-accounts>`,
+otherwise they will lose access to all repositories.
+You can read more about `granting permissions on GitHub`_ in their documentation.
+
+.. warning:: Once you enable this option, your existing Read the Docs teams will not be used.
+
+.. _granting permissions on GitHub: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization
+
+Grant access to read the documentation
+--------------------------------------
+
+By granting **read** permissions to a user in your git repository,
+you are giving the user access to read the documentation of the associated project on Read the Docs.
+
+Grant access to administer a project
+------------------------------------
+
+By granting **write** permission to a user in the git repository,
+you are giving the user access to read the documentation *and* to be an administrator of the associated project on Read the Docs.
+
+Grant access to import a project
+--------------------------------
+
+When SSO with a VCS provider is enabled, only owners of the Read the Docs organization can import projects.
+Adding users as owners of your organization will give them permissions to import projects.
+
+To be able to import a project,
+that user must have **admin** permissions in the VCS repository associated.
+
+Revoke access to a project
+--------------------------
+
+If a user should not have access to a project,
+you can revoke access to the git repository,
+and this will be automatically reflected in Read the Docs.
+
+The same process is followed in case you need to remove admin access,
+but still want that user to have access to read the documentation.
+Instead of revoking access completely,
+just need their permissions to read only.
+
+.. seealso::
+    To learn more about choosing a Single Sign-on approach,
+    please read :doc:`/commercial/single-sign-on`.

docs/user/guides/setup-single-sign-on-google-email.rst

@@ -0,0 +1,70 @@
+How to setup Single Sign-On (SSO) with Google Workspace
+=======================================================
+
+.. include:: /shared/admonition-rtd-business.rst
+
+This how-to guide will provide instructions on how to enable :abbr:`SSO (Single Sign-on)` with Google Workspace.
+If you want more information on this feature,
+please read :doc:`/commercial/single-sign-on`
+
+Prerequisites
+-------------
+
+Organization permissions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change your Organization's settings,
+you need to be an *owner* of that organization.
+
+You can validate your ownership of the Organization with these steps:
+
+* Navigate to :guilabel:`Username dropdown` > :guilabel:`Organizations` > :guilabel:`<Organization name>`
+* Look at the **Owners** UI elements on the right menu.
+
+If you'd like to to modify this setting and are not an owner,
+you can ask an existing organization owner to follow this guide.
+
+User setup
+~~~~~~~~~~
+
+Using this setup,
+all users who have access to the domain you configure will be granted a subset of permissions on your organization automatically on account creation.
+Other users can also be added to your organization and given access in an ad hoc manner.
+
+Enabling SSO
+------------
+
+By default, users that sign up with a Google account do not have any permissions over any project.
+However, you can define which teams users matching your company's domain email address will auto-join when they sign up.
+
+You can enable this feature in your organization:
+
+* Navigate to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Username name>` > > :guilabel:`Settings` > :guilabel:`Authorization`
+* Select :guilabel:`Google` as the *Provider*
+* Specify your Google Workspace domain as the *Domain*.
+
+Configure team for all users to join
+------------------------------------
+
+You can mark one or many teams that users are automatically joined when they sign up with a matching email address.
+Configure this option by:
+
+* Navigating to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Organization name>` > :guilabel:`Teams` > :guilabel:`<Team name>`
+* Click :guilabel:`Edit team`
+* Enable *Auto join users with an organization's email address to this team*.
+* Click :guilabel:`Save`
+
+With this enabled,
+all users that sign up with their ``[email protected]`` email will automatically join this team.
+These teams can have either *read-only* or *admin* permissions over a set of projects.
+
+Revoke user's access to all the projects
+----------------------------------------
+
+By disabling the Google Workspace account with email ``[email protected]``,
+you revoke access to all the projects that user had access and disable login on Read the Docs completely for that user.
+
+.. seealso::
+    * Additional user management options are available at :doc:`/guides/manage-read-the-docs-teams`.
+    * To learn more about choosing a Single Sign-on approach,
+    please read :doc:`/commercial/single-sign-on`.