Documentation for Sigle Sign-On feature on commercial #7212

humitos · 2020-06-22T16:03:11Z

Initial documentation for SSO on Read the Docs for Business.

My goals here are:

mention different types of SSO:
- authentication & authorization (GitHub)
- authentication (verified email address)
make it clear where permissions are managed
- social accounts (GitHub, etc)
- normal Read the Docs auth (Admins teams)
mention that this is still on Beta and enabled by request only
avoid confusions mentioning differences with "regular organizations": users only needs to know how SSO works

Rendered version: https://docs--7212.org.readthedocs.build/en/7212/commercial/single-sign-on.html

ericholscher

This document definitely feels half-finished. I think it shows how confusing this is with the current setup, and we likely need to think more to explain it better. There's a large number of changes I'd suggest, but in general we definitely need to do more work here.

docs/commercial/single-sign-on.rst

humitos · 2020-07-06T13:24:09Z

@eric I did another iteration on this document. I tried to focus on the distinction of the two different types of SSO we currently support: Social Account and @company.com email address. Besides, I made the normal actions (e.g. grant admin access) as sections so it's easier to see and find them.

I think it's too much better than the previous one and makes things clearer. I'd like to have "better making names" for the two different types, but at least, I think it communicates clearly what the differences are. I suppose we can grow from here...

humitos · 2020-07-06T13:34:10Z

Note with this we will have 3 different types of Auth for organizations:

Read the Docs Auth:
- Owners
  - admin of the organization's settings
  - admin of all projects
  - can import projects
- Admins
  - admins of projects under "Admin Team"
  - can import projects
  - every user must have to be invited to the team
- Members
  - read access of projects under "Read Team"
  - every user must have to be invited to the organization
Verified email:
- Owners
  - admin of the organization's settings
  - admin of all the projects
  - can import projects
- Admins
  - admins of projects under "Admin Team"
  - can import projects
  - every user must have to be invited to the team
- Members
  - any user with @company.com verified email
  - read access to all the projects on the organization
  - there is no need to invite/add this users manually to any Team
GitHub:
- Owners
  - admin of the organization's settings
  - no admin of any projects under the organization
- Admins
  - users with admin access in the GitHub repository associated
- Members
  - users with read (or more) permissions in the GitHub repository associated
- There is no concept of teams at all

ericholscher · 2020-07-06T16:13:10Z

@humitos I think #1 and #2 should be exactly the same, except for the membership with email.

humitos · 2020-07-06T19:33:45Z

@ericholscher what do you mean exactly with "membership with email"? What access a user would have after signup with a @company.com email if the organization already have 3 projects imported?

NOTE, I added "can import project" on Verified Email -> Admins, that was missing

humitos · 2020-07-06T19:35:24Z

The main important difference that make this feature useful (between #1 and #2) is that "users with @company.com email will have read access to all the projects of the organization" --the rest is exactly the same.

ericholscher

This is a much better doc, very clear 👍

ericholscher · 2020-07-07T15:59:00Z

docs/commercial/single-sign-on.rst

+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.
+
+Note the users created under Read the Docs must have their GitHub, Bitbucket or GitLab


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?

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

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.

docs/commercial/single-sign-on.rst

ericholscher · 2020-07-07T16:01:15Z

docs/commercial/single-sign-on.rst

+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.


They can only import projects into that team, right?

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

ericholscher · 2020-07-07T16:01:46Z

docs/commercial/single-sign-on.rst

+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 at least **read** permissions in the GitHub, Bitbucket or GitLab repository associated,


This seems wrong, no? We can't set webhooks on these repos, and I think it isn't how it works currently right?

Right. This is a mistake.

Wait... This is confusing.

Currently, without SSO, if the project is public and you have read permissions on it, you can imported it, see

readthedocs.org/readthedocs/projects/static-src/projects/js/import.js

Lines 123 to 128 in eb34b08

self.is_locked = ko.computed(function () {

if (view.has_sso_enabled) {

return !self.admin();

}

return (self.private() && !self.admin());

});

. In that case, you will be able to import the project, but the webhook won't be connected, ssh key not setup and we will show these notifications:

I changed that behavior to only make is_locked = !self.admin() only when SSO is enabled because it doesn't make sense to import a project that you are not able to modify later (GitHub SSO won't give you access to Admin tab if you don't have admin permissions in the GH repo).

Summarizing,

current behavior with RTD Auth, allows you to import public projects with only read permissions

GitHub SSO, allows you to import projects only if you admin on the GH repository

Verified Email, same as RTD Auth

I think, for corporate, it makes sense to always force to be admin on the GH repository to be able to import a project; because the reasons that you mentioned. After imported, you will end up with a half configured project. This would change the current behavior, tho.

I changed this behavior to allow import projects only with admin permissions in the repository for Email SSO and VCS SSO.

I think, we should eventually do the same for RTD Auth and make all behave the same under corporate: "admin permissions on RemoteRepository are required to import a project".

Co-authored-by: Eric Holscher <[email protected]>

…humitos/docs-for-sso

`autosectionlabel` creates a unique label per section. Since we have exactly the same section name multiple times in the same document, Sphinx raises a warning. We could `autosectionlabel_maxdepth=1` to avoid this, but that will make other subsections to stop being labeled and we may be using them. Renaming the section with a very similar title is a quick fix for now. https://www.sphinx-doc.org/es/master/usage/extensions/autosectionlabel.html

ericholscher

We are using VCS, VCS provider, VCS repository and VCS social provider all in this single document. We need to standardize on terms, not introduce even more! I think VCS provider or VCS repository is probably best.

ericholscher · 2020-07-14T00:24:59Z

docs/commercial/organizations.rst

@@ -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)>`


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 :)

humitos · 2020-07-14T10:02:46Z

OK. I finally used "VCS provider" when the document refers to GitHub/GitLab/Bitbucket and "VCS repository" when it refers to a specific repository associated to a Read the Docs' project. I'm not 100% convinced, but seems a little better at least :)

ericholscher · 2020-07-14T15:25:01Z

Looks good 👍

ericholscher · 2020-07-14T15:25:14Z

Excited to have this public 🎉

Documentation for Sigle Sign-On feature on commercial

dc29d57

humitos requested a review from a team June 22, 2020 16:03

ericholscher reviewed Jun 22, 2020

View reviewed changes

docs/commercial/single-sign-on.rst Outdated Show resolved Hide resolved

humitos added 2 commits July 6, 2020 15:20

Note about different behavior of regular Auth when SSO is enabled

741d340

Refactor SSO document to define specific actions

fd23a67

humitos added 3 commits July 6, 2020 15:46

Employee -> User

5f7b386

Typo

7340c5c

Add permissions

5062751

ericholscher approved these changes Jul 7, 2020

View reviewed changes

humitos and others added 7 commits July 7, 2020 18:52

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

6826a5a

Co-authored-by: Eric Holscher <[email protected]>

Admin permissions are required to import a project

43b278e

Merge branch 'master' of github.com:readthedocs/readthedocs.org into …

7d5ca8a

…humitos/docs-for-sso

Small copy/wording changes

ebb30a7

Make reference to work

b8ad6cb

Include document and fix reference

07a08be

ericholscher reviewed Jul 14, 2020

View reviewed changes

humitos added 2 commits July 14, 2020 11:56

Standardize usage of "VCS provider"

edf0066

Use "VCS repository" when talking to the associated repository

87200d0

ericholscher merged commit 0c96ab8 into master Jul 14, 2020

ericholscher deleted the humitos/docs-for-sso branch July 14, 2020 15:25

humitos mentioned this pull request Oct 28, 2020

CI: use circleci #7603

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation for Sigle Sign-On feature on commercial #7212

Documentation for Sigle Sign-On feature on commercial #7212

humitos commented Jun 22, 2020 •

edited

Loading

ericholscher left a comment

humitos commented Jul 6, 2020

humitos commented Jul 6, 2020 •

edited

Loading

ericholscher commented Jul 6, 2020

humitos commented Jul 6, 2020

humitos commented Jul 6, 2020

ericholscher left a comment

ericholscher Jul 7, 2020 •

edited

Loading

humitos Jul 7, 2020

humitos Jul 9, 2020

ericholscher Jul 7, 2020

humitos Jul 7, 2020

ericholscher Jul 7, 2020

humitos Jul 7, 2020

humitos Jul 7, 2020

humitos Jul 9, 2020

ericholscher left a comment •

edited

Loading

ericholscher Jul 14, 2020

humitos commented Jul 14, 2020

ericholscher commented Jul 14, 2020

ericholscher commented Jul 14, 2020

	self.is_locked = ko.computed(function () {
	if (view.has_sso_enabled) {
	return !self.admin();
	}
	return (self.private() && !self.admin());
	});

Documentation for Sigle Sign-On feature on commercial #7212

Documentation for Sigle Sign-On feature on commercial #7212

Conversation

humitos commented Jun 22, 2020 • edited Loading

ericholscher left a comment

Choose a reason for hiding this comment

humitos commented Jul 6, 2020

humitos commented Jul 6, 2020 • edited Loading

ericholscher commented Jul 6, 2020

humitos commented Jul 6, 2020

humitos commented Jul 6, 2020

ericholscher left a comment

Choose a reason for hiding this comment

ericholscher Jul 7, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ericholscher left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

humitos commented Jul 14, 2020

ericholscher commented Jul 14, 2020

ericholscher commented Jul 14, 2020

humitos commented Jun 22, 2020 •

edited

Loading

humitos commented Jul 6, 2020 •

edited

Loading

ericholscher Jul 7, 2020 •

edited

Loading

ericholscher left a comment •

edited

Loading