Sourcegraph Accounts Management System (SAMS) is the single source of truth (aka. IdP) for Sourcegraph-operated services that require a Sourcegraph user account or machine-to-machine authentication and authorization, including but not limited to Sourcegraph.com, Workspaces, Cody PLG, Sourcegraph Analytics, Cody Gateway, Telemetry Gateway and Enterprise Portal.

The MSP IAM (Identity and Access Management) framework aims to standardize how SAMS-integrated Managed Services Platform (MSP) services think about and manage roles and permissions by offering a Zanzibar-style relationship-based access control (ReBAC) solution based on OpenFGA.

Diagram

The diagram below illustrates the example architecture for Enterprise Portal (EP) (excalidraw):

In the above diagram, we have Enterprise Portal as the example service, and components colored in orange are part of the MSP IAM framework, components colored in blue belong to Enterprise Portal itself.

The motivation for the distributedly-managed architecture:

• Per objective, Core Services wants something short-term deliverable and be intentional about making infrastructure resources as owned by the framework.
• It provides a unified approach so services can be built more future-looking, but managed in a distributed manner to allow managed service owners more flexibility and independence.
• Separate databases ensure service owners cannot accidentally rely on internal details of the framework when designing and implementing their services - the msp_iam database is owned by the framework, and should not be used directly.
  • This is critical to ensure fleet-wide upgradability as Core Services makes future improvements to the framework, and ultimately transparently swap out the backend of the framework to be a centralized system.
  • Although the storage (database) lives alongside the service deployment (for the time being), services should be treating the framework as a black box. Notable anti-patterns are:
    • ❌ Connect directly into the msp_iam database and run SQL queries.
    • ❌ Replicate IAM data directly on the SQL level.
      • If the service needs to replicate the IAM data, ALWAYS use the APIs that are provided by the framework.

Philosophy

In Zanzibar’s data modeling, the primary building blocks are a few types of “relationships” that form graphs from which access control decisions are made. It does not provide further details about how exactly services are utilizing those relations, i.e. are they making roles the most granular level, or are they using relations both as roles and permissions, or are they doing interpretation of relation (as roles) and translating to permissions at the service level. How the “access control graph” is used is up to each integrator.

In lieu of a “Zanzibar recommendation”, we propose usage patterns that are similar to GCP IAM (which according to the white paper, builds access controls on top of Zanzibar): the MSP IAM framework makes roles and permissions first-class concepts by explicitly defining their purposes and responsibilities.

The way service owners should think about roles and permissions:

• Services define the roles and their associated permissions, subjects are assigned with roles only, e.g. “this user is a customer admin of the subscription”.
• Permissions is what call sites only cares about, e.g. “can this subject view the Cody Analytics for the instance ” NOT “is this subject a customer admin on the instance” because relying on the permissions has the least coupling between services, and the most compatible manner when the service owner introduce other roles that can do the same thing (or removing, changing name, etc.), without updating all the call sites.

Further readings:

• Google Cloud - IAM overview

Scopes vs. roles and permissions