Docs: basic docs for SAML SSO

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

@@ -44,6 +44,21 @@ 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 with SAML
+-------------
+
+.. note::
+
+   This feature is in beta, and will be available for **Enterprise** plans only.
+   Contact :doc:`support </support>` to enable this feature for your organization.
+
+   **At the moment only Okta is supported as a SAML identity provider.**
+
+This feature allows you to easily manage access to users that are part of your identity provider.
+As SAML doesn't provide information about which projects a user has access to,
+permissions are managed by the :ref:`internal Read the Docs's teams <commercial/organizations:Team Types>` authorization system.
+Learn how to configure this SSO method with our :doc:`guide </guides/set-up-single-sign-on-saml>`.
+
 Requesting additional providers
 -------------------------------
 

docs/user/guides/access/index.rst

@@ -33,6 +33,7 @@ How-to guides: security and access
 
    Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>
    Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>
+   Single Sign-On (SSO) with SAML </guides/set-up-single-sign-on-saml>
    Managing Read the Docs teams </guides/manage-read-the-docs-teams>
    Manually importing private repositories </guides/importing-private-repositories>
    Using private Git submodules </guides/private-submodules>

docs/user/guides/set-up-single-sign-on-saml.rst

@@ -0,0 +1,125 @@
+How to set up Single Sign-On (SSO) with SAML
+============================================
+
+.. include:: /shared/admonition-rtd-business.rst
+
+.. note::
+
+   This feature is in beta, and will be available for **Enterprise** plans only.
+   Contact :doc:`support </support>` to enable this feature for your organization.
+
+   **At the moment only Okta is supported as a SAML identity provider.**
+
+This how-to guide will provide instructions on how to enable :abbr:`SSO (Single Sign-on)` using Okta as a SAML identity provider.
+If you want more information on this feature, please read :doc:`/commercial/single-sign-on`
+
+Prerequisites
+-------------
+
+.. include:: /shared/organization-permissions.rst
+
+Create a new SAML application in Okta
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to enable SSO with Okta, you need to create a new SAML application in your Okta account.
+
+1. Log in to your Okta account.
+2. Click on :guilabel:`Applications`.
+3. Click on :guilabel:`Create App Integration`.
+4. Choose :guilabel:`SAML 2.0`, and click :guilabel:`Next`.
+5. Fill in the following fields with the information from `your SAML integration <https://readthedocs.com/organizations/choose/organization_saml/>`__:
+
+   * :guilabel:`App name`: Read the Docs
+   * :guilabel:`App logo`: Optionally you can use the `Read the Docs logo <https://brand-guidelines.readthedocs.org/_images/logo-wordmark-vertical-compact-dark.png>`__.
+   * :guilabel:`App visibility`: (optional)
+   * :guilabel:`Single Sign On URL`: ``https://readthedocs.com/accounts/saml/<organization-slug>/acs/`` (replace ``<organization-slug>`` with your organization slug)
+   * :guilabel:`Audience URI (SP Entity ID)`: ``https://readthedocs.com/accounts/saml/<organization-slug>/metadata/`` (replace ``<organization-slug>`` with your organization slug)
+   * :guilabel:`Name ID format`: ``EmailAddress``
+   * Leave the rest of the fields as default.
+
+6. Add the following "attribute statements" to be used when creating a new user:
+
+   .. csv-table::
+      :header: "Name", "Format", "Value"
+
+      "user.id", "Basic", "user.id"
+      "user.firstName", "Basic", "user.firstName"
+      "user.lastName", "Basic", "user.lastName"
+
+7. Click :guilabel:`Next`.
+8. Select ``This is an internal app that we have created``.
+9. Click :guilabel:`Finish`.
+
+User setup
+~~~~~~~~~~
+
+Using this setup, all users who have access to the configured Okta application will automatically join to your organization when they sign up.
+Existing users will not be automatically joined to the organization.
+
+You can still add outside collaborators and manage their access.
+There are two ways to manage this access:
+
+* Using :doc:`teams </guides/manage-read-the-docs-teams>` to provide access for ongoing contribution.
+* Using :doc:`sharing </commercial/sharing>` to provide short-term access requiring a login.
+
+Enabling SSO
+------------
+
+Enabling SSO is currently done by the Read the Docs team,
+contact :doc:`support </support>` to enable this feature for your organization.
+
+By default, users that sign up with SAML do not have any permissions over any project.
+However, you can define which teams users will auto-join when they sign up.
+
+After enabling the SAML integration,
+all users with email addresses from your configured domain will be required to signup using SAML.
+
+.. warning::
+
+   Existing users with email addresses from your configured domain will not be required to sign up using SAML,
+   but they won't be automatically joined to your organization.
+
+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:
+
+1. Navigate to the `teams management page <https://readthedocs.com/organizations/choose/organization_team_list/>`__.
+2. Click the :guilabel:`<team name>`.
+3. Click :guilabel:`Edit team`
+4. Enable *Auto join users with an organization's email address to this team*.
+5. Click :guilabel:`Save`
+
+With this enabled,
+all users that sign up with SAML 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 access to the SAML integration to a user,
+you revoke access to all the projects the linked Read the Docs user had access to,
+and disable login on Read the Docs completely for that user.
+
+.. warning::
+
+   If the user signed up to Read the Docs previously to enabling SAML on your organization,
+   they may still have access to their account and projects if they were manually added to a team.
+
+   To completely revoke access to a user, remove them from all the teams they are part of.
+
+.. warning::
+
+   If the user was already signed in to Read the Docs when their access was revoked,
+   they may still have access to documentation pages until their session expires.
+   This is three days for the dashboard and documentation pages.
+
+   To completely revoke access to a user, remove them from all the teams they are part of.
+
+.. seealso::
+
+   :doc:`/guides/manage-read-the-docs-teams`
+     Additional user management options
+   :doc:`/commercial/single-sign-on`
+     Information about choosing a Single Sign-on approach