Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion docs/admin/audit-log.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ Audit logs are structured logs delivered as JSON to STDERR. As long as one can i

### Log Output

All audit logs are delivered to **STDERR** for each individual [component](/self-hosted/deploy/kubernetes/scale#core-components).
All audit logs are delivered to **STDERR** for each individual [component](/self-hosted/deploy/kubernetes/scale).

### Filtering Audit Logs

Expand Down
2 changes: 1 addition & 1 deletion docs/admin/auth/builtin.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Builtin password authentication

The [`builtin` auth provider](/admin/config/site-config#builtin-password-authentication) manages user accounts inside Sourcegraph. It supports user signup, login, and password reset. This is the simplest provider type to set up, and is the default auth provider on a fresh installation for the first user so they can create an account and become site admin.
The [`builtin` auth provider](/admin/auth/builtin) manages user accounts inside Sourcegraph. It supports user signup, login, and password reset. This is the simplest provider type to set up, and is the default auth provider on a fresh installation for the first user so they can create an account and become site admin.

Use this auth provider, if you have no organizational requirements to use a SSO provider.

Expand Down
18 changes: 9 additions & 9 deletions docs/admin/auth/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ The following methods are supported for sign up and sign in:
- [HTTP authentication proxies](#http-authentication-proxies)
- [Username header prefixes](#username-header-prefixes)

The authentication providers are configured in the [`auth.providers`](/admin/config/site-config#authentication-providers) site configuration option.
The authentication providers are configured in the [`auth.providers`](/admin/config/site-config) site configuration option.

## Programmatic authentication

Expand All @@ -50,7 +50,7 @@ If you are unsure which auth provider is right for you, we recommend applying th
order:

- If you have no external identity providers (i.e., not SSO) or are just trying to spin Sourcegraph
up as quickly as possible to try, use [`builtin`](#builtin-password-authentication) authentication. You can
up as quickly as possible to try, use [`builtin`](/admin/auth/builtin) authentication. You can
always change the auth configuration later, and user identities from external providers will be
linked automatically to existing Sourcegraph accounts using verified email addresses.
- If you are deploying Sourcegraph behind a HTTP authentication proxy service, use the
Expand Down Expand Up @@ -116,7 +116,7 @@ configuration.

Leave the `url` field empty for GitHub.com.

Once you've configured GitHub as a sign-on provider, you may also want to [add GitHub repositories to Sourcegraph](/admin/code-hosts/github#repository-syncing).
Once you've configured GitHub as a sign-on provider, you may also want to [add GitHub repositories to Sourcegraph](/admin/code-hosts/github#selecting-repositories-to-sync).

### How to control user sign-up and sign-in with GitHub auth provider

Expand Down Expand Up @@ -405,7 +405,7 @@ Users can then add Gerrit credentials by visiting their **Settings** > **Account

## OpenID Connect

The [`openidconnect` auth provider](/admin/config/site-config#openid-connect-including-google-workspace) authenticates users via OpenID Connect, which is supported by many external services, including:
The [`openidconnect` auth provider](/admin/auth#openid-connect) authenticates users via OpenID Connect, which is supported by many external services, including:

- [Google Workspace (Google accounts)](#google-workspace-google-accounts)
- [Okta](https://developer.okta.com/docs/api/resources/oidc.html)
Expand All @@ -427,7 +427,7 @@ To configure Sourcegraph to authenticate users via OpenID Connect:
1. Provide the OpenID Connect client's issuer, client ID, and client secret in the Sourcegraph site configuration shown below.
1. (Optional) Require users to have a specific email domain name to authenticate (e.g., to limit users to only those from your organization).

Example [`openidconnect` auth provider](/admin/config/site-config#openid-connect-including-google-workspace) configuration:
Example [`openidconnect` auth provider](/admin/auth#openid-connect) configuration:

```json
{
Expand All @@ -449,7 +449,7 @@ Example [`openidconnect` auth provider](/admin/config/site-config#openid-connect

Sourcegraph supports the OpenID Connect Discovery standard for configuring the auth provider (using the values provided in the document at, e.g., `https://oidc.example.com/.well-known/openid-configuration`).

See the [`openid` auth provider documentation](/admin/config/site-config#openid-connect-including-google-workspace) for the full set of configuration options.
See the [`openid` auth provider documentation](/admin/auth#openid-connect) for the full set of configuration options.

### How to control user sign-up with OpenID auth provider

Expand Down Expand Up @@ -478,7 +478,7 @@ Google's Workspace (formerly known as G Suite) supports OpenID Connect, which is
1. Use the **client ID** and **client secret** values in Sourcegraph site configuration (as shown in the example below).
1. Set your Google Workspace domain in `requireEmailDomain` to prevent users outside your organization from signing in.

Example [`openidconnect` auth provider](/admin/config/site-config#openid-connect-including-google-workspace) configuration for Google Workspace:
Example [`openidconnect` auth provider](/admin/auth#openid-connect) configuration for Google Workspace:

```json
{
Expand Down Expand Up @@ -547,7 +547,7 @@ Consequently, you can only sign in via an auth provider if your email on Sourceg
Let's say the email field in your Sourcegraph account was kept blank when a site admin created the account for you, but the username matches your username on GitHub or GitLab. Will this work? If you try to sign in to SG with GitHub or GitLab, it won't work, and you will see an error informing you that a verified email is missing.

Exceptions to this rule are [HTTP Proxies](#http-authentication-proxies), where there's an option to make the link via username only.
For [Bitbucket](/admin/config/authorization-and-authentication#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.
For [Bitbucket](/admin/config/authorization-and-authentication#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](/admin/code-hosts/gitlab#username), for example.
Usernames in Sourcegraph are mutable, so a malicious user could change a username, elevating their privileges.
Expand All @@ -556,7 +556,7 @@ Usernames in Sourcegraph are mutable, so a malicious user could change a usernam

Sourcegraph will automatically link accounts from multiple external auth providers, resulting in a single user account on Sourcegraph. That way a user can login with multiple auth methods and end up being logged in with the same Sourcegraph account. In general, to link accounts, the following condition needs to be met:

At the time of signing in with the new account, any of the email addresses configured on the user account on the auth provider must match any of the **verified** email addresses on the user account on the Sourcegraph side. If there is a match, the accounts are linked, [otherwise a new user account is created if auth provider is configured to support user sign ups](#how-to-control-user-sign-up).
At the time of signing in with the new account, any of the email addresses configured on the user account on the auth provider must match any of the **verified** email addresses on the user account on the Sourcegraph side. If there is a match, the accounts are linked, [otherwise a new user account is created if auth provider is configured to support user sign ups](#how-to-control-user-sign-up-and-sign-in-with-github-auth-provider).

## Username normalization

Expand Down
2 changes: 1 addition & 1 deletion docs/admin/auth/login-form.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The login form allows users to sign in to Sourcegraph using [configured auth pro

<Callout type="info">Supported for Sourcegraph versions 5.1 or more.</Callout>

These options do not apply to [`builtin`](/admin/auth/#builtin-password-authentication) and
These options do not apply to [`builtin`](/admin/auth/builtin) and
[`http-header`](/admin/auth/#http-authentication-proxies) auth providers.

- The builtin auth provider has its own login form.
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/auth/saml/azure-ad.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@

## 2. Add the SAML auth provider to Sourcegraph site config

[Add a SAML auth provider](/admin/auth/#add-a-saml-provider) with `identityProviderMetadataURL` set to the "App Federation Metadata Url" you recorded in the previous section. Here is an example of what your site configuration should look like:
[Add a SAML auth provider](/admin/auth/saml#add-a-saml-provider) with `identityProviderMetadataURL` set to the "App Federation Metadata Url" you recorded in the previous section. Here is an example of what your site configuration should look like:

```json
{
Expand Down
2 changes: 1 addition & 1 deletion docs/admin/auth/saml/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Select your SAML identity provider for setup instructions:
- [JumpCloud](/admin/auth/saml/jump-cloud)
- [Other](/admin/auth/saml/generic)

For advanced SAML configuration options, see the [`saml` auth provider documentation](/admin/config/site-config#saml).
For advanced SAML configuration options, see the [`saml` auth provider documentation](/admin/auth/saml).

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This link is intended to go do the site config schema section for saml, but that's broken because the site config schema is a JSON blob, and markdown headers aren't supported inside a giant JSON blob.

Linking instead to the saml docs page is not the intended path, but I'm not sure what else to do here.


> NOTE: Sourcegraph currently supports at most 1 SAML auth provider at a time (but you can configure additional auth providers of other types). This should not be an issue for 99% of customers.

Expand Down
4 changes: 2 additions & 2 deletions docs/admin/auth/saml/microsoft-adfs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ These instructions guide you through configuring Sourcegraph as a relying party

- Active Directory instance where all users have email and username attributes.
- An instance of ADFS running on Windows Server, joined to your Active Directory domain.
- Sourcegraph should be [configured to use HTTPS](/self-hosted/http-https-configuration#nginx-ssl-https-configuration).
- Sourcegraph should be [configured to use HTTPS](/self-hosted/http-https-configuration#nginx-sslhttps-configuration).
- Ensure that `externalURL` in [site config](/admin/config/site-config) meets the following
criteria:
- It is the URL used by end users (no trailing slash).
Expand Down Expand Up @@ -191,4 +191,4 @@ error, double-check the relying party identifiers of the Relying Party Trust ent

### Other troubleshooting

See [SAML troubleshooting](/admin/auth/saml/#saml-troubleshooting) for more tips.
See [SAML troubleshooting](/admin/auth/saml#troubleshooting) for more tips.
2 changes: 1 addition & 1 deletion docs/admin/code-hosts/aws-codecommit.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ To add CodeCommit repositories in Docker Container:
### Mounting SSH keys into the container

1. Copy all the files at your `$HOME/.ssh directory` to `$HOME/.sourcegraph/config/ssh` directory.
1. Read our [guide here](/self-hosted/deploy/docker-compose/#git-ssh-configuration) for Docker Compose deployments
1. Read our [guide here](/self-hosted/deploy/docker-compose/configuration#git-ssh-configuration) for Docker Compose deployments
1. Read our [guide here](/self-hosted/deploy/kubernetes/configure#ssh-for-cloning) for Kubernetes deployments
1. Start (or restart) the container.
1. Connect Sourcegraph to AWS CodeCommit by going to **Sourcegraph > Site Admin > Manage code hosts > Generic Git host** and add the following:
Expand Down
6 changes: 3 additions & 3 deletions docs/admin/code-hosts/bitbucket-server.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ To connect Bitbucket Server / Bitbucket Data Center to Sourcegraph:
1. Configure the connection to Bitbucket Server / Bitbucket Data Center using the action buttons above the text field, and additional fields can be added using <kbd>Cmd/Ctrl+Space</kbd> for auto-completion. See the [configuration documentation below](#configuration).
1. Press **Add repositories**.

Also consider installing the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-server-plugin) which enables native code navigation for every Bitbucket user when browsing code and reviewing pull requests, allows for faster permission syncing between Sourcegraph and Bitbucket Server / Bitbucket Data Center and adds support for webhooks to Bitbucket Server / Bitbucket Data Center.
Also consider installing the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-plugin) which enables native code navigation for every Bitbucket user when browsing code and reviewing pull requests, allows for faster permission syncing between Sourcegraph and Bitbucket Server / Bitbucket Data Center and adds support for webhooks to Bitbucket Server / Bitbucket Data Center.

## Access token permissions

Expand Down Expand Up @@ -163,11 +163,11 @@ By installing the [Bitbucket Server plugin](/integration/bitbucket-server), you

### Fast permission syncing

With the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-server-plugin) you can enable fast permission syncing:
With the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-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](#repository-permissions) with Bitbucket Server / Bitbucket Data Center.
1. Install the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-server-plugin) on your Bitbucket Server / Bitbucket Data Center instance.
1. Install the [Sourcegraph Bitbucket Server plugin](/integration/bitbucket-server#sourcegraph-bitbucket-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:

Expand Down
2 changes: 1 addition & 1 deletion docs/admin/code-hosts/gerrit.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ Users should now be able to authenticate their Sourcegraph accounts using their

## Have users authenticate their Sourcegraph accounts using their Gerrit HTTP credentials

After [configuring Gerrit as a code host connection](#configure-gerrit-as-code-host-connection) and [adding Gerrit as an authentication provider](#add-gerrit-as-an-authnetication-provider), users will be able to authenticate their Sourcegraph accounts using their Gerrit HTTP credentials:
After [configuring Gerrit as a code host connection](#configure-gerrit-as-a-code-host-connection) and [adding Gerrit as an authentication provider](#add-gerrit-as-an-authentication-provider), users will be able to authenticate their Sourcegraph accounts using their Gerrit HTTP credentials:

As a user:

Expand Down
12 changes: 6 additions & 6 deletions docs/admin/code-hosts/github.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,7 @@ When creating a code host connection for a GitHub App with multiple installation

> NOTE: When you create a GitHub App, Sourcegraph automatically sets up an [incoming webhook](/admin/webhooks/incoming) for the app. This webhook subscribes to events for any repository or organization the app has access to, allowing Sourcegraph to keep repository and permission data in sync with GitHub.

> NOTE: If you are using [Batch Changes](/batch-changes/), you can create a GitHub App to perform [commit signing](/admin/config/batch-changes#commit-signing-for-github) (Beta).
> NOTE: If you are using [Batch Changes](/batch-changes/), you can create a GitHub App to perform [commit signing](/admin/config/batch-changes#commit-signing-with-github-apps) (Beta).

#### Multiple installations

Expand Down Expand Up @@ -292,7 +292,7 @@ There are four fields for configuring which repositories are mirrored/synchroniz

- [`repos`](/admin/code-hosts/github#repos)A list of repositories in `owner/name` format. The order determines the order in which we sync repository metadata and is safe to change.
- [`orgs`](/admin/code-hosts/github#orgs)A list of organizations (every repository belonging to the organization will be cloned).
- [`repositoryQuery`](/admin/code-hosts/github#repositoryQuery)A list of strings with three pre-defined options (`public`, `affiliated`, `none`, none of which are subject to result limitations), and/or a [GitHub advanced search query](https://github.com/search/advanced). Note: There is an existing limitation that requires the latter, GitHub advanced search queries, to return [less than 1000 results](#repositoryquery-returns-first-1000-results-only).
- [`repositoryQuery`](/admin/code-hosts/github#repositoryQuery)A list of strings with three pre-defined options (`public`, `affiliated`, `none`, none of which are subject to result limitations), and/or a [GitHub advanced search query](https://github.com/search/advanced). Note: There is an existing limitation that requires the latter, GitHub advanced search queries, to return less than 1000 results.
- [`exclude`](/admin/code-hosts/github#exclude)A list of repositories to exclude which takes precedence over the `repos`, `orgs`, and `repositoryQuery` fields.

## Rate limits
Expand Down Expand Up @@ -321,7 +321,7 @@ See [Internal rate limits](/admin/code-hosts/rate-limits#internal-rate-limits).

Prerequisite for configuring repository permission syncing: [Add GitHub as an authentication provider](/admin/auth/#github).

> NOTE: If your GitHub organization enforces SAML SSO, consider configuring [`requiredSsoOrgs`](/admin/auth/#requiredssoOrgs) in your GitHub auth provider to ensure users properly authorize the OAuth application during sign-in. This helps prevent permissions syncing issues caused by tokens that lack SSO authorization.
> NOTE: If your GitHub organization enforces SAML SSO, consider configuring [`requiredSsoOrgs`](/admin/auth#github) in your GitHub auth provider to ensure users properly authorize the OAuth application during sign-in. This helps prevent permissions syncing issues caused by tokens that lack SSO authorization.

Then, add or edit the GitHub connection as described above and include the `authorization` field:

Expand All @@ -338,7 +338,7 @@ Repo-centric permission syncing is done by calling the [list repository collabor

> IMPORTANT: We strongly recommend configuring both read and write access to associated repositories for permission syncing due to GitHub's token scope requirements. Without write access, there will be a conflict between [user-centric sync](/admin/permissions/syncing#troubleshooting) and repo-centric sync. In that case, [disable repo-centric permission sync](/admin/permissions/syncing#disable-repo-centric-permission-sync) (supported in Sourcegraph 5.0.4+).

> IMPORTANT: Optional, but strongly recommended - [continue with configuring webhooks for permissions](/admin/webhooks/incoming#user-permissions).
> IMPORTANT: Optional, but strongly recommended - [continue with configuring webhooks for permissions](/admin/webhooks/incoming#github).

<span class="virtual-br"></span>

Expand Down Expand Up @@ -372,13 +372,13 @@ If you would like internal repositories to remain private, but you're experienci

### Trigger permissions sync from GitHub webhooks

Follow the link to [configure webhooks for permissions for Github](/admin/webhooks/incoming#user-permissions)
Follow the link to [configure webhooks for permissions for Github](/admin/webhooks/incoming#github)

### Teams and organizations permissions caching

> NOTE: This is an experimental feature.

> WARNING: The following section is experimental and might not work properly anymore on new Sourcegraph versions (post 4.0+). Please prefer [configuring webhooks for permissions instead](/admin/webhooks/incoming#user-permissions)
> WARNING: The following section is experimental and might not work properly anymore on new Sourcegraph versions (post 4.0+). Please prefer [configuring webhooks for permissions instead](/admin/webhooks/incoming#github)

Github code host can leverage caching mechanisms to reduce the number of API calls used when syncing permissions. This can significantly reduce the amount of time it takes to perform a full cycle of permissions sync due to reduced instances of being rate limited by the code host, and is useful for code hosts with very large numbers of users and repositories.

Expand Down
Loading