Skip to content

Documentation for Sigle Sign-On feature on commercial #7212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 15 commits into from
Jul 14, 2020
Merged

Documentation for Sigle Sign-On feature on commercial #7212

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
dc29d57
Documentation for Sigle Sign-On feature on commercial
humitos Jun 22, 2020
741d340
Note about different behavior of regular Auth when SSO is enabled
humitos Jul 6, 2020
fd23a67
Refactor SSO document to define specific actions
humitos Jul 6, 2020
5f7b386
Employee -> User
humitos Jul 6, 2020
7340c5c
Typo
humitos Jul 6, 2020
5062751
Add permissions
humitos Jul 6, 2020
6826a5a
Update docs/commercial/single-sign-on.rst
humitos Jul 7, 2020
43b278e
Admin permissions are required to import a project
humitos Jul 7, 2020
7d5ca8a
Merge branch 'master' of github.com:readthedocs/readthedocs.org into …
humitos Jul 9, 2020
ebb30a7
Small copy/wording changes
humitos Jul 9, 2020
b8ad6cb
Make reference to work
humitos Jul 9, 2020
07a08be
Include document and fix reference
humitos Jul 9, 2020
4b290fe
Rename section titles because autosectionlabel Sphinx extension
humitos Jul 9, 2020
edf0066
Standardize usage of "VCS provider"
humitos Jul 14, 2020
87200d0
Use "VCS repository" when talking to the associated repository
humitos Jul 14, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/commercial/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
2 changes: 1 addition & 1 deletion docs/commercial/organizations.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ The best way to think about this relationship is:
.. warning::

Owners, Members and Teams behave differently if you are using
:ref:`SSO with GitHub, Bitbucket or GitLab <SSO with GitHub, Bitbucket or GitLab>`.
:ref:`SSO with VCS social provider (GitHub, Bitbucket or GitLab) <commercial/single-sign-on:SSO with VCS social provider (GitHub, Bitbucket or GitLab)>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

VCS social provider feels even more verbose and isn't a term I've ever heard before, and we're still including the full set of 3. I'm not convinced this is better :)


Team Types
~~~~~~~~~~
Expand Down
38 changes: 19 additions & 19 deletions docs/commercial/single-sign-on.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,24 +16,24 @@ Currently, we support two different types of Single Sign-On:

.. note::

SSO is currently in **Beta** and only GitHub is supported for now.
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 GitHub, Bitbucket or GitLab
------------------------------------
SSO with VCS social 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 GitHub, Bitbucket or GitLab repository associated with it.
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
Copy link
Member

@ericholscher ericholscher Jul 7, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think GitHub, Bitbucket or GitLab is a bit verbose, we should probably just say VCS provider or something, and explain that above:

GitHub, Bitbucket or GitLab ("VCS provider")

Maybe it's better to be explicit here though?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's fine using "VCS provider" as a general concept here I think. We use "VCS account" already in other documents, https://docs.readthedocs.io/en/stable/connected-accounts.html. Probably better to stick with that term.

I think it makes sense to mention them explicitly at the beginning maybe and use the general term in the rest of the document. It's good to avoid confusions with projects imported from outside these three providers. However, they have to be imported manually which is not discoverable in .com

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made some small changes for this. I left it explicit where I thought it makes sense to make it explicit and used "VCS social provider" or "VCS provider" as well.

account connected in order to make SSO to work.
:doc:`account connected </connected-accounts>` in order to make SSO to work.

.. note::

Expand All @@ -45,46 +45,46 @@ account connected in order to make SSO to work.
Grant access to read the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

By granting **read** (or more) permissions to a user under GitHub, Bitbucket or GitLab
By granting **read** (or more) permissions to a user under VCS provider
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 under GitHub, Bitbucket or GitLab
By granting **write** permission to a user under VCS provider
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 GitHub, Bitbucket or GitLab is enabled in the organization only owners can import projects on the organization.
When SSO with VCS social 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 GitHub, Bitbucket or GitLab repository associated.
Note that to be able to import a project, that user must have **admin** permissions in the VCS provider repository associated.


SSO with a ``@company.com`` email address
-----------------------------------------
SSO with your company email address
-----------------------------------

Using a ``@company.com`` email address allows you to
Using your company's email address (e.g. ``employee@company.com``) 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 administrate a project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 :guilabel:`Teams` > :guilabel:`Admins` > :guilabel:`Invite Member`.
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 import a project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They can only import projects into that team, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. In fact, if you are an admin, you can only import projects under the Admins teams you belong to. You cannot import projects on "Read" teams, even if you belong to --which is a bug, I'd say. See https://github.com/readthedocs/readthedocs-corporate/issues/929

I'm not sure if this has to be clarified here, since it's not related to SSO. It probably fits better on https://docs.readthedocs.io/en/stable/commercial/organizations.html


Note that to be able to import a project, that user must have at least **read** permissions in the GitHub, Bitbucket or GitLab repository associated,
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.