Add bridge backend for sync

Signed-off-by: Bryan Frimin <bryan@getprobo.com>
2026-02-01 21:22:31 +01:00
parent bc5bbdae81
commit 3d4b215b8f
19 changed files with 1038 additions and 145 deletions
--- a/pkg/iam/scim/bridge/bridge.go
+++ b/pkg/iam/scim/bridge/bridge.go
@@ -0,0 +1,142 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+// Package scimbridge provides a bridge for synchronizing users from identity
+// providers to SCIM-compliant systems.
+package bridge
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"strings"
+
+	scimclient "go.probo.inc/probo/pkg/iam/scim/bridge/client"
+	"go.probo.inc/probo/pkg/iam/scim/bridge/provider"
+)
+
+type (
+	Bridge struct {
+		provider    provider.Provider
+		scimClient  *scimclient.Client
+		forceUpdate bool
+		dryRun      bool
+	}
+
+	Option func(*Bridge)
+)
+
+func WithDryRun(dryRun bool) Option {
+	return func(s *Bridge) {
+		s.dryRun = dryRun
+	}
+}
+
+func WithForceUpdate(forceUpdate bool) Option {
+	return func(s *Bridge) {
+		s.forceUpdate = forceUpdate
+	}
+}
+
+func NewBridge(provider provider.Provider, scimClient *scimclient.Client, opts ...Option) *Bridge {
+	s := &Bridge{
+		provider:   provider,
+		scimClient: scimClient,
+	}
+
+	for _, opt := range opts {
+		opt(s)
+	}
+
+	return s
+}
+
+func (s *Bridge) Run(ctx context.Context) (created, updated, deactivated, skipped int, err error) {
+	providerUsers, err := s.provider.ListUsers(ctx)
+	if err != nil {
+		return 0, 0, 0, 0, fmt.Errorf("cannot list provider users: %w", err)
+	}
+
+	scimUsers, err := s.scimClient.ListUsers(ctx)
+	if err != nil {
+		return 0, 0, 0, 0, fmt.Errorf("cannot list scim users: %w", err)
+	}
+
+	scimUsersByEmail := make(map[string]*scimclient.User)
+	for i := range scimUsers {
+		email := strings.ToLower(scimUsers[i].UserName)
+		scimUsersByEmail[email] = &scimUsers[i]
+	}
+
+	providerEmails := make(map[string]bool)
+
+	var errs []error
+
+	for _, pu := range providerUsers {
+		email := strings.ToLower(pu.UserName)
+		providerEmails[email] = true
+
+		existingSCIM, exists := scimUsersByEmail[email]
+		if !exists {
+			if !s.dryRun {
+				if err := s.scimClient.CreateUser(ctx, &pu); err != nil {
+					errs = append(errs, fmt.Errorf("cannot create user %q: %w", pu.UserName, err))
+					continue
+				}
+			}
+			created++
+		} else {
+			needsUpdate := s.forceUpdate
+
+			if existingSCIM.Active != pu.Active {
+				needsUpdate = true
+			}
+			if existingSCIM.DisplayName != pu.DisplayName {
+				needsUpdate = true
+			}
+
+			if needsUpdate {
+				if !s.dryRun {
+					if err := s.scimClient.UpdateUser(ctx, existingSCIM.ID, &pu); err != nil {
+						errs = append(errs, fmt.Errorf("cannot update user %q: %w", pu.UserName, err))
+						continue
+					}
+				}
+				updated++
+			} else {
+				skipped++
+			}
+		}
+	}
+
+	for email, scimUser := range scimUsersByEmail {
+		if providerEmails[email] {
+			continue
+		}
+
+		if !scimUser.Active {
+			continue
+		}
+
+		if !s.dryRun {
+			if err := s.scimClient.DeactivateUser(ctx, scimUser.ID); err != nil {
+				errs = append(errs, fmt.Errorf("cannot deactivate user %q: %w", email, err))
+				continue
+			}
+		}
+		deactivated++
+	}
+
+	return created, updated, deactivated, skipped, errors.Join(errs...)
+}
--- a/pkg/iam/scim/bridge/client/client.go
+++ b/pkg/iam/scim/bridge/client/client.go
@@ -0,0 +1,254 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package scimclient
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+)
+
+type (
+	Client struct {
+		endpoint   string
+		token      string
+		httpClient *http.Client
+	}
+
+	User struct {
+		ID          string `json:"id,omitempty"`
+		UserName    string `json:"userName"`
+		DisplayName string `json:"displayName"`
+		GivenName   string `json:"-"`
+		FamilyName  string `json:"-"`
+		Active      bool   `json:"active"`
+	}
+
+	Users []User
+
+	ListResponse struct {
+		Schemas      []string `json:"schemas"`
+		TotalResults int      `json:"totalResults"`
+		StartIndex   int      `json:"startIndex"`
+		ItemsPerPage int      `json:"itemsPerPage"`
+		Resources    Users    `json:"Resources"`
+	}
+)
+
+func NewClient(httpClient *http.Client, endpoint, token string) *Client {
+	return &Client{
+		endpoint:   strings.TrimSuffix(endpoint, "/"),
+		token:      token,
+		httpClient: httpClient,
+	}
+}
+
+func (c *Client) ListUsers(ctx context.Context) (Users, error) {
+	var allUsers Users
+	startIndex := 1
+	count := 100
+
+	for {
+		users, total, err := c.listUsersPage(ctx, startIndex, count)
+		if err != nil {
+			return nil, err
+		}
+
+		allUsers = append(allUsers, users...)
+
+		if len(allUsers) >= total {
+			break
+		}
+
+		startIndex += count
+	}
+
+	return allUsers, nil
+}
+
+func (c *Client) listUsersPage(ctx context.Context, startIndex, count int) (Users, int, error) {
+	reqURL := fmt.Sprintf("%s/Users?startIndex=%d&count=%d", c.endpoint, startIndex, count)
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, reqURL, nil)
+	if err != nil {
+		return nil, 0, fmt.Errorf("cannot create request: %w", err)
+	}
+
+	c.setHeaders(req)
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return nil, 0, fmt.Errorf("cannot fetch users: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		body, _ := io.ReadAll(resp.Body)
+		return nil, 0, fmt.Errorf("SCIM API error: status %d, body: %s", resp.StatusCode, string(body))
+	}
+
+	var listResp ListResponse
+	if err := json.NewDecoder(resp.Body).Decode(&listResp); err != nil {
+		return nil, 0, fmt.Errorf("cannot decode response: %w", err)
+	}
+
+	return listResp.Resources, listResp.TotalResults, nil
+}
+
+func (c *Client) CreateUser(ctx context.Context, user *User) error {
+	payload := map[string]any{
+		"schemas":  []string{"urn:ietf:params:scim:schemas:core:2.0:User"},
+		"userName": user.UserName,
+		"name": map[string]string{
+			"givenName":  user.GivenName,
+			"familyName": user.FamilyName,
+			"formatted":  user.DisplayName,
+		},
+		"displayName": user.DisplayName,
+		"active":      user.Active,
+		"emails": []map[string]any{
+			{
+				"value":   user.UserName,
+				"type":    "work",
+				"primary": true,
+			},
+		},
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("cannot marshal user: %w", err)
+	}
+
+	reqURL := fmt.Sprintf("%s/Users", c.endpoint)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, reqURL, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("cannot create request: %w", err)
+	}
+
+	c.setHeaders(req)
+	req.Header.Set("Content-Type", "application/scim+json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("cannot create user: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusCreated && resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("SCIM API error: status %d, body: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}
+
+func (c *Client) UpdateUser(ctx context.Context, userID string, user *User) error {
+	payload := map[string]any{
+		"schemas":  []string{"urn:ietf:params:scim:schemas:core:2.0:User"},
+		"userName": user.UserName,
+		"name": map[string]string{
+			"givenName":  user.GivenName,
+			"familyName": user.FamilyName,
+			"formatted":  user.DisplayName,
+		},
+		"displayName": user.DisplayName,
+		"active":      user.Active,
+		"emails": []map[string]any{
+			{
+				"value":   user.UserName,
+				"type":    "work",
+				"primary": true,
+			},
+		},
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("cannot marshal user: %w", err)
+	}
+
+	reqURL := fmt.Sprintf("%s/Users/%s", c.endpoint, url.PathEscape(userID))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPut, reqURL, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("cannot create request: %w", err)
+	}
+
+	c.setHeaders(req)
+	req.Header.Set("Content-Type", "application/scim+json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("cannot update user: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("SCIM API error: status %d, body: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}
+
+func (c *Client) DeactivateUser(ctx context.Context, userID string) error {
+	payload := map[string]any{
+		"schemas": []string{"urn:ietf:params:scim:api:messages:2.0:PatchOp"},
+		"Operations": []map[string]any{
+			{
+				"op":    "replace",
+				"path":  "active",
+				"value": false,
+			},
+		},
+	}
+
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return fmt.Errorf("cannot marshal patch: %w", err)
+	}
+
+	reqURL := fmt.Sprintf("%s/Users/%s", c.endpoint, url.PathEscape(userID))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPatch, reqURL, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("cannot create request: %w", err)
+	}
+
+	c.setHeaders(req)
+	req.Header.Set("Content-Type", "application/scim+json")
+
+	resp, err := c.httpClient.Do(req)
+	if err != nil {
+		return fmt.Errorf("cannot deactivate user: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		respBody, _ := io.ReadAll(resp.Body)
+		return fmt.Errorf("SCIM API error: status %d, body: %s", resp.StatusCode, string(respBody))
+	}
+
+	return nil
+}
+
+func (c *Client) setHeaders(req *http.Request) {
+	req.Header.Set("Authorization", "Bearer "+c.token)
+	req.Header.Set("Accept", "application/scim+json")
+}
--- a/pkg/iam/scim/bridge/provider/googleworkspace/provider.go
+++ b/pkg/iam/scim/bridge/provider/googleworkspace/provider.go
@@ -0,0 +1,87 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+// Package googleworkspace provides a Google Workspace identity provider
+// for SCIM synchronization using OAuth2.
+package googleworkspace
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	admin "google.golang.org/api/admin/directory/v1"
+	"google.golang.org/api/option"
+
+	scimclient "go.probo.inc/probo/pkg/iam/scim/bridge/client"
+	"go.probo.inc/probo/pkg/iam/scim/bridge/provider"
+)
+
+var _ provider.Provider = (*Provider)(nil)
+
+type Provider struct {
+	httpClient *http.Client
+}
+
+func New(httpClient *http.Client) *Provider {
+	return &Provider{
+		httpClient: httpClient,
+	}
+}
+
+func (p *Provider) Name() string {
+	return "google-workspace"
+}
+
+func (p *Provider) ListUsers(ctx context.Context) (scimclient.Users, error) {
+	adminService, err := admin.NewService(ctx, option.WithHTTPClient(p.httpClient))
+	if err != nil {
+		return nil, fmt.Errorf("cannot create admin service: %w", err)
+	}
+
+	var allUsers scimclient.Users
+	pageToken := ""
+
+	for {
+		call := adminService.Users.List().Customer("my_customer").MaxResults(500).Context(ctx)
+		if pageToken != "" {
+			call = call.PageToken(pageToken)
+		}
+
+		resp, err := call.Do()
+		if err != nil {
+			return nil, fmt.Errorf("cannot list users: %w", err)
+		}
+
+		for _, u := range resp.Users {
+			allUsers = append(
+				allUsers,
+				scimclient.User{
+					UserName:    u.PrimaryEmail,
+					DisplayName: u.Name.FullName,
+					GivenName:   u.Name.GivenName,
+					FamilyName:  u.Name.FamilyName,
+					Active:      !u.Suspended && !u.Archived,
+				},
+			)
+		}
+
+		pageToken = resp.NextPageToken
+		if pageToken == "" {
+			break
+		}
+	}
+
+	return allUsers, nil
+}
--- a/pkg/iam/scim/bridge/provider/provider.go
+++ b/pkg/iam/scim/bridge/provider/provider.go
@@ -0,0 +1,28 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+// Package provider defines the interface for identity providers that can be
+// used as a source of truth for SCIM synchronization.
+package provider
+
+import (
+	"context"
+
+	scimclient "go.probo.inc/probo/pkg/iam/scim/bridge/client"
+)
+
+type Provider interface {
+	Name() string
+	ListUsers(ctx context.Context) (scimclient.Users, error)
+}
--- a/pkg/iam/scim/bridge_runner.go
+++ b/pkg/iam/scim/bridge_runner.go
@@ -0,0 +1,166 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package scim
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.opentelemetry.io/otel/codes"
+	"go.opentelemetry.io/otel/trace"
+	"go.probo.inc/probo/pkg/baseurl"
+	"go.probo.inc/probo/pkg/connector"
+	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/crypto/cipher"
+)
+
+type (
+	// BridgeRunnerConfig holds the configuration for the SCIM bridge runner.
+	BridgeRunnerConfig struct {
+		// Interval is the time between sync attempts for each bridge.
+		Interval time.Duration
+		// PollInterval is the time between polling for bridges to sync.
+		PollInterval time.Duration
+		// SyncTimeout is the maximum time allowed for a single sync operation.
+		SyncTimeout time.Duration
+		// BaseURL is the base URL of the API server (used to construct SCIM endpoint).
+		BaseURL *baseurl.BaseURL
+		// MaxBackoff is the maximum backoff duration between retries for failed bridges.
+		MaxBackoff time.Duration
+		// MaxConsecutiveFailures is the maximum number of consecutive failures
+		// before a bridge is automatically disabled.
+		MaxConsecutiveFailures int
+		// StaleSyncThreshold is the time after which a SYNCING bridge is considered
+		// stale and can be recovered by another runner (handles crashed runners).
+		StaleSyncThreshold time.Duration
+	}
+
+	// BridgeRunner is the SCIM bridge background runner.
+	BridgeRunner struct {
+		pg                *pg.Client
+		logger            *log.Logger
+		tp                trace.TracerProvider
+		tracer            trace.Tracer
+		registerer        prometheus.Registerer
+		encryptionKey     cipher.EncryptionKey
+		connectorRegistry *connector.ConnectorRegistry
+		cfg               BridgeRunnerConfig
+	}
+)
+
+// NewBridgeRunner creates a new SCIM bridge runner.
+func NewBridgeRunner(
+	pgClient *pg.Client,
+	logger *log.Logger,
+	tp trace.TracerProvider,
+	registerer prometheus.Registerer,
+	encryptionKey cipher.EncryptionKey,
+	connectorRegistry *connector.ConnectorRegistry,
+	cfg BridgeRunnerConfig,
+) *BridgeRunner {
+	if cfg.Interval == 0 {
+		cfg.Interval = 15 * time.Minute
+	}
+	if cfg.PollInterval == 0 {
+		cfg.PollInterval = 30 * time.Second
+	}
+	if cfg.SyncTimeout == 0 {
+		cfg.SyncTimeout = 5 * time.Minute
+	}
+	if cfg.MaxBackoff == 0 {
+		cfg.MaxBackoff = DefaultMaxBackoff
+	}
+	if cfg.MaxConsecutiveFailures == 0 {
+		cfg.MaxConsecutiveFailures = DefaultMaxConsecutiveFailures
+	}
+	if cfg.StaleSyncThreshold == 0 {
+		cfg.StaleSyncThreshold = DefaultStaleSyncThreshold
+	}
+
+	return &BridgeRunner{
+		pg:                pgClient,
+		logger:            logger,
+		tp:                tp,
+		tracer:            tp.Tracer("scim-bridge-runner"),
+		registerer:        registerer,
+		encryptionKey:     encryptionKey,
+		connectorRegistry: connectorRegistry,
+		cfg:               cfg,
+	}
+}
+
+// Run starts the runner loop that processes SCIM bridges.
+func (r *BridgeRunner) Run(ctx context.Context) error {
+	r.logger.InfoCtx(ctx, "starting SCIM bridge runner",
+		log.Duration("poll_interval", r.cfg.PollInterval),
+		log.Duration("sync_interval", r.cfg.Interval),
+		log.Duration("sync_timeout", r.cfg.SyncTimeout),
+		log.Duration("max_backoff", r.cfg.MaxBackoff),
+		log.Int("max_consecutive_failures", r.cfg.MaxConsecutiveFailures),
+		log.Duration("stale_sync_threshold", r.cfg.StaleSyncThreshold),
+	)
+
+	ticker := time.NewTicker(r.cfg.PollInterval)
+	defer ticker.Stop()
+
+	for {
+		if err := r.processBridge(ctx); err != nil {
+			if !errors.Is(err, coredata.ErrNoSCIMBridgeAvailable) {
+				r.logger.ErrorCtx(ctx, "cannot process SCIM bridge", log.Error(err))
+			}
+		}
+
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-ticker.C:
+		}
+	}
+}
+
+func (r *BridgeRunner) processBridge(ctx context.Context) error {
+	bridge, scope, err := r.acquireNextBridge(ctx)
+	if err != nil {
+		return err
+	}
+
+	ctx, span := r.tracer.Start(ctx, "scim-bridge-runner.processBridge")
+	defer span.End()
+
+	logger := r.logger.Named("bridge-sync").With(
+		log.String("bridge_id", bridge.ID.String()),
+		log.String("scim_configuration_id", bridge.ScimConfigurationID.String()),
+		log.String("bridge_type", string(bridge.Type)),
+		log.Int("consecutive_failures", bridge.ConsecutiveFailures),
+	)
+
+	logger.InfoCtx(ctx, "starting sync")
+
+	syncCtx, cancel := context.WithTimeout(ctx, r.cfg.SyncTimeout)
+	defer cancel()
+
+	stats, duration, connector, err := r.executeSync(syncCtx, bridge, scope, logger)
+	if err != nil {
+		span.RecordError(err)
+		span.SetStatus(codes.Error, "sync failed")
+		return r.transitionToFailed(ctx, bridge, scope, err, duration, logger)
+	}
+
+	return r.transitionToSuccess(ctx, bridge, scope, stats, duration, connector, logger)
+}
--- a/pkg/iam/scim/bridge_runner_backoff.go
+++ b/pkg/iam/scim/bridge_runner_backoff.go
@@ -0,0 +1,48 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package scim
+
+import "time"
+
+const (
+	// DefaultMaxConsecutiveFailures is the maximum number of consecutive failures
+	// before a bridge is disabled.
+	DefaultMaxConsecutiveFailures = 10
+
+	// DefaultMaxBackoff is the maximum backoff duration between retries.
+	DefaultMaxBackoff = 24 * time.Hour
+
+	// DefaultStaleSyncThreshold is the time after which a SYNCING bridge is
+	// considered stale and can be recovered by another runner.
+	DefaultStaleSyncThreshold = 10 * time.Minute
+)
+
+func (r *BridgeRunner) calculateBackoff(consecutiveFailures int) time.Duration {
+	if consecutiveFailures <= 0 {
+		return r.cfg.Interval
+	}
+
+	backoff := r.cfg.Interval * time.Duration(1<<consecutiveFailures)
+
+	if backoff > r.cfg.MaxBackoff {
+		return r.cfg.MaxBackoff
+	}
+
+	return backoff
+}
+
+func (r *BridgeRunner) shouldDisable(consecutiveFailures int) bool {
+	return consecutiveFailures >= r.cfg.MaxConsecutiveFailures
+}
--- a/pkg/iam/scim/bridge_runner_state.go
+++ b/pkg/iam/scim/bridge_runner_state.go
@@ -0,0 +1,173 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package scim
+
+import (
+	"context"
+	"time"
+
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/pkg/coredata"
+)
+
+// SyncStats holds the statistics from a sync operation.
+type SyncStats struct {
+	Created     int
+	Updated     int
+	Deactivated int
+	Skipped     int
+}
+
+func (r *BridgeRunner) acquireNextBridge(ctx context.Context) (*coredata.SCIMBridge, coredata.Scoper, error) {
+	var bridge *coredata.SCIMBridge
+	var scope coredata.Scoper
+
+	err := r.pg.WithTx(
+		ctx,
+		func(tx pg.Conn) error {
+			bridge = &coredata.SCIMBridge{}
+			if err := bridge.LoadNextForSyncSkipLocked(ctx, tx, r.cfg.StaleSyncThreshold); err != nil {
+				return err
+			}
+
+			scope = coredata.NewScope(bridge.ID.TenantID())
+
+			now := time.Now()
+			bridge.State = coredata.SCIMBridgeStateSyncing
+			bridge.UpdatedAt = now
+
+			return bridge.Update(ctx, tx, scope)
+		},
+	)
+
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return bridge, scope, nil
+}
+
+func (r *BridgeRunner) transitionToSuccess(
+	ctx context.Context,
+	bridge *coredata.SCIMBridge,
+	scope coredata.Scoper,
+	stats SyncStats,
+	duration time.Duration,
+	connector *coredata.Connector,
+	logger *log.Logger,
+) error {
+	return r.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			now := time.Now()
+			nextSync := now.Add(r.cfg.Interval)
+
+			bridge.State = coredata.SCIMBridgeStateActive
+			bridge.LastSyncedAt = &now
+			bridge.NextSyncAt = &nextSync
+			bridge.SyncError = nil
+			bridge.ConsecutiveFailures = 0
+			bridge.TotalSyncCount++
+			bridge.UpdatedAt = now
+
+			if err := bridge.Update(ctx, conn, scope); err != nil {
+				logger.ErrorCtx(ctx, "cannot update bridge after successful sync",
+					log.Error(err),
+				)
+				return err
+			}
+
+			if connector != nil {
+				connector.UpdatedAt = now
+				if err := connector.Update(ctx, conn, scope, r.encryptionKey); err != nil {
+					logger.WarnCtx(ctx, "cannot persist refreshed OAuth2 token",
+						log.String("connector_id", connector.ID.String()),
+						log.Error(err),
+					)
+				}
+			}
+
+			logger.InfoCtx(ctx, "sync completed successfully",
+				log.Duration("sync_duration", duration),
+				log.Int("users_created", stats.Created),
+				log.Int("users_updated", stats.Updated),
+				log.Int("users_deactivated", stats.Deactivated),
+				log.Int("users_skipped", stats.Skipped),
+			)
+
+			return nil
+		},
+	)
+}
+
+func (r *BridgeRunner) transitionToFailed(
+	ctx context.Context,
+	bridge *coredata.SCIMBridge,
+	scope coredata.Scoper,
+	syncErr error,
+	duration time.Duration,
+	logger *log.Logger,
+) error {
+	return r.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			now := time.Now()
+
+			bridge.ConsecutiveFailures++
+			bridge.TotalFailureCount++
+			bridge.TotalSyncCount++
+			bridge.LastSyncedAt = &now
+			bridge.UpdatedAt = now
+
+			errStr := syncErr.Error()
+			bridge.SyncError = &errStr
+
+			if r.shouldDisable(bridge.ConsecutiveFailures) {
+				bridge.State = coredata.SCIMBridgeStateDisabled
+				bridge.NextSyncAt = nil
+
+				logger.ErrorCtx(ctx, "bridge disabled due to max consecutive failures",
+					log.Duration("sync_duration", duration),
+					log.Int("consecutive_failures", bridge.ConsecutiveFailures),
+					log.Int("max_consecutive_failures", r.cfg.MaxConsecutiveFailures),
+					log.Error(syncErr),
+				)
+			} else {
+				bridge.State = coredata.SCIMBridgeStateFailed
+				backoff := r.calculateBackoff(bridge.ConsecutiveFailures)
+				nextSync := now.Add(backoff)
+				bridge.NextSyncAt = &nextSync
+
+				logger.ErrorCtx(ctx, "sync failed, will retry with backoff",
+					log.Duration("sync_duration", duration),
+					log.Int("consecutive_failures", bridge.ConsecutiveFailures),
+					log.Duration("next_retry_in", backoff),
+					log.Error(syncErr),
+				)
+			}
+
+			if err := bridge.Update(ctx, conn, scope); err != nil {
+				logger.ErrorCtx(ctx, "cannot update bridge after failed sync",
+					log.String("new_state", string(bridge.State)),
+					log.Error(err),
+				)
+				return err
+			}
+
+			return nil
+		},
+	)
+}
--- a/pkg/iam/scim/bridge_runner_sync.go
+++ b/pkg/iam/scim/bridge_runner_sync.go
@@ -0,0 +1,173 @@
+// Copyright (c) 2025 Probo Inc <hello@getprobo.com>.
+//
+// Permission to use, copy, modify, and/or distribute this software for any
+// purpose with or without fee is hereby granted, provided that the above
+// copyright notice and this permission notice appear in all copies.
+//
+// THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+// AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+// OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+// PERFORMANCE OF THIS SOFTWARE.
+
+package scim
+
+import (
+	"context"
+	"fmt"
+	"time"
+
+	"go.gearno.de/kit/httpclient"
+	"go.gearno.de/kit/log"
+	"go.gearno.de/kit/pg"
+	"go.probo.inc/probo/pkg/connector"
+	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/iam/scim/bridge"
+	scimclient "go.probo.inc/probo/pkg/iam/scim/bridge/client"
+	"go.probo.inc/probo/pkg/iam/scim/bridge/provider"
+	"go.probo.inc/probo/pkg/iam/scim/bridge/provider/googleworkspace"
+)
+
+func (r *BridgeRunner) executeSync(
+	ctx context.Context,
+	bridge *coredata.SCIMBridge,
+	scope coredata.Scoper,
+	logger *log.Logger,
+) (stats SyncStats, duration time.Duration, connector *coredata.Connector, err error) {
+	start := time.Now()
+
+	err = r.pg.WithConn(
+		ctx,
+		func(conn pg.Conn) error {
+			var syncErr error
+			stats, connector, syncErr = r.doSync(ctx, conn, bridge, scope, logger)
+			return syncErr
+		},
+	)
+
+	duration = time.Since(start)
+	return stats, duration, connector, err
+}
+
+func (r *BridgeRunner) doSync(
+	ctx context.Context,
+	conn pg.Conn,
+	scimBridge *coredata.SCIMBridge,
+	scope coredata.Scoper,
+	logger *log.Logger,
+) (SyncStats, *coredata.Connector, error) {
+	if scimBridge.ConnectorID == nil {
+		return SyncStats{}, nil, fmt.Errorf("bridge has no connector configured")
+	}
+
+	dbConnector := &coredata.Connector{}
+	if err := dbConnector.LoadByID(ctx, conn, scope, *scimBridge.ConnectorID, r.encryptionKey); err != nil {
+		return SyncStats{}, nil, fmt.Errorf("cannot load connector: %w", err)
+	}
+
+	idp, err := r.createProvider(ctx, logger, scimBridge.Type, dbConnector)
+	if err != nil {
+		return SyncStats{}, nil, fmt.Errorf("cannot create provider: %w", err)
+	}
+
+	var scimConfig coredata.SCIMConfiguration
+	if err := scimConfig.LoadByID(ctx, conn, scope, scimBridge.ScimConfigurationID); err != nil {
+		return SyncStats{}, nil, fmt.Errorf("cannot load SCIM configuration: %w", err)
+	}
+
+	token, err := GenerateToken()
+	if err != nil {
+		return SyncStats{}, nil, fmt.Errorf("cannot generate SCIM token: %w", err)
+	}
+
+	scimConfig.HashedToken = HashToken(token)
+	scimConfig.UpdatedAt = time.Now()
+	if err := scimConfig.Update(ctx, conn, scope); err != nil {
+		return SyncStats{}, nil, fmt.Errorf("cannot update SCIM configuration token: %w", err)
+	}
+
+	scimClient := r.createSCIMClient(logger, token)
+	syncer := bridge.NewBridge(idp, scimClient)
+	created, updated, deactivated, skipped, err := syncer.Run(ctx)
+	if err != nil {
+		return SyncStats{}, nil, fmt.Errorf("sync failed: %w", err)
+	}
+
+	stats := SyncStats{
+		Created:     created,
+		Updated:     updated,
+		Deactivated: deactivated,
+		Skipped:     skipped,
+	}
+
+	return stats, dbConnector, nil
+}
+
+func (r *BridgeRunner) createSCIMClient(logger *log.Logger, token string) *scimclient.Client {
+	scimEndpoint := r.cfg.BaseURL.WithPath("/api/connect/v1/scim/2.0").MustString()
+	httpClient := httpclient.DefaultPooledClient(
+		httpclient.WithLogger(logger),
+		httpclient.WithTracerProvider(r.tp),
+		httpclient.WithRegisterer(r.registerer),
+	)
+
+	return scimclient.NewClient(httpClient, scimEndpoint, token)
+}
+
+func (r *BridgeRunner) createProvider(
+	ctx context.Context,
+	logger *log.Logger,
+	bridgeType coredata.SCIMBridgeType,
+	dbConnector *coredata.Connector,
+) (provider.Provider, error) {
+	switch bridgeType {
+	case coredata.SCIMBridgeTypeGoogleWorkspace:
+		return r.createGoogleWorkspaceProvider(ctx, logger, dbConnector)
+	default:
+		return nil, fmt.Errorf("unsupported bridge type: %s", bridgeType)
+	}
+}
+
+func (r *BridgeRunner) createGoogleWorkspaceProvider(
+	ctx context.Context,
+	logger *log.Logger,
+	dbConnector *coredata.Connector,
+) (provider.Provider, error) {
+	if dbConnector.Connection == nil {
+		return nil, fmt.Errorf("connector has no connection configured")
+	}
+
+	oauth2Conn, ok := dbConnector.Connection.(*connector.OAuth2Connection)
+	if !ok {
+		return nil, fmt.Errorf("connector is not an OAuth2 connection")
+	}
+
+	httpClientOpts := []httpclient.Option{
+		httpclient.WithLogger(logger),
+		httpclient.WithTracerProvider(r.tp),
+		httpclient.WithRegisterer(r.registerer),
+	}
+
+	providerName := dbConnector.Provider.String()
+	refreshCfg := r.connectorRegistry.GetOAuth2RefreshConfig(providerName)
+	if refreshCfg == nil {
+		logger.WarnCtx(ctx, "no OAuth2 refresh config found, using static token",
+			log.String("connector_id", dbConnector.ID.String()),
+			log.String("connector_provider", providerName),
+		)
+		httpClient, err := oauth2Conn.ClientWithOptions(ctx, httpClientOpts...)
+		if err != nil {
+			return nil, fmt.Errorf("cannot create HTTP client: %w", err)
+		}
+		return googleworkspace.New(httpClient), nil
+	}
+
+	httpClient, err := oauth2Conn.RefreshableClient(ctx, *refreshCfg, httpClientOpts...)
+	if err != nil {
+		return nil, fmt.Errorf("cannot create refreshable HTTP client: %w", err)
+	}
+
+	return googleworkspace.New(httpClient), nil
+}
--- a/pkg/iam/scim/service.go
+++ b/pkg/iam/scim/service.go
@@ -27,10 +27,14 @@ import (
 	"github.com/elimity-com/scim"
 	scimerrors "github.com/elimity-com/scim/errors"
 	"github.com/elimity-com/scim/optional"
+	"github.com/prometheus/client_golang/prometheus"
 	scimfilter "github.com/scim2/filter-parser/v2"
 	"go.gearno.de/kit/log"
 	"go.gearno.de/kit/pg"
+	"go.opentelemetry.io/otel/trace"
+	"go.probo.inc/probo/pkg/connector"
 	"go.probo.inc/probo/pkg/coredata"
+	"go.probo.inc/probo/pkg/crypto/cipher"
 	"go.probo.inc/probo/pkg/gid"
 	"go.probo.inc/probo/pkg/mail"
 	"go.probo.inc/probo/pkg/page"
@@ -38,21 +42,47 @@ import (

 type (
 	Service struct {
-		pg     *pg.Client
-		logger *log.Logger
+		pg           *pg.Client
+		logger       *log.Logger
+		bridgeRunner *BridgeRunner
+	}
+
+	ServiceConfig struct {
+		TracerProvider    trace.TracerProvider
+		Registerer        prometheus.Registerer
+		EncryptionKey     cipher.EncryptionKey
+		ConnectorRegistry *connector.ConnectorRegistry
+		BridgeRunner      BridgeRunnerConfig
 	}
 )

 func NewService(
 	pg *pg.Client,
 	logger *log.Logger,
+	cfg ServiceConfig,
 ) *Service {
+	bridgeRunner := NewBridgeRunner(
+		pg,
+		logger.Named("bridge-runner"),
+		cfg.TracerProvider,
+		cfg.Registerer,
+		cfg.EncryptionKey,
+		cfg.ConnectorRegistry,
+		cfg.BridgeRunner,
+	)
+
 	return &Service{
-		pg:     pg,
-		logger: logger,
+		pg:           pg,
+		logger:       logger,
+		bridgeRunner: bridgeRunner,
 	}
 }

+// Run starts the SCIM service background processes.
+func (s *Service) Run(ctx context.Context) error {
+	return s.bridgeRunner.Run(ctx)
+}
+
 func HashToken(token string) []byte {
 	hash := sha256.Sum256([]byte(token))
 	return hash[:]