Sourcegraph Accounts Management System (SAMS)

Sourcegraph Accounts Management System (SAMS) is the centralized accounts system for all of the Sourcegraph-operated systems, it provides:

  • Single Sign-On (SSO) experience for users of those systems, and cross-system referenceable user ID.
  • Out-of-the-box machine-to-machine authentication and authorization capabilities.

It is compliant with OAuth 2 and OIDC protocols but only exposes a subset of the full capabilities for security reasons. In particular, only the following flows are allowed:

The OpenID Discovery endpoint lays out all the protocol details that a Service Provider (aka. Relay Party) needs to know to integrate with SAMS.

System designs

Security measures

Here is a list of security measures that are notable to systems integrating with SAMS:

  1. Access tokens all have expiry with 1 hour, refresh tokens are always issued together with access tokens.
  2. Refresh tokens all have expiry with 30 days, and each refresh token can only be used at most once. A new refresh token is always issued upon refreshing the access token.

Internal documents

Service images

Images are published to a private image repository, us-central1-docker.pkg.dev/sourcegraph-dev/sourcegraph-accounts/accounts-server, on every commit in main using the insiders tag. To pull down the published images locally, you need to request access via Entitle.

Publishing resources are provisioned in sourcegraph/infrastructure.

Operations

For standard infrastructure operations, see Sourcegraph Accounts infrastructure operations.

Deployments

The SAMS service infrastructure is defined in sourcegraph/managed-services/services/sourcegraph-accounts utilizing Managed Services Platform.

Update deployment secrets

  • For production instance (https://accounts.sourcegraph.com), all secrets are stored in the same GCP project sourcegraph-accounts-prod-csvc.
    1. Make an Entitle request to grant access to the project.
    2. Add/update the secrets in the GSM.
    3. Make a pull request to add/update the secrets references under the id: prod > secretEnv section in the service.yaml file.
    4. Once the pull request is merged, roll out a new deployment to pick up the changes to the secrets.
  • For testing instance (https://accounts.sgdev.org), all secrets are stored in a shared GCP project sourcegraph-dev.
    1. Make an Entitle request to grant access to the project.
    2. Add/update the secrets in the GSM. Because this is shared project, make sure to prefix all secrets with SAMS_ to avoid naming collisions.
    3. Make a pull request to add/update the secrets references under the id: dev > secretEnv section in the service.yaml file.
    4. Once the pull request is merged, roll out a new deployment to pick up the changes to the secrets.

Modify deployment manifest

To modify the deployment manifest:

  1. Update service.yaml file
  2. In the repository root, run sg msp generate sourcegraph-accounts prod
  3. Stage changes and make a pull request
  4. The Terraform Cloud rolls out changes

Re-deploy the same manifest

Go to the “Deploy revision” page of the Cloud Run service and click DEPLOY (bottom of the page) without changing any configuration. This will also happen whenever a Terraform change happens to the “cloudrun” stack.

Observability

Alerting

Alerts are sent to Sentry and then forwarded to Slack:

Metrics

The deployment’s Cloud Run metrics overview page provides basic observability into the service provided out-of-the-box by Cloud Run, such as instance count and resource utilization.

Development

The source code and CI are located in the sourcegraph/sourcegraph-accounts GitHub repository.