[doc] Changing docs for repository permissions (sourcegraph#48039)

## TODO

- ❌  ~~Add an FAQ~~ I think we can add FAQ as a followup improvement
- [x] Add an example to how long it takes for permissions to take effect
(what I call lag-time in the docs).
- [x] Render math formulas nicely

## Old docs
[Link to the current docs
page](https://docs.sourcegraph.com/admin/repo/permissions)


## New docs

[Link to the docs page with code from this
branch](https://docs.sourcegraph.com/@milan_docs_permissions/admin/permissions)

## Test plan

Docs changes only, so eyeballing is the only method I did 🤷 

## Disclaimer

I need to move on to other tasks. So if you find big issues or room for
improvement that cannot be fixed in ~20 minutes, we can create followup
PRs later, if there's time before the code freeze.

Author: kopancek

doc/admin/auth/index.md

@@ -1,8 +1,7 @@
-# User authentication (SSO)
+# User authentication
 
 Sourcegraph supports the following ways for users to sign in:
 
-- [Guidance](#guidance)
 - [Builtin password authentication](#builtin-password-authentication)
 - [GitHub](#github)
 - [GitLab](#gitlab)
@@ -18,7 +17,7 @@ Sourcegraph supports the following ways for users to sign in:
 
 The authentication provider is configured in the [`auth.providers`](../config/site_config.md#authentication-providers) site configuration option.
 
-## Guidance
+## Recommendations
 
 If you are unsure which auth provider is right for you, we recommend applying the following rules in
 order:
@@ -331,7 +330,7 @@ Sourcegraph instance:
 - Callback URL: `https://sourcegraph.example.com/.auth/bitbucketcloud/callback`
 - Permissions: 
   - `Account`: `Read`
-  - `Repositories`: `Read` (if [permissions syncing](../repo/permissions.md) is desired)
+  - `Repositories`: `Read` (more information in [repository permissions section](../permissions/index.md))
 
 After the consumer is created, you will need the `Key` and the `Secret`, which can be found by expanding OAuth consumer in the list.
 Then add the following lines to your [site configuration](config/site_config.md):
@@ -512,7 +511,7 @@ Let's say the email field in your Sourcegraph account was kept blank when a site
 Exceptions to this rule are [HTTP Proxies](#http-authentication-proxies), where there's an option to make the link via username only.
 For [Bitbucket](../config/authorization_and_authentication.md#bitbucket-server-bitbucket-data-center-authorization), we don't support OAuth. Still, the match between the chosen auth provider used with Bitbucket and a user's Bitbucket account happens via username.
 
-Using only a username to match a Sourcegraph account to an auth provider account is not recommended, as you can see [here](../repo/permissions.md#username), for example.
+Using only a username to match a Sourcegraph account to an auth provider account is not recommended, as you can see [here](../external_service/gitlab.md#username), for example.
 Usernames in Sourcegraph are mutable, so a malicious user could change a username, elevating their privileges.
 
 ## Linking accounts from multiple auth providers

doc/admin/config/authorization_and_authentication.md

@@ -1,4 +1,4 @@
-# Authentication and authorization in Sourcegraph
+# Authentication and authorization
 
 Sourcegraph has two authentication concepts:
 
@@ -7,7 +7,7 @@ Sourcegraph has two authentication concepts:
 
 We suggest configuring both when using Sourcegraph Enterprise. If you do not configure permissions, all users will be able to see all of the code in the instance.
 
-## Authentication in Sourcegraph
+## Authentication
 
 Sourcegraph supports username/password auth by default and SAML, OAuth, HTTP Proxy auth, and OpenID Connect if configured. Changing a username in Sourcegraph will allow the user to escalate permissions, so if you are syncing permissions, you will need to add the following to your site config at `https://sourcegraph.yourdomain.com/siteadmin/configuration` ([Learn more about viewing and editing your site configuration.](./site_config.md#view-and-edit-site-configuration))
 
@@ -68,7 +68,7 @@ In this way, access to Sourcegraph will still be managed by your identity provid
 
 Follow these steps to [configure authentication with GitHub via OAuth](../auth/index.md#github). 
 
-Once authentication with GitHub via OAuth is configured, follow [these steps to configure access permissions](../repo/permissions.md#github). Users will log into Sourcegraph using Github OAuth, and permissions will be synced in the background.
+Once authentication with GitHub via OAuth is configured, follow [these steps to configure access permissions](../external_service/github.md#repository-permissions). Users will log into Sourcegraph using Github OAuth, and permissions will be synced in the background.
 
 ### GitLab Enterprise or GitLab Cloud authentication and authorization
 
@@ -79,13 +79,13 @@ We support both authentication and permissions syncing (through OAuth) for GitLa
 1. Use SAML (or another auth mechanism) to log in to GitLab
 2. Use GitLab OAuth to log in to Sourcegraph
 
-In this way, access to Sourcegraph will still be managed by your identity provider, using the code host as a middle step. This option is the simplest to configure. To do so, [set up GitLab as an authentication option](../auth/index.md#gitlab), and then [enable permissions syncing](../repo/permissions.md#oauth-application).
+In this way, access to Sourcegraph will still be managed by your identity provider, using the code host as a middle step. This option is the simplest to configure. To do so, [set up GitLab as an authentication option](../auth/index.md#gitlab), and then [enable permissions syncing](../external_service/gitlab.md#oauth-application).
 
 #### Option 2
 
 Alternatively, you can configure SAML authentication in Sourcegraph, and use GitLab permissions syncing in the background to control access permissions. To implement this method, you will need to make sure that GitLab is able to return a value in `identities.provider` for the `GET /users` endpoint ([GitLab documentation](https://docs.gitlab.com/ee/api/users.html#for-admins)) that your identity provider is able to pass as the `nameID` in the SAML response. If that isn’t possible, you will need to use the first option. 
 
-To configure SAML auth with GitLab permissions, you will need to first [configure permissions from GitLab](../repo/permissions.md#administrator-sudo-level-access-token). Then, [configure SAML authentication](../auth/saml/index.md). The `nameID` passed by the identity provider will need to match the value of `identities.provider`. 
+To configure SAML auth with GitLab permissions, you will need to first [configure permissions from GitLab](../external_service/gitlab.md#administrator-sudo-level-access-token). Then, [configure SAML authentication](../auth/saml/index.md). The `nameID` passed by the identity provider will need to match the value of `identities.provider`. 
 
 For example, if the GitLab API returns:
 
@@ -118,15 +118,15 @@ And configure the identity provider to pass the email address as the `nameID`.
 
 We do not currently support OAuth for Bitbucket Server or Bitbucket Data Center. You will need to combine permissions syncing from Bitbucket Server / Bitbucket Data Center with another authentication mechanism (SAML, built-in auth, HTTP authentication proxies). Bitbucket Server and Bitbucket Data Center only pass usernames to Sourcegraph, so you’ll need to make sure that those usernames are matched by whatever mechanism you choose to use for access.
 
-Follow the steps to [sync Bitbucket Server / Bitbucket Data Center permissions](../repo/permissions.md#bitbucket-server). Then, do one of the following:
+Follow the steps to [sync Bitbucket Server / Bitbucket Data Center permissions](../external_service/bitbucket_server.md#repository-permissions). Then, do one of the following:
 
 1. Create the user accounts in Sourcegraph with matching usernames. (Access using `builtin` auth.)
 2. [Configure SAML authentication](../auth/saml/index.md). If you are using Bitbucket Server / Bitbucket Data Center, the `login` attribute is *not* optional. You need to pass the Bitbucket Server username as the `login` attribute. 
 3. [Configure an HTTP authentication proxy](../auth/index.md#http-authentication-proxies), passing the Bitbucket Server username value as the `usernameHeader`. 
 
 ### Explicit Permissions API authorization
 
-With any authentication mechanism, you can use our GraphQL API to set permissions for all repositories. If you choose to do this, this is the *only* mechanism that can be used for permissions—all others will be ignored. Follow the instructions for the [mutations needed within the GraphQL API](../repo/permissions.md#explicit-permissions-api) to configure access.
+With any authentication mechanism, you can use our GraphQL API to set permissions for all repositories. If you choose to do this, this is the *only* mechanism that can be used for permissions—all others will be ignored. Follow the instructions for the [mutations needed within the GraphQL API](../permissions/api.md) to configure access.
 
 ### OpenID Connect authentication
 

doc/admin/config/webhooks.md

@@ -73,7 +73,7 @@ Done! Sourcegraph will now receive webhook events from GitHub and use them to sy
 
 Follow the same steps as above, but ensure you include the `push` event under **Let me select individual events**
 
-#### User permissions
+#### Repository permissions
 
 Follow the same steps as above, but ensure you include the following events under **Let me select individual events**:
 - `Collaborator add, remove, or changed`

doc/admin/deploy/migrate-backup.md

@@ -34,7 +34,7 @@ This list is not guaranteed to be complete, but rather representative of the typ
 |---|---|---|
 |Repository metadata (e.g. clone URLs, whether it is a fork or archive, etc.)|Yes||
 |User accounts|Yes (if using [SSO authentication](../auth/index.md)), No if using builtin authentication||
-|[Repository permissions](../repo/permissions.md)|Yes||
+|[Repository permissions](../permissions/index.md)|Yes||
 |[Organizations](../organizations.md)|No||
 |[User and org settings](../config/settings.md)|No|Global settings can be backed up as described above, but user- and org-level settings cannot.|
 |[Saved searches](../../code_search/how-to/saved_searches.md)|No||

doc/admin/external_service/bitbucket_cloud.md

@@ -38,6 +38,25 @@ If enabled, the default rate is set at 7200 per hour (2 per second), which can b
 To configure Bitbucket Cloud as an authentication provider (which will enable sign-in via Bitbucket Cloud), see the
 [authentication documentation](../auth/index.md#bitbucket-cloud).
 
+## Repository permissions
+
+Prerequisite: [Add Bitbucket Cloud as an authentication provider](#user-authentication).
+
+Then, add or edit a Bitbucket Cloud connection as described above and include the `authorization` field:
+
+```json
+{
+  // The URL used to set up the Bitbucket Cloud authentication provider must match this URL.
+  "url": "https://bitbucket.com",
+  "username": "horsten",
+  "appPassword": "$APP_PASSWORD",
+  // ...
+  "authorization": {}
+}
+```
+
+> NOTE: It can take some time to complete full cycle of repository permissions sync if you have a large number of users or repositories. [See sync duration time](../permissions/syncing.md#sync-duration) for more information.
+
 ## Configuration
 
 Bitbucket Cloud connections support the following configuration options, which are specified in the JSON editor in the site admin "Manage code hosts" area.

doc/admin/external_service/bitbucket_server.md

@@ -38,14 +38,77 @@ Please consult [this page](../config/webhooks.md) in order to configure webhooks
 
 ## Repository permissions
 
-By default, all Sourcegraph users can view all repositories. To configure Sourcegraph to use Bitbucket Server / Bitbucket Data Center's repository permissions, see [Repository permissions](../repo/permissions.md#bitbucket_server).
+Enforcing Bitbucket Server / Bitbucket Data Center permissions can be configured via the `authorization` setting in its configuration.
+
+> NOTE: It can take some time to complete full cycle of repository permissions sync if you have a large number of users or repositories. [See sync duration time](../permissions/syncing.md#sync-duration) for more information.
+
+### Prerequisites
+
+1. You have the exact same user accounts, **with matching usernames**, in Sourcegraph and Bitbucket Server / Bitbucket Data Center. This can be accomplished by configuring an [external authentication provider](../auth/index.md) that mirrors user accounts from a central directory like LDAP or Active Directory. The same should be done on Bitbucket Server / Bitbucket Data Center with [external user directories](https://confluence.atlassian.com/bitbucketserver/external-user-directories-776640394.html).
+1. Ensure you have set `auth.enableUsernameChanges` to **`false`** in the [site config](../config/site_config.md) to prevent users from changing their usernames and **escalating their privileges**.
+
+
+### Setup
+
+This section walks you through the process of setting up an *Application Link between Sourcegraph and Bitbucket Server / Bitbucket Data Center* and configuring the Sourcegraph Bitbucket Server / Bitbucket Data Center configuration with `authorization` settings. It assumes the above prerequisites are met.
+
+As an admin user, go to the "Application Links" page. You can use the sidebar navigation in the admin dashboard, or go directly to [https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks](https://bitbucketserver.example.com/plugins/servlet/applinks/listApplicationLinks).
+
+<img src="https://imgur.com/Hg4bzOf.png" width="800">
+
+Write Sourcegraph's external URL in the text area (e.g. `https://sourcegraph.example.com`) and click **Create new link**. Click **Continue** even if Bitbucket Server / Bitbucket Data Center warns you about the given URL not responding.
+
+<img src="https://imgur.com/x6vFKIL.png" width="800">
+
+Write `Sourcegraph` as the *Application Name* and select `Generic Application` as the *Application Type*. Leave everything else unset and click **Continue**.
+
+<img src="https://imgur.com/161rbB9.png" width="800">
+
+Now click the edit button in the `Sourcegraph` Application Link that you just created and select the `Incoming Authentication` panel.
+
+<img src="https://imgur.com/sMGmzhH.png" width="800">
+
+Generate a *Consumer Key* in your terminal with `echo sourcegraph$(openssl rand -hex 16)`. Copy this command's output and paste it in the *Consumer Key* field. Write `Sourcegraph` in the *Consumer Name* field.
+
+<img src="https://imgur.com/1kK2Y5x.png" width="800">
+
+Generate an RSA key pair in your terminal with `openssl genrsa -out sourcegraph.pem 4096 && openssl rsa -in sourcegraph.pem -pubout > sourcegraph.pub`. Copy the contents of `sourcegraph.pub` and paste them in the *Public Key* field.
+
+<img src="https://imgur.com/YHm1uSr.png" width="800">
+
+Scroll to the bottom and check the *Allow 2-Legged OAuth* checkbox, then write your admin account's username in the *Execute as* field and, lastly, check the *Allow user impersonation through 2-Legged OAuth* checkbox. Press **Save**.
+
+<img src="https://imgur.com/1qxEAye.png" width="800">
+
+Go to your Sourcegraph's *Manage code hosts* page (i.e. `https://sourcegraph.example.com/site-admin/external-services`) and either edit or create a new *Bitbucket Server / Bitbucket Data Center* connection. Add the following settings:
+
+```json
+{
+	// Other config goes here
+	"authorization": {
+		"identityProvider": {
+			"type": "username"
+		},
+		"oauth": {
+			"consumerKey": "<KEY GOES HERE>",
+			"signingKey": "<KEY GOES HERE>"
+		}
+	}
+}
+```
+
+Copy the *Consumer Key* you generated before to the `oauth.consumerKey` field and the output of the command `base64 sourcegraph.pem | tr -d '\n'` to the `oauth.signingKey` field. Finally, **save the configuration**. You're done!
+
+### Fast permission sync with Bitbucket Server plugin
+
+By installing the [Bitbucket Server plugin](../../../integration/bitbucket_server.md), you can make use of the fast permission sync feature that allows using Bitbucket Server / Bitbucket Data Center permissions on larger instances.
 
 ### Fast permission syncing
 
 With the [Sourcegraph Bitbucket Server](../../integration/bitbucket_server.md#sourcegraph-bitbucket-server-plugin) you can enable fast permission syncing:
 
 1. Connect Bitbucket Server / Bitbucket Data Center to Sourcegraph (_see instructions above_).
-1. Follow the [instructions to set up repository permissions](../repo/permissions.md#bitbucket_server) with Bitbucket Server / Bitbucket Data Center.
+1. Follow the [instructions to set up repository permissions](#repository-permissions) with Bitbucket Server / Bitbucket Data Center.
 1. Install the [Sourcegraph Bitbucket Server plugin](../../integration/bitbucket_server.md#sourcegraph-bitbucket-server-plugin) on your Bitbucket Server / Bitbucket Data Center instance.
 1. In Sourcegraph, go to **Site admin > Manage code hosts** and edit the Bitbucket Server / Bitbucket Data Center configuration.
 1. Add the `"plugin.permissions"` property:

doc/admin/external_service/gerrit.md

@@ -25,8 +25,22 @@ To connect Gerrit to Sourcegraph:
 
 ## Repository permissions
 
-By default, all Sourcegraph users can view all repositories. To configure
-Sourcegraph to use Gerrit's access management, see "[Repository permissions](../repo/permissions.md#gerrit)".
+Prerequisite: [Add Gerrit as an authentication provider](../auth/index.md#gerrit).
+
+Then, add or edit a Gerrit connection as described above and include the `authorization` field:
+
+```json
+{
+  // The Gerrit URL used to set up the Gerrit authentication provider must match this URL.
+  "url": "https://gerrit.example.com",
+  "username": "<admin username>",
+  "password": "<admin password>",
+  // ...
+  "authorization": {}
+}
+```
+
+> NOTE: It can take some time to complete full cycle of repository permissions sync if you have a large number of users or repositories. [See sync duration time](../permissions/syncing.md#sync-duration) for more information.
 
 ## User authentication