Sourcegraph Accounts Managment System (SAMS)

Sourcegraph Accounts Managment 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.

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.

Service images

Images are published to a private image repository, us-central1-docker.pkg.dev/sourcegraph-dev/sams/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

Here is a list of useful quick links:

For standard infrastructure operations, see Sourcegraph Accounts infrastructure operations.

Infrastructure access

The following Entitle requests are needed to get access to SAMS service infrastructure:

Deployments

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

Modify deployment manifest

To modify the deployment manifest:

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

Use a different image tag

To specify a Docker image tag other than the default, update the service.yaml:

 - id: prod
   ...
   deploy:
     type: manual
+    manual:
+      tag: insiders@sha256:3a7e1c0dd4e0d7e0c6d3e4d7b3a1

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/sams GitHub repository.