stacklok / toolhive / 21189106084

push

github

Add UserStorage interface to authserver for multi-IDP support (#3358)

Add UserStorage interface for multi-IDP support

The primary goal of this change is to provide a stable, unique "sub" claim
for tokens issued by ToolHive's authorization server, decoupled from any
specific upstream identity provider (IDP).

Without an internal user identity layer, ToolHive would be tightly coupled
to a single upstream IDP. The upstream provider's "sub" claim would flow
directly into issued tokens, creating problems:

- Changing or adding IDP providers would break existing user identities
- No path to supporting multiple IDPs (e.g., Google AND GitHub)
- The "sub" claim in issued tokens would be outside our control

Moreover, with pure OAuth providers we would /need/ to have a "sub"
claim in the upstream token to use it in the first place. This was
already hit by Trey and Gautam with Atlassian.

Introduce an internal User identity with a stable ID that becomes the "sub"
claim in all ToolHive-issued tokens. The upstream provider's subject is
stored separately in ProviderIdentity, creating an abstraction layer:

```
Upstream IDP          ToolHive                    Downstream
============          ========                    ==========
                      User.ID=uuid-xxx --------> JWT sub=uuid-xxx
                           ^
Google sub=abc123 -----> ProviderIdentity
GitHub sub=def456 -----> ProviderIdentity (future: multi-IDP support)
```

This enables:
- Adding new IDP providers without affecting existing users
- Future account linking (one user, multiple providers)
- Consistent "sub" claim regardless of authentication method

- New User and ProviderIdentity types with UserStorage interface
- UpstreamTokens now tracks ProviderID and separates UserID from UpstreamSubject
- DeleteUser cascades to remove associated ProviderIdentities and UpstreamTokens
- MemoryStorage implementation with full test coverage

This storage layer will be used by the OAuth callback handle... (continued)

152 of 306 new or added lines in 2 files covered. (49.67%)

36276 of 60949 relevant lines covered (59.52%)

79.15 hits per line