Merge pull request #7212 from readthedocs/humitos/docs-for-sso

Documentation for Sigle Sign-On feature on commercial

Author: ericholscher

docs/commercial/index.rst

@@ -29,9 +29,10 @@ Advertising-free
 .. _readthedocs.org: https://readthedocs.org
 .. _readthedocs.com: https://readthedocs.com
 
-.. toctree:: 
+.. toctree::
    :caption: Additional commercial features
 
    organizations
+   single-sign-on
    sharing
    analytics

docs/commercial/organizations.rst

@@ -22,6 +22,11 @@ The best way to think about this relationship is:
 
 *Owners* will create *Teams* to assign permissions to all *Members*.
 
+.. warning::
+
+   Owners, Members and Teams behave differently if you are using
+   :ref:`SSO with VCS provider (GitHub, Bitbucket or GitLab) <commercial/single-sign-on:SSO with VCS provider (GitHub, Bitbucket or GitLab)>`
+
 Team Types
 ~~~~~~~~~~
 
@@ -44,4 +49,3 @@ Roadrunner would set up a *Team* called *Contractors*.
 That team would have *Read Only* access to the *Road Builder* project.
 Then he would add *Wile E. Coyote* to the team.
 This would give him access to just this one project inside the organization.
-

docs/commercial/single-sign-on.rst

@@ -0,0 +1,90 @@
+Single Sign-On
+==============
+
+.. note::
+
+   This feature only exists on `Read the Docs for Business <https://readthedocs.com/>`__.
+
+
+Single Sign-On is supported on |com_brand| for Pro and Enterprise plans.
+: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 is managed by the Identity Provider (e.g. a ``@company.com`` verified email address)
+
+.. note::
+
+   SSO is currently in **Beta** and only GitHub and Company Email are supported for now.
+   If you would like to apply for the Beta, please `contact us <mailto:[email protected]>`_.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+SSO with VCS provider (GitHub, Bitbucket or GitLab)
+---------------------------------------------------
+
+Using an Identity Provider that supports authentication and authorization allows you to manage
+"who have access to what projects on Read the Docs" directly from the provider itself.
+In case you want a user to have access to your documentation project under Read the Docs,
+that user just needs to be granted permissions in the VCS repository associated with it.
+
+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 to work.
+
+.. note::
+
+   You can read more about `granting permissions on GitHub`_.
+
+   .. _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 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.
+
+
+SSO with your company email address
+-----------------------------------
+
+Using your company's email address (e.g. ``[email protected]``) allows you to
+"grant **read** access to all the projects under your organization to users with a ``@company.com`` verified email address".
+
+
+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 detail's 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.