Merge branch 'docs-clarify-guest-users' into 'master'

Clarify the relationship between external and free guest users

Closes gitlab-com/support/feedback#663 and #32128

See merge request gitlab-org/gitlab!17745

doc/administration/auth/ldap-ee.md

@@ -281,7 +281,7 @@ sync to run once every 2 hours at the top of the hour.
 > Introduced in GitLab Enterprise Edition Starter 8.9.
 
 Using the `external_groups` setting will allow you to mark all users belonging
-to these groups as [external users](../../user/permissions.md#external-users-permissions).
+to these groups as [external users](../../user/permissions.md#external-users-core-only).
 Group membership is checked periodically through the `LdapGroupSync` background
 task.
 

doc/user/permissions.md

@@ -241,58 +241,83 @@ nested groups if you have membership in one of its parents.
 To learn more, read through the documentation on
 [subgroups memberships](group/subgroups/index.md#membership).
 
-## Free Guest users **(ULTIMATE)**
-
-When a user is given `Guest` permissions on a project and/or group, and holds no
-higher permission level on any other project or group on the instance, the user
-is considered a guest user by GitLab and will not consume a license seat.
-There is no other specific "guest" designation for newly created users.
-
-If the user is assigned a higher role on any projects or groups, the user will
-take a license seat. If a user creates a project, the user becomes a `Maintainer`
-on the project, resulting in the use of a license seat.
-
-To prevent a guest user from creating projects, you can edit the user profile to mark the user as
-[External](#external-users-permissions).
-
-## External users permissions
+## External users **(CORE ONLY)**
 
 In cases where it is desired that a user has access only to some internal or
 private projects, there is the option of creating **External Users**. This
 feature may be useful when for example a contractor is working on a given
 project and should only have access to that project.
 
-External users can only access projects to which they are explicitly granted
-access, thus hiding all other internal or private ones from them. Access can be
-granted by adding the user as member to the project or group.
+External users:
+
+- Cannot create groups or projects.
+- Can only access projects to which they are explicitly granted access,
+  thus hiding all other internal or private ones from them (like being
+  logged out).
 
+Access can be granted by adding the user as member to the project or group.
 They will, like usual users, receive a role in the project or group with all
-the abilities that are mentioned in the table above. They cannot however create
-groups or projects, and they have the same access as logged out users in all
-other cases.
+the abilities that are mentioned in the [permissions table above](#project-members-permissions).
+For example, if an external user is added as Guest, and your project is
+private, they will not have access to the code; you would need to grant the external
+user access at the Reporter level or above if you want them to have access to the code. You should
+always take into account the
+[project's visibility and permissions settings](project/settings/index.md#sharing-and-permissions)
+as well as the permission level of the user.
 
-An administrator can flag a user as external [through the API](../api/users.md)
-or by checking the checkbox on the admin panel. As an administrator, navigate
-to **Admin > Users** to create a new user or edit an existing one. There, you
-will find the option to flag the user as external.
+NOTE: **Note:**
+External users still count towards a license seat.
+
+An administrator can flag a user as external by either of the following methods:
 
-By default new users are not set as external users. This behavior can be changed
-by an administrator under **Admin > Application Settings**.
+- Either [through the API](../api/users.md#user-modification).
+- Or by navigating to the **Admin area > Overview > Users** to create a new user
+  or edit an existing one. There, you will find the option to flag the user as
+  external.
 
-### Default internal users
+### Setting new users to external
 
-The "Internal users" field allows specifying an e-mail address regex pattern to identify default internal users.
+By default, new users are not set as external users. This behavior can be changed
+by an administrator under the **Admin Area > Settings > General > Account and limit** page.
 
-New users whose email address matches the regex pattern will be set to internal by default rather than an external collaborator.
+If you change the default behavior of creating new users as external, you will
+have the option to narrow it down by defining a set of internal users.
+The **Internal users** field allows specifying an email address regex pattern to
+identify default internal users. New users whose email address matches the regex
+pattern will be set to internal by default rather than an external collaborator.
 
-The regex pattern format is Ruby, but it needs to be convertible to JavaScript, and the ignore case flag will be set, e.g. "/regex pattern/i".
+The regex pattern format is Ruby, but it needs to be convertible to JavaScript,
+and the ignore case flag will be set (`/regex pattern/i`). Here are some examples:
 
-Here are some examples:
+- Use `\.internal@domain\.com$` to mark email addresses ending with
+  `.internal@domain.com` as internal.
+- Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses
+  NOT including `.ext@domain.com` as internal.
 
-- Use `\.internal@domain\.com$` to mark email addresses ending with ".internal@domain.com" internal.
-- Use `^(?:(?!\.ext@domain\.com).)*$\r?` to mark users with email addresses NOT including .ext@domain.com internal.
+CAUTION: **Warning:**
+Be aware that this regex could lead to a
+[regular expression denial of service (ReDoS) attack](https://en.wikipedia.org/wiki/ReDoS).
+
+## Free Guest users **(ULTIMATE)**
 
-Please be aware that this regex could lead to a DOS attack, [see](https://en.wikipedia.org/wiki/ReDoS?) ReDos on Wikipedia.
+When a user is given Guest permissions on a project, group, or both, and holds no
+higher permission level on any other project or group on the GitLab instance,
+the user is considered a guest user by GitLab and will not consume a license seat.
+There is no other specific "guest" designation for newly created users.
+
+If the user is assigned a higher role on any projects or groups, the user will
+take a license seat. If a user creates a project, the user becomes a Maintainer
+on the project, resulting in the use of a license seat. Also, note that if your
+project is internal or private, Guest users will have all the abilities that are
+mentioned in the [permissions table above](#project-members-permissions) (they
+will not be able to browse the project's repository for example).
+
+TIP: **Tip:**
+To prevent a guest user from creating projects, as an admin, you can edit the
+user's profile to mark the user as [external](#external-users-core-only).
+Beware though that even if a user is external, if they already have Reporter or
+higher permissions in any project or group, they will **not** be counted as a
+free guest user.
 
 ## Auditor users **(PREMIUM ONLY)**
 

doc/user/project/new_ci_build_permissions_model.md

@@ -47,7 +47,7 @@ It is important to note that we have a few types of users:
   Administrator will have to be a member of it in order to have access to it
   via another project's job.
 
-- **External users**: CI jobs created by [external users](../permissions.md#external-users-permissions) will have
+- **External users**: CI jobs created by [external users](../permissions.md#external-users-core-only) will have
   access only to projects to which user has at least reporter access. This
   rules out accessing all internal projects by default.
 
@@ -58,7 +58,7 @@ Let's consider the following scenario:
    hosted in private repositories and you have multiple CI jobs that make use
    of these repositories.
 
-1. You invite a new [external user](../permissions.md#external-users-permissions). CI jobs created by that user do not
+1. You invite a new [external user](../permissions.md#external-users-core-only). CI jobs created by that user do not
    have access to internal repositories, because the user also doesn't have the
    access from within GitLab. You as an employee have to grant explicit access
    for this user. This allows us to prevent from accidental data leakage.