Sourcegraph teammate access to Cloud instances

Sourcegraph teammates access to Cloud instances application interface (Web UI) is restricted to essential personnel only. This ensures Sourcegraph is able to help customers troubleshoot issues and deliver a smooth experience. We utilize Sourcegraph Operator Authentication Provider (SOAP) which implements OpenID Connect to enable Sourcegraph employees access to customer instance to make sure there is an audit trail for every access.

The Cloud team manages a separate Cloud Okta account (separate from the company-wide Sourcegraph Okta account) to manage UI access to Cloud instances. The Cloud Okta account is federated by the parent Sourcegraph Okta account to ensure access control is consistent across all our systems. For example, if an account is deactivated from the Sourcegraph Okta account, the user will loss access to Cloud Okta as well.

Each Cloud instance equals to an Okta OAuth application. For each Okta application, an Okta group is created and assign access to the Okta application. By default, no teammate has UI access to any customer Cloud instances, hence the Okta group is empty. We will then grant time-bound access to the group as needed.

You can learn more about the detail from the following RFCs:

The default admin user on managed instances

Every instance has a default Sourcegraph admin user added during the instance initialisation. The username, password and access token of the admin user is stored in Google Secret Manager (GSM) in the GCP project of the managed instance. The access token is used to access the managed instance by our services programmatically.

Request UI access to managed instances

Use the /access_request slash command on Slack, and select the following:

  • Search permission:
  • Grant method: Direct
  • Permission duration: 1 Hour
  • Add justification: Please explain in detail why do you need access to the Cloud instance UI. It will be best to include relevant links to issues, slack thread to provide more context.

The request will be routed to #cloud, #security, and your direct manager for approval. Any of the approvers can review and approve the access request.

Please tag @cloud-support or @security-support in #cloud for immediate attention if the request is time sensitive.

The Entitle Slack app will notify you both when you make the request and when the request is approved. You will then have UI access to the requested managed instance for 1 hour (the Permission duration from the previous step). Once the access period ends, you will be logged-out from the managed instance and have to request access again through the Entitle.

To sign in to the requested managed instance:

  1. Visit in your browser
  2. Click on the Continue with Sourcegraph Operators sign-in option
  3. Complete the authentication flow with Okta

UI access to private managed instances

Private managed instances refer to managed instances that have enabled private mode, additonal steps are required to be able to visit the instance UI after you have completed the steps to grant UI access.

  1. Set up a port forwarding to the managed instance:

    mi forward 80 4444
  2. Visit http://localhost:4444/sign-in?sourcegraph-operator

  3. Click on the Continue with Sourcegraph Operators sign-in option

  4. Complete the authentication flow with Okta

  5. Encounter an error about no state cookie found

  6. Replace the beginning part of URL from to http://localhost:4444


What is Sourcegraph Operator Authentication Provider?

Sourcegraph Operator Authentication Provider (SOAP) is an OpenID Connect-based authentication provider that is designed specifically for Sourcergaph Cloud managed instances. In combination with the Okta application and Entitle access request workflow, it allows time-bound, audit-trailed UI access to managed instances for Sourcegraph employees in the events of instance maintenance, issue troubleshooting, and customer assistance.

SOAP creates special user accounts that are refered as “Sourcegraph operators”, which has the following traits:

  • Sourcegraph operators are only available on Sourcergaph Cloud managed instances.
  • Sourcegraph operators are temporary user accounts. By default, they’ll be hard-deleted from the instances after 60 minutes.
  • Sourcegraph operators are not counting towards the customer license seats.
  • Sourcegraph operators are invisible from the application UI, site admins are not able to see them.
  • All activities of Sourcegraph operators are logged and attributed in the database, and excluded from both in-product analytics and usage stats in pings.

How to identify Sourcegraph operators on a managed instance?

Sourcegraph operators often have the prefix sourcegraph-operator- in their usernames, however, having such username prefix does not automatically make those users become Sourcegraph operators.

To pull out the list of Sourcegraph operators on a given managed instance, set up a Cloud SQL proxy to the managed instance.

Run the following SQL query:

    SELECT user_id FROM user_external_accounts WHERE service_type = 'sourcegraph-operator'

How to identify user activities of Sourcegraph operators on a managed instance?

To pull out user activities of Sourcegraph operators on a given managed instance, set up a Cloud SQL proxy to the managed instance.

Run the following SQL query for event logs:

SELECT * FROM event_logs WHERE public_argument @> '{"sourcegraph_operator": true}';

Run the following SQL query for security event logs:

SELECT * FROM security_event_logs WHERE argument @> '{"sourcegraph_operator": true}';

How to enable/disable SOAP for a managed instance?

Go to the $CUSTOMER direcotry.

For v1 instances:

  1. Remove or add the following line in the config.yaml file to enable or disable SOAP respectively:

    disableSourcegraphManagementAccess: true
  2. Update the GSM value of the secret CLOUD_SITE_CONFIG by running mi sync cloud-site-config.

  3. Pull down the new GSM value to the VM by running terraform apply or trigger an apply on the Terraform Cloud.

  4. Reload the manage instance.

For v2 instances:

Disabling SOAP is currently not supported on v2.

How to enable SOAP locally?

  1. Create a temporary JSON file (site-config.json) with the following content, the credentials can be obtained from the Okta test instance admin in 1Password and the OpenID Connect (sourcegraph.test:3443) Okta application :

      "authProviders": {
        "sourcegraphOperator": {
          "issuer": "",
          "clientID": "<REDACTED>",
          "clientSecret": "<REDACTED>",
          "lifecycleDuration": 60
  2. Sign the Cloud site config:

    mi sign-cloud-site-config --config-file site-config.json
  3. Set the output of the above command as the value of the environment variable SRC_CLOUD_SITE_CONFIG in your sg.config.overwrite.yaml:

      SRC_CLOUD_SITE_CONFIG: 'eyJzaWduYXR1cmUiOnsiRm9ybWF0Ijoic3NoLWVkMjU1M...'
  4. Start the local Sourcegraph instance and sign in with Continue with Sourcergaph Operators using the same Okta account used in the step 1.