Critical configuration

Critical configuration defines how critical Sourcegraph components behave, such as the external URL and user authentication. Unlike normal site configuration, incorrect critical configuration can make Sourcegraph's web interface unreachable. Therefore, critical configuration must be edited on the failsafe management console, to allow recovery from misconfiguration.

View and edit critical configuration

Critical configuration must be edited on the management console. See "Accessing the management console" for more information.

Reference

All critical configuration options and their default values are shown below.

admin/config/critical.schema.json

{
	// WARNING: This option has been removed in favor of `auth.enableUsernameChanges`. As of 3.3, it has no effect, and as of 3.4, it will be removed entirely.
	"auth.disableUsernameChanges": false,

	// Enables users to change their username after account creation. Warning: setting this to be true has security implications if you have enabled (or will at any point in the future enable) repository permissions with an option that relies on username equivalency between Sourcegraph and an external service or authentication provider. Do NOT set this to true if you are using non-built-in authentication OR rely on username equivalency for repository permissions.
	"auth.enableUsernameChanges": false,

	// The externally accessible URL for Sourcegraph (i.e., what you type into your browser). Previously called `appURL`.
	"externalURL": null,
	// Other example values:
	// - "https://sourcegraph.example.com"

	// Whether the critical configuration has been migrated to the site configuration yet.
	"migrated": false,

//////////////////////////////////////////////////////////////
// Authentication
//////////////////////////////////////////////////////////////

	// The authentication providers to use for identifying and signing in users. See instructions below for configuring SAML, OpenID Connect (including G Suite), and HTTP authentication proxies. Multiple authentication providers are supported (by specifying multiple elements in this array).
	"auth.providers": [
		{
			"allowSignup": true,
			"type": "builtin"
		}
	],

	// WARNING: This option has been removed as of 3.8.
	"auth.public": false,

	// The duration of a user session, after which it expires and the user is required to re-authenticate. The default is 90 days. There is typically no need to set this, but some users may have specific internal security requirements.
	//
	// The string format is that of the Duration type in the Go time package (https://golang.org/pkg/time/#ParseDuration). E.g., "720h", "43200m", "2592000s" all indicate a timespan of 30 days.
	//
	// Note: changing this field does not affect the expiration of existing sessions. If you would like to enforce this limit for existing sessions, you must log out currently signed-in users. You can force this by removing all keys beginning with "session_" from the Redis store:
	//
	// * For deployments using `sourcegraph/server`: `docker exec $CONTAINER_ID redis-cli --raw keys 'session_*' | xargs docker exec $CONTAINER_ID redis-cli del`
	// * For cluster deployments: 
	//   ```
	//   REDIS_POD="$(kubectl get pods -l app=redis-store -o jsonpath={.items[0].metadata.name})";
	//   kubectl exec "$REDIS_POD" -- redis-cli --raw keys 'session_*' | xargs kubectl exec "$REDIS_POD" -- redis-cli --raw del;
	//   ```
	"auth.sessionExpiry": "2160h",
	// Other example values:
	// - "168h"

//////////////////////////////////////////////////////////////
// Misc.
//////////////////////////////////////////////////////////////

	// HTML to inject at the bottom of the `<body>` element on each page, for analytics scripts
	"htmlBodyBottom": null,

	// HTML to inject at the top of the `<body>` element on each page, for analytics scripts
	"htmlBodyTop": null,

	// HTML to inject at the bottom of the `<head>` element on each page, for analytics scripts
	"htmlHeadBottom": null,

	// HTML to inject at the top of the `<head>` element on each page, for analytics scripts
	"htmlHeadTop": null,

	// Access token for sending traces to LightStep.
	"lightstepAccessToken": null,

	// The project ID on LightStep that corresponds to the `lightstepAccessToken`, only for generating links to traces. For example, if `lightstepProject` is `mycompany-prod`, all HTTP responses from Sourcegraph will include an X-Trace header with the URL to the trace on LightStep, of the form `https://app.lightstep.com/mycompany-prod/trace?span_guid=...&at_micros=...`.
	"lightstepProject": null,
	// Other example values:
	// - "myproject"

	// Configuration for logging and alerting, including to external services.
	"log": null,
	// Other example values:
	// - {
	//     "sentry": {
	//       "dsn": "https://[email protected]/myproject"
	//     }
	//   }

	// The channel on which to automatically check for Sourcegraph updates.
	"update.channel": "release",
	// Other example values:
	// - "none"

	// Use local Jaeger instance for tracing. Kubernetes cluster deployments only.
	//
	// After enabling Jaeger and updating your Kubernetes cluster, `kubectl get pods`
	// should display pods prefixed with `jaeger-cassandra`,
	// `jaeger-collector`, and `jaeger-query`. `jaeger-collector` will start
	// crashing until you initialize the Cassandra DB. To do so, do the
	// following:
	//
	// 1. Install [`cqlsh`](https://pypi.python.org/pypi/cqlsh).
	// 1. `kubectl port-forward $(kubectl get pods | grep jaeger-cassandra | awk '{ print $1 }') 9042`
	// 1. `git clone https://github.com/uber/jaeger && cd jaeger && MODE=test ./plugin/storage/cassandra/schema/create.sh | cqlsh`
	// 1. `kubectl port-forward $(kubectl get pods | grep jaeger-query | awk '{ print $1 }') 16686`
	// 1. Go to http://localhost:16686 to view the Jaeger dashboard.
	"useJaeger": null,

//////////////////////////////////////////////////////////////
// Sourcegraph Enterprise license
//////////////////////////////////////////////////////////////

	// The license key associated with a Sourcegraph product subscription, which is necessary to activate Sourcegraph Enterprise functionality. To obtain this value, contact Sourcegraph to purchase a subscription. To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"licenseKey": null
}

Authentication providers auth.providers

The auth.providers critical configuration property defines how users can authenticate to the Sourcegraph instance. It is an array of values, each of which defines an authentication provider. If the array has more than one element, users may use any of the configured authentication methods.

All authentication providers support the (optional) displayName property, which is used to distinguish the authentication provider when there are multiple providers configured.

Builtin password authentication

Defines an authentication provider that stores and validates passwords for each user account. It also allows users (and site admins) to reset passwords.

To use this authentication method, add an element to the auth.providers array with the following shape:

admin/config/critical.schema.json#/definitions/BuiltinAuthProvider

{
	"type": "builtin",

	// Allows new visitors to sign up for accounts. The sign-up page will be enabled and accessible to all visitors.
	//
	// SECURITY: If the site has no users (i.e., during initial setup), it will always allow the first user to sign up and become site admin **without any approval** (first user to sign up becomes the admin).
	"allowSignup": false
}

SAML

Defines an authentication provider backed by SAML.

Note: if you are using IdP-initiated login, you must have at most one SAML authentication provider in the auth.providers array.

To use this authentication method, add an element to the auth.providers array with the following shape:

admin/config/critical.schema.json#/definitions/SAMLAuthProvider

{
	"type": "saml",

	// An identifier that can be used to reference this authentication provider in other parts of the config. For example, in configuration for a code host, you may want to designate this authentication provider as the identity provider for the code host.
	"configID": null,

	"displayName": null,

	// The SAML Identity Provider metadata XML contents (for static configuration of the SAML Service Provider). The value of this field should be an XML document whose root element is `<EntityDescriptor>` or `<EntityDescriptors>`. To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"identityProviderMetadata": null,

	// The SAML Identity Provider metadata URL (for dynamic configuration of the SAML Service Provider).
	"identityProviderMetadataURL": null,

	// Whether the Service Provider should (insecurely) accept assertions from the Identity Provider without a valid signature.
	"insecureSkipAssertionSignatureValidation": false,

	// The SAML NameID format to use when performing user authentication.
	"nameIDFormat": "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
	// Other example values:
	// - "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
	// - "urn:oasis:names:tc:SAML:1.1:nameid-format:persistent"
	// - "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
	// - "urn:oasis:names:tc:SAML:2.0:nameid-format:emailAddress"
	// - "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
	// - "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
	// - "urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified"

	// The SAML Service Provider certificate in X.509 encoding (begins with "-----BEGIN CERTIFICATE-----"). This certificate is used by the Identity Provider to validate the Service Provider's AuthnRequests and LogoutRequests. It corresponds to the Service Provider's private key (`serviceProviderPrivateKey`). To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"serviceProviderCertificate": null,

	// The SAML Service Provider name, used to identify this Service Provider. This is required if the "externalURL" field is not set (as the SAML metadata endpoint is computed as "<externalURL>.auth/saml/metadata"), or when using multiple SAML authentication providers.
	"serviceProviderIssuer": null,

	// The SAML Service Provider private key in PKCS#8 encoding (begins with "-----BEGIN PRIVATE KEY-----"). This private key is used to sign AuthnRequests and LogoutRequests. It corresponds to the Service Provider's certificate (`serviceProviderCertificate`). To escape the value into a JSON string, you may want to use a tool like https://json-escape-text.now.sh.
	"serviceProviderPrivateKey": null,

	// Sign AuthnRequests and LogoutRequests sent to the Identity Provider using the Service Provider's private key (`serviceProviderPrivateKey`). It defaults to true if the `serviceProviderPrivateKey` and `serviceProviderCertificate` are set, and false otherwise.
	"signRequests": null
}

OpenID Connect (including G Suite)

Defines an authentication provider backed by OpenID Connect. The most common case is G Suite (Google) authentication.

To use this authentication method, add an element to the auth.providers array with the following shape:

admin/config/critical.schema.json#/definitions/OpenIDConnectAuthProvider

{
	"type": "openidconnect",

	// The client ID for the OpenID Connect client for this site.
	//
	// For Google Apps: obtain this value from the API console (https://console.developers.google.com), as described at https://developers.google.com/identity/protocols/OpenIDConnect#getcredentials
	"clientID": null,

	// The client secret for the OpenID Connect client for this site.
	//
	// For Google Apps: obtain this value from the API console (https://console.developers.google.com), as described at https://developers.google.com/identity/protocols/OpenIDConnect#getcredentials
	"clientSecret": null,

	// An identifier that can be used to reference this authentication provider in other parts of the config. For example, in configuration for a code host, you may want to designate this authentication provider as the identity provider for the code host.
	"configID": null,

	"displayName": null,

	// The URL of the OpenID Connect issuer.
	//
	// For Google Apps: https://accounts.google.com
	"issuer": null,

	// Only allow users to authenticate if their email domain is equal to this value (example: mycompany.com). Do not include a leading "@". If not set, all users on this OpenID Connect provider can authenticate to Sourcegraph.
	"requireEmailDomain": null
}

HTTP authentication proxy

Defines an authentication provider that authenticates users by consulting an HTTP request header set by an authentication proxy, such as https://github.com/bitly/oauth2_proxy.

To use this authentication method, add an element to the auth.providers array with the following shape:

admin/config/critical.schema.json#/definitions/HTTPHeaderAuthProvider

{
	"type": "http-header",

	// The prefix that precedes the username portion of the HTTP header specified in `usernameHeader`. If specified, the prefix will be stripped from the header value and the remainder will be used as the username. For example, if using Google Identity-Aware Proxy (IAP) with Google Sign-In, set this value to `accounts.google.com:`.
	"stripUsernameHeaderPrefix": null,
	// Other example values:
	// - "accounts.google.com:"

	// The name (case-insensitive) of an HTTP header whose value is taken to be the username of the client requesting the page. Set this value when using an HTTP proxy that authenticates requests, and you don't want the extra configurability of the other authentication methods.
	"usernameHeader": null
	// Other example values:
	// - "X-Forwarded-User"
}

Known bugs

The following critical configuration options require the server to be restarted for the changes to take effect:

lightstepAccessToken
lightstepProject
auth.userOrgMap
auth.providers
update.channel
useJaeger