Skip to content

Commit 58c74f0

Browse files
stsewdhumitos
stsewd
and
humitos
authored
Docs: basic docs for SAML SSO (#11288)
* Docs: basic docs for SAML SSO We still need to figure out a couple of things, but I think it doesn't hurt to have some basic docs about this feature. Ref #11262 * Use a table instead * Make attributes required * Updates from review --------- Co-authored-by: Manuel Kaufmann <[email protected]>
1 parent 6d6ec71 commit 58c74f0

File tree

3 files changed

+141
-0
lines changed

3 files changed

+141
-0
lines changed

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

+15
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,21 @@ permissions are managed by the :ref:`internal Read the Docs's teams <commercial/
4444
This feature is only available on the **Pro plan** and above.
4545
Learn how to configure this SSO method with our :doc:`/guides/setup-single-sign-on-google-email`.
4646

47+
SSO with SAML
48+
-------------
49+
50+
.. note::
51+
52+
This feature is in beta, and will be available for **Enterprise** plans only.
53+
Contact :doc:`support </support>` to enable this feature for your organization.
54+
55+
**At the moment only Okta is supported as a SAML identity provider.**
56+
57+
This feature allows you to easily manage access to users that are part of your identity provider.
58+
As SAML doesn't provide information about which projects a user has access to,
59+
permissions are managed by the :ref:`internal Read the Docs's teams <commercial/organizations:Team Types>` authorization system.
60+
Learn how to configure this SSO method with our :doc:`guide </guides/set-up-single-sign-on-saml>`.
61+
4762
Requesting additional providers
4863
-------------------------------
4964

‎docs/user/guides/access/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ How-to guides: security and access
3333

3434
Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>
3535
Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>
36+
Single Sign-On (SSO) with SAML </guides/set-up-single-sign-on-saml>
3637
Managing Read the Docs teams </guides/manage-read-the-docs-teams>
3738
Manually importing private repositories </guides/importing-private-repositories>
3839
Using private Git submodules </guides/private-submodules>

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

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
How to set up Single Sign-On (SSO) with SAML
2+
============================================
3+
4+
.. include:: /shared/admonition-rtd-business.rst
5+
6+
.. note::
7+
8+
This feature is in beta, and will be available for **Enterprise** plans only.
9+
Contact :doc:`support </support>` to enable this feature for your organization.
10+
11+
**At the moment only Okta is supported as a SAML identity provider.**
12+
13+
This how-to guide will provide instructions on how to enable :abbr:`SSO (Single Sign-on)` using Okta as a SAML identity provider.
14+
If you want more information on this feature, please read :doc:`/commercial/single-sign-on`
15+
16+
Prerequisites
17+
-------------
18+
19+
.. include:: /shared/organization-permissions.rst
20+
21+
Create a new SAML application in Okta
22+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
23+
24+
In order to enable SSO with Okta, you need to create a new SAML application in your Okta account.
25+
26+
1. Log in to your Okta account.
27+
2. Click on :guilabel:`Applications`.
28+
3. Click on :guilabel:`Create App Integration`.
29+
4. Choose :guilabel:`SAML 2.0`, and click :guilabel:`Next`.
30+
5. Fill in the following fields with the information from `your SAML integration <https://readthedocs.com/organizations/choose/organization_saml/>`__:
31+
32+
* :guilabel:`App name`: Read the Docs
33+
* :guilabel:`App logo`: Optionally you can use the `Read the Docs logo <https://brand-guidelines.readthedocs.org/_images/logo-wordmark-vertical-compact-dark.png>`__.
34+
* :guilabel:`App visibility`: (optional)
35+
* :guilabel:`Single Sign On URL`: ``https://readthedocs.com/accounts/saml/<organization-slug>/acs/`` (replace ``<organization-slug>`` with your organization slug)
36+
* :guilabel:`Audience URI (SP Entity ID)`: ``https://readthedocs.com/accounts/saml/<organization-slug>/metadata/`` (replace ``<organization-slug>`` with your organization slug)
37+
* :guilabel:`Name ID format`: ``EmailAddress``
38+
* Leave the rest of the fields as default.
39+
40+
6. Add the following "attribute statements" to be used when creating a new user:
41+
42+
.. csv-table::
43+
:header: "Name", "Format", "Value"
44+
45+
"user.id", "Basic", "user.id"
46+
"user.firstName", "Basic", "user.firstName"
47+
"user.lastName", "Basic", "user.lastName"
48+
49+
7. Click :guilabel:`Next`.
50+
8. Select ``This is an internal app that we have created``.
51+
9. Click :guilabel:`Finish`.
52+
53+
User setup
54+
~~~~~~~~~~
55+
56+
Using this setup, all users who have access to the configured Okta application will automatically join to your Read the Docs organization when they sign up.
57+
Existing users will not be automatically joined to the organization.
58+
59+
You can still add outside collaborators and manage their access.
60+
There are two ways to manage this access:
61+
62+
* Using :doc:`teams </guides/manage-read-the-docs-teams>` to provide access for ongoing contribution.
63+
* Using :doc:`sharing </commercial/sharing>` to provide short-term access requiring a login.
64+
65+
Enabling SSO
66+
------------
67+
68+
Enabling SSO is currently done by the Read the Docs team,
69+
contact :doc:`support </support>` to enable this feature for your organization.
70+
71+
By default, users that sign up with SAML do not have any permissions over any project.
72+
However, you can define which teams users will auto-join when they sign up.
73+
74+
After enabling the SAML integration,
75+
all users with email addresses from your configured domain will be required to signup using SAML.
76+
77+
.. warning::
78+
79+
Existing users with email addresses from your configured domain will not be required to sign up using SAML,
80+
but they won't be automatically joined to your organization.
81+
82+
Configure team for all users to join
83+
------------------------------------
84+
85+
You can mark one or more teams that users will automatically join when they sign up with a matching email address.
86+
Configure this option by:
87+
88+
1. Navigate to the `teams management page <https://readthedocs.com/organizations/choose/organization_team_list/>`__.
89+
2. Click the :guilabel:`<team name>`.
90+
3. Click :guilabel:`Edit team`
91+
4. Enable *Auto join users with an organization's email address to this team*.
92+
5. Click :guilabel:`Save`
93+
94+
With this enabled,
95+
all users that sign up with SAML will automatically join this team.
96+
These teams can have either *read-only* or *admin* permissions over a set of projects.
97+
98+
Revoke user's access to all the projects
99+
----------------------------------------
100+
101+
By disabling access to the SAML integration to a user,
102+
you revoke access to all the projects the linked Read the Docs user had access to,
103+
and disable login on Read the Docs completely for that user.
104+
105+
.. warning::
106+
107+
If the user signed up to Read the Docs previously to enabling SAML on your organization,
108+
they may still have access to their account and projects if they were manually added to a team.
109+
110+
To completely revoke access to a user, remove them from all the teams they are part of.
111+
112+
.. warning::
113+
114+
If the user was already signed in to Read the Docs when their access was revoked,
115+
they may still have access to documentation pages until their session expires.
116+
This is three days for the dashboard and documentation pages.
117+
118+
To completely revoke access to a user, remove them from all the teams they are part of.
119+
120+
.. seealso::
121+
122+
:doc:`/guides/manage-read-the-docs-teams`
123+
Additional user management options
124+
:doc:`/commercial/single-sign-on`
125+
Information about choosing a Single Sign-on approach

0 commit comments

Comments
 (0)