readthedocs · benjaoming · Dec 16, 2022 · Dec 13, 2022 · Dec 13, 2022 · Dec 13, 2022
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -4586,7 +4586,7 @@ Version 2.1.5
  * `@stsewd <https://github.com/stsewd>`__: Move project description to the top (`#3510 <https://github.com/readthedocs/readthedocs.org/pull/3510>`__)
  * `@RichardLitt <https://github.com/RichardLitt>`__: Docs: Rename "Good First Bug" to "Good First Issue" (`#3505 <https://github.com/readthedocs/readthedocs.org/pull/3505>`__)
  * `@stsewd <https://github.com/stsewd>`__: Fix regex for getting project and user (`#3501 <https://github.com/readthedocs/readthedocs.org/pull/3501>`__)
- * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in BitBucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
+ * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in Bitbucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
  * `@andrewgodwin <https://github.com/andrewgodwin>`__: "stable" appearing to track future release branches (`#3268 <https://github.com/readthedocs/readthedocs.org/issues/3268>`__)
  * `@cdeil <https://github.com/cdeil>`__: No module named pip in conda build (`#2827 <https://github.com/readthedocs/readthedocs.org/issues/2827>`__)
  * `@Yaseenh <https://github.com/Yaseenh>`__: building project does not generate new pdf with changes in it (`#2758 <https://github.com/readthedocs/readthedocs.org/issues/2758>`__)
@@ -4603,7 +4603,7 @@ Version 2.1.4
  * `@davidfischer <https://github.com/davidfischer>`__: Small formatting change to the Alabaster footer (`#3491 <https://github.com/readthedocs/readthedocs.org/pull/3491>`__)
  * `@matsen <https://github.com/matsen>`__: Fixing "resetting" misspelling. (`#3487 <https://github.com/readthedocs/readthedocs.org/pull/3487>`__)
  * `@ericholscher <https://github.com/ericholscher>`__: Add David to dev team listing (`#3485 <https://github.com/readthedocs/readthedocs.org/pull/3485>`__)
- * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in BitBucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
+ * `@ericholscher <https://github.com/ericholscher>`__: Check to make sure changes exist in Bitbucket pushes (`#3480 <https://github.com/readthedocs/readthedocs.org/pull/3480>`__)
  * `@ericholscher <https://github.com/ericholscher>`__: Use semvar for readthedocs-build to make bumping easier (`#3475 <https://github.com/readthedocs/readthedocs.org/pull/3475>`__)
  * `@davidfischer <https://github.com/davidfischer>`__: Add programming languages (`#3471 <https://github.com/readthedocs/readthedocs.org/pull/3471>`__)
  * `@humitos <https://github.com/humitos>`__: Remove TEMPLATE_LOADERS since it's the default (`#3469 <https://github.com/readthedocs/readthedocs.org/pull/3469>`__)

diff --git a/docs/dev/install.rst b/docs/dev/install.rst
@@ -196,7 +196,7 @@ Configuring connected accounts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 These are optional steps to setup the :doc:`connected accounts <rtd:connected-accounts>`
-(GitHub, GitLab, and BitBucket) in your development environment.
+(GitHub, GitLab, and Bitbucket) in your development environment.
 This will allow you to login to your local development instance
 using your GitHub, Bitbucket, or GitLab credentials
 and this makes the process of importing repositories easier.

diff --git a/docs/user/_includes/organization-permissions.rst b/docs/user/_includes/organization-permissions.rst
@@ -0,0 +1,15 @@
+:orphan:
+
+Organization permissions
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+To change your :doc:`Organization's </commercial/organizations>` 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 :guilabel:`Owners` section 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 take the actions listed.
diff --git a/docs/user/api/v3.rst b/docs/user/api/v3.rst
@@ -1652,7 +1652,7 @@ Remote Organizations
 ~~~~~~~~~~~~~~~~~~~~
 
 Remote Organizations are the VCS organizations connected via
-``GitHub``, ``GitLab`` and ``BitBucket``.
+``GitHub``, ``GitLab`` and ``Bitbucket``.
 
 
 Remote Organization listing
@@ -1715,7 +1715,7 @@ Remote Repositories
 ~~~~~~~~~~~~~~~~~~~
 
 Remote Repositories are the importable repositories connected via
-``GitHub``, ``GitLab`` and ``BitBucket``.
+``GitHub``, ``GitLab`` and ``Bitbucket``.
 
 
 Remote Repository listing

diff --git a/docs/user/commercial/single-sign-on.rst b/docs/user/commercial/single-sign-on.rst
@@ -1,15 +1,17 @@
-Single Sign-On
-==============
+Choosing a Single Sign-On (SSO) approach for your organization
+==============================================================
 
 .. include:: /shared/admonition-rtd-business.rst
 
-Single sign-on is supported on |com_brand| for all users.
+Single sign-on an optional feature on |com_brand| for all users.
+By default,
+you will use :doc:`teams </guides/manage-read-the-docs-teams>` within Read the Docs to manage user authorization.
 :abbr:`SSO (single sign-on)` will allow you to grant permissions to your organization's projects in an easy way.
 
 Currently, we support two different types of single sign-on:
 
-* Authentication *and* authorization are managed by the identity provider (e.g. GitHub, Bitbucket or GitLab)
-* Authentication (*only*) is managed by the identity provider (e.g. an active Google Workspace account with a verified email address)
+* Authentication *and* authorization are managed by the identity provider (GitHub, Bitbucket or GitLab)
+* Authentication (*only*) is managed by the identity provider (Google Workspace account with a verified email address)
 
 Users can log out by using the :ref:`Log Out <versions:Logging out>` link in the RTD flyout menu.
 
@@ -18,123 +20,40 @@ 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.
+Using an identity provider that supports authentication and authorization allows organization owners to manage
+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.
+that user just needs to be granted permissions in the git 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.
+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.
 
+Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-github-gitlab-bitbucket`.
 
 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]``),
+where ``company.com`` is a registered Google Workspace domain.
+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.
+This feature is only available on the **Pro plan** and above.
+Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-google-email`.
 
+Requesting additional providers
+-------------------------------
 
-Revoke user's access to all the projects
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+We are always interested in hearing from our users about what authentication needs they have.
+You can reach out to our :doc:`/support` to talk with us about any additional authentication needs you might have.
 
-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.
+.. tip::
+   Many additional providers can be supported via GitHub, Bitbucket, and GitLab SSO.
+   We will depend on those sites in order to authenticate you,
+   so you can use all your existing SSO methods already configured on those services.
diff --git a/docs/user/connected-accounts.rst b/docs/user/connected-accounts.rst
@@ -13,7 +13,7 @@ Connecting your account allows for:
 If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab
 credentials, you're all done. Your account is connected.
 
-To connect a social account, go to your :guilabel:`Username dropdown` > :guilabel:`Settings` > :guilabel:`Connected Services`.
+To connect a social account, go to your :guilabel:`<Username dropdown>` > :guilabel:`Settings` > :guilabel:`Connected Services`.
 From here, you'll be able to connect to your GitHub, Bitbucket or GitLab
 account. This process will ask you to authorize a connection to Read the Docs,
 that allows us to read information about and clone your repositories.

diff --git a/docs/user/features.rst b/docs/user/features.rst
@@ -7,7 +7,7 @@ Read the Docs offers a number of platform features that are possible because we
 Automatic Documentation Deployment
 ----------------------------------
 
-We integrate with GitHub, BitBucket, and GitLab.
+We integrate with GitHub, Bitbucket, and GitLab.
 We automatically create webhooks in your repository,
 which tell us whenever you push a commit.
 We will then build and deploy your docs every time you push a commit.

diff --git a/docs/user/guides/administrators.rst b/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
diff --git a/docs/user/guides/manage-read-the-docs-teams.rst b/docs/user/guides/manage-read-the-docs-teams.rst
@@ -0,0 +1,41 @@
+How to manage Read the Docs teams
+=================================
+
+Read the Docs uses teams within an organization to group users and provide permissions to projects.
+This guide will cover how to do team management,
+including adding and removing people from teams.
+You can read more about organizations and teams in our :doc:`/commercial/organizations` documentation.
+
+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:`<Organization 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 from a team removes all permissions that team gave them
+
+* Navigating to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Organization 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 on that team.
+
+Automating this process
+-----------------------
+
+You can manage teams more easily using our :doc:`Single Sign-On </commercial/single-sign-on>` features.
+
+.. seealso:: Our infomation on :doc:`/commercial/organizations`.
diff --git a/docs/user/guides/pull-requests.rst b/docs/user/guides/pull-requests.rst
@@ -60,7 +60,7 @@ No new builds are started when I open a pull request
 
    You may also notice this behavior if your Read the Docs account is not
    connected to your VCS provider account, or if it needs to be reconnected.
-   You can (re)connect your account by going to your :guilabel:`Username dropdown`,
+   You can (re)connect your account by going to your :guilabel:`<Username dropdown>`,
    :guilabel:`Settings`, then to :guilabel:`Connected Services`.
 
 

diff --git a/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst b/docs/user/guides/setup-single-sign-on-github-gitlab-bitbucket.rst
@@ -0,0 +1,78 @@
+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
+-------------
+
+.. include:: /_includes/organization-permissions.rst
+
+User setup
+~~~~~~~~~~
+
+Users in your organization must have their GitHub, Bitbucket, or GitLab
+:doc:`account connected </connected-accounts>`,
+otherwise they won't have access to any project on Read the Docs after performing this change.
+You can read more about `granting permissions on GitHub`_ in their documentation.
+
+.. _granting permissions on GitHub: https://docs.github.com/en/github/setting-up-and-managing-organizations-and-teams/repository-permission-levels-for-an-organization
+
+Enabling SSO
+------------
+
+You can enable this feature in your organization by:
+
+* Navigate to :guilabel:`<Username dropdown>` > :guilabel:`Organizations` > :guilabel:`<Organization name>` > :guilabel:`Settings` > :guilabel:`Authorization`
+* Select :guilabel:`GitHub, GitLab or Bitbucket` on the :guilabel:`Provider` dropdown.
+* Select :guilabel:`Save`
+
+.. warning::
+    Once you enable this option,
+    your existing Read the Docs :doc:`teams </guides/manage-read-the-docs-teams>` will not be used.
+    While testing you can enable SSO and then disable it without any data loss.
+
+Grant access to read private 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.
+By default, private git repositories are built as private documentation websites.
+Having **read** permissions to the git repository translates to having **view** permissions to a private documentation website.
+
+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 Git provider is enabled, only owners of the Read the Docs organization can import projects.
+
+To be able to import a project,
+a user must have:
+
+#. **admin** permissions in the associated Git repository.
+#. Ownership rights to the Read the Docs organization
+
+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,
+downgrade their permissions to *read only*.
+
+.. seealso::
+    To learn more about choosing a Single Sign-on approach,
+    please read :doc:`/commercial/single-sign-on`.