Add authentication documentation (#11834)

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

@@ -31,6 +31,8 @@ including any two-factor authentication and additional Single Sign-on that they
 
 Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-github-gitlab-bitbucket`.
 
+.. _sso_google_workspace:
+
 SSO with Google Workspace
 -------------------------
 
@@ -42,6 +44,8 @@ permissions are managed by the :ref:`internal Read the Docs's teams <commercial/
 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`.
 
+.. _sso_saml:
+
 SSO with SAML
 -------------
 

docs/user/guides/access/index.rst

@@ -27,6 +27,9 @@ How-to guides: security and access
     a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
     a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
 
+⏩️ :doc:`Manage Maintainers </guides/managing-maintainers>`
+    Learn how to manage maintainers for your projects on |org_brand|.
+
 .. toctree::
    :maxdepth: 1
    :hidden:
@@ -38,3 +41,4 @@ How-to guides: security and access
    Manually importing private repositories </guides/importing-private-repositories>
    Using private Git submodules </guides/private-submodules>
    Installing private python packages </guides/private-python-packages>
+   Manage maintainers </guides/managing-maintainers>

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

@@ -1,5 +1,3 @@
-.. TODO: We should documentation how community team management works
-
 How to manage Read the Docs teams
 =================================
 

docs/user/guides/managing-maintainers.rst

@@ -0,0 +1,43 @@
+How to manage maintainers for your project
+==========================================
+
+|org_brand| allows you to manage maintainers for your projects.
+Every project is configured with its own list of maintainers
+who will all have admin privileges to the project,
+so be careful when adding new maintainers.
+
+When you add a maintainer to your project,
+they will be invited to join the project as a maintainer.
+They will receive an email notification with a link to accept the invitation,
+and won't have access to the project until they accept the invitation.
+
+Adding a maintainer
+-------------------
+
+Adding a maintainer gives them admin access to your project.
+
+Follow these steps:
+
+* Navigate to the :guilabel:`Settings` tab of your project.
+* Under :guilabel:`Setup`, click on the :guilabel:`Maintainers` tab.
+* Click the :guilabel:`Add maintainer` button.
+* Fill out the form with the new maintainer's username or email address.
+* Click :guilabel:`Invite`.
+
+Removing a maintainer
+---------------------
+
+Removing a maintainer revokes their admin access to your project.
+
+Follow these steps:
+
+* Navigate to the :guilabel:`Settings` tab of your project.
+* Under :guilabel:`Setup`, click on the :guilabel:`Maintainers` tab.
+* Find the maintainer you want to remove in the list.
+* Click the :guilabel:`Remove` button next to their name.
+* Confirm the removal in the dialog that appears.
+
+.. seealso::
+
+   :doc:`/guides/manage-read-the-docs-teams`
+     Learn how to manage teams within an organization on |com_brand|.

docs/user/index.rst

@@ -10,6 +10,7 @@ Read the Docs: documentation simplified
    /intro/add-project
    /intro/doctools
    /examples
+   /intro/accounts
 
 .. toctree::
    :maxdepth: 2

docs/user/intro/accounts.rst

@@ -0,0 +1,82 @@
+Account authentication methods
+==============================
+
+Read the Docs supports several authentication methods for creating an account and logging in.
+The method you choose depends on your preferences and the security requirements of your organization.
+
+These authentication methods are not mutually exclusive,
+you can use multiple methods to access your account.
+
+Email and password
+------------------
+
+You can create an account on Read the Docs using your email address and a password.
+This method works well for individual users and small teams,
+but it limits the functionality available to you.
+
+VCS provider authentication
+---------------------------
+
+You can also create an account on Read the Docs using a VCS authentication provider: GitHub, GitLab, or Bitbucket.
+This method is more secure and convenient than using an email and password,
+and provides access to additional features like automatic repository syncing.
+
+VCS provider authentication is required for the following features:
+
+* :doc:`/pull-requests`
+* Automatic repository syncing for easy project creation
+* Automatic webhook creation on project creation
+
+.. seealso::
+
+   :doc:`/guides/connecting-git-account`
+     Learn how to connect your Read the Docs account with a Git provider.
+
+Google authentication
+---------------------
+
+.. include:: /shared/admonition-rtd-business.rst
+
+Read the Docs supports Google authentication for organizations.
+Google authentication works well for users already using Google services,
+and easily integrates into your existing workflow.
+
+Google provides authentication, but not authorization.
+This means that you can login to Read the Docs with this method,
+but we aren't able to determine which projects you have access to automatically.
+
+.. seealso::
+
+   :ref:`sso_google_workspace`
+    Learn how to configure Google authentication for your organization.
+
+SAML authentication
+-------------------
+
+.. include:: /shared/admonition-rtd-business.rst
+
+Read the Docs supports SAML authentication for organizations.
+SAML authentication is a secure way to authenticate users and manage access to your organization's projects.
+This is only available on Enterprise plans,
+and requires custom integration to be enabled.
+
+SAML provides authentication, but not authorization.
+This means that users can login to Read the Docs with this method,
+but we aren't able to determine which projects each user has access to automatically.
+
+.. seealso::
+
+   :ref:`sso_saml`
+    Learn how to configure SAML authentication for your organization.
+
+Two-factor authentication
+-------------------------
+
+Read the Docs supports two-factor authentication (2FA) for added security on all authentication methods.
+If you have 2FA enabled on your account, you will be prompted to enter a code
+when logging in.
+
+.. seealso::
+
+    :doc:`/guides/management/2fa`
+      Learn how to enable and disable two-factor authentication on your account.