1764 Idp Provider Support 754adbcb

# Multi-Provider Identity Provider (IdP) Support

**Version:** 1.0
**Last Updated:** 2026-01-18

## Related Documentation

- [Authentication Design](./authentication-design.md) - Auth flows for human users, programmatic access, and M2M workloads
- [Authentication & Authorization Guide](../auth.md) - Operational guide with setup instructions
- [Microsoft Entra ID Integration](../entra.md) - Entra ID-specific setup and configuration

## Overview

The MCP Gateway Registry supports multiple identity providers (IdPs) through a pluggable architecture. This design enables organizations to use their existing enterprise identity infrastructure (Keycloak, Microsoft Entra ID) for authentication and authorization.

## Architecture

### High-Level Component Diagram

```
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|   Registry UI    |     |   CLI Tools      |     |   AI Agents      |
|   (Frontend)     |     | (registry_mgmt)  |     |  (M2M Clients)   |
|                  |     |                  |     |                  |
+--------+---------+     +--------+---------+     +--------+---------+
         |                        |                        |
         |   HTTP + JWT Token     |   HTTP + JWT Token     |
         |                        |                        |
         v                        v                        v
+--------+------------------------+------------------------+---------+
|                                                                    |
|                         NGINX Gateway                              |
|                     (auth_request /validate)                       |
|                                                                    |
+--------+-----------------------------------------------------------+
         |
         | /validate
         v
+--------+-----------------------------------------------------------+
|                                                                    |
|                         Auth Server                                |
|                                                                    |
|  +----------------+    +------------------+    +----------------+  |
|  |                |    |                  |    |                |  |
|  | AuthProvider   |    | AuthProvider     |    | AuthProvider   |  |
|  | Factory        +--->+ Protocol         +--->+ Implementations|  |
|  |                |    | (Base Class)     |    |                |  |
|  +----------------+    +------------------+    +----------------+  |
|                                                      |             |
|                           +----------------+---------+             |
|                           |                |                       |
|                           v                v                       |
|                    +------+------+  +------+------+                |
|                    |             |  |             |                |
|                    |  Keycloak   |  |  Entra ID   |                |
|                    |  Provider   |  |  Provider   |                |
|                    |             |  |             |                |
|                    +-------------+  +-------------+                |
|                                                                    |
+--------------------------------------------------------------------+
         |
         | Group-to-Scope Mapping
         v
+--------+-----------------------------------------------------------+
|                                                                    |
|               MongoDB-CE / Amazon DocumentDB                       |
|                                                                    |
|  +---------------------------+  +---------------------------+      |
|  | mcp_scopes_default        |  | mcp_servers_default       |      |
|  |                           |  |                           |      |
|  | - scope definitions       |  | - server configurations   |      |
|  | - group_mappings          |  | - tool definitions        |      |
|  | - server_access rules     |  |                           |      |
|  | - ui_permissions          |  |                           |      |
|  +---------------------------+  +---------------------------+      |
|                                                                    |
+--------------------------------------------------------------------+
```

## Provider Selection

The active identity provider is determined by the `AUTH_PROVIDER` environment variable:

```
AUTH_PROVIDER=keycloak   # Use Keycloak
AUTH_PROVIDER=entra      # Use Microsoft Entra ID
```

### Provider Factory Pattern

```
+-------------------+     +--------------------------+
|                   |     |                          |
| AUTH_PROVIDER env +---->+  AuthProviderFactory     |
|                   |     |                          |
+-------------------+     +------------+-------------+
                                       |
                    +------------------+------------------+
                    |                                     |
                    v                                     v
          +---------+---------+              +-----------+-----------+
          |                   |              |                       |
          | KeycloakProvider  |              |  EntraIdProvider      |
          |                   |              |                       |
          | - OIDC endpoints  |              | - Microsoft Graph API |
          | - JWKS validation |              | - JWKS validation     |
          | - Realm-based     |              | - Tenant-based        |
          |                   |              |                       |
          +-------------------+              +-----------------------+
```

## IAM Manager Interface

For administrative operations (user/group CRUD), the system uses the IAM Manager abstraction:

```python
@runtime_checkable
class IAMManager(Protocol):
    """Protocol defining the IAM manager interface."""

    async def list_users(
        self,
        search: str | None = None,
        max_results: int = 500,
        include_groups: bool = True
    ) -> list[dict[str, Any]]: ...

    async def create_human_user(
        self,
        username: str,
        email: str,
        first_name: str,
        last_name: str,
        groups: list[str],
        password: str | None = None,
    ) -> dict[str, Any]: ...

    async def delete_user(self, username: str) -> bool: ...

    async def list_groups(self) -> list[dict[str, Any]]: ...

    async def create_group(
        self,
        group_name: str,
        description: str = ""
    ) -> dict[str, Any]: ...

    async def delete_group(self, group_name: str) -> bool: ...

    async def create_service_account(
        self,
        client_id: str,
        groups: list[str],
        description: str | None = None
    ) -> dict[str, Any]: ...
```

### Implementation Classes

```
+------------------+          +------------------+
|                  |          |                  |
| KeycloakIAM      |          | EntraIAM         |
| Manager          |          | Manager          |
|                  |          |                  |
+--------+---------+          +--------+---------+
         |                             |
         | Delegates to                | Delegates to
         v                             v
+--------+---------+          +--------+---------+
|                  |          |                  |
| keycloak_manager |          | entra_manager    |
| .py              |          | .py              |
|                  |          |                  |
| - Keycloak Admin |          | - Microsoft      |
|   REST API       |          |   Graph API      |
| - Realm mgmt     |          | - App registr.   |
| - Client mgmt    |          | - Service        |
|                  |          |   principals     |
+------------------+          +------------------+
```

## Provider-Specific Details

### Keycloak Provider

**Authentication Flow:**
- Uses OIDC Authorization Code flow
- Tokens issued by Keycloak realm
- JWKS endpoint: `{keycloak_url}/realms/{realm}/protocol/openid-connect/certs`

**Group Identifier in Tokens:**
- Group names (e.g., `registry-admins`, `public-mcp-users`)
- Stored in `groups` claim of JWT

**IAM Operations:**
- Uses Keycloak Admin REST API
- Requires admin credentials or service account with realm-admin role

### Microsoft Entra ID Provider

**Authentication Flow:**
- Uses OAuth2 Authorization Code flow (users)
- Uses OAuth2 Client Credentials flow (M2M)
- Tokens issued by Microsoft STS
- JWKS endpoint: `https://login.microsoftonline.com/{tenant_id}/discovery/v2.0/keys`

**Group Identifier in Tokens:**
- Group Object IDs (GUIDs) like `5f605d68-06bc-4208-b992-bb378eee12c5`
- Stored in `groups` claim of JWT
- Object IDs must be mapped to scope names in MongoDB

**IAM Operations:**
- Uses Microsoft Graph API
- Requires App Registration with appropriate permissions:
  - `Application.ReadWrite.All`
  - `Directory.ReadWrite.All`
  - `Group.ReadWrite.All`
  - `User.ReadWrite.All`

## Group-to-Scope Mapping

The mapping between IdP groups and registry scopes is stored in MongoDB-CE/Amazon DocumentDB (`mcp_scopes_default` collection):

```
+---------------------------------------------------+
| MongoDB-CE/Amazon DocumentDB: mcp_scopes_default  |
+---------------------------------------------------+
| Document Structure:                               |
|                                                   |
| {                                         |
|   "_id": "registry-admins",               |  <-- Scope name
|   "group_mappings": [                     |
|     "registry-admins",                    |  <-- Keycloak group name
|     "4c46ec66-a4f7-4b62-9095-..."         |  <-- Entra ID group Object ID
|   ],                                      |
|   "server_access": [ ... ],               |  <-- MCP server permissions
|   "ui_permissions": { ... }               |  <-- UI feature access
| }                                         |
+-------------------------------------------+
```

### Mapping Flow

```
+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|  JWT Token       |     |  Scope           |     |  Access          |
|  from IdP        +---->+  Repository      +---->+  Decision        |
|                  |     |                  |     |                  |
+------------------+     +------------------+     +------------------+
        |                        |                        |
        | groups claim:          | Query:                 | Result:
        | ["5f605d68-..."]       | Find scopes where      | scopes=["public-
        |                        | group_mappings         |  mcp-users"]
        |                        | contains "5f605d68-"   |
        v                        v                        v

Keycloak example:              Entra ID example:
groups: ["public-mcp-users"]   groups: ["5f605d68-06bc-4208-b992-bb378eee12c5"]
        |                              |
        +------------------------------+
                      |
                      v
              +-------+-------+
              |               |
              | Mapped to:    |
              | public-mcp-   |
              | users scope   |
              |               |
              +---------------+
```

## Configuration

### Environment Variables

```bash
# Provider Selection
AUTH_PROVIDER=entra              # or "keycloak"

# Keycloak Configuration
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM=mcp-gateway
KEYCLOAK_CLIENT_ID=mcp-registry
KEYCLOAK_CLIENT_SECRET=...

# Entra ID Configuration
ENTRA_TENANT_ID=6e6ee81b-6bf3-495d-a7fc-d363a551f765
ENTRA_CLIENT_ID=1bd17ba1-aad3-447f-be0b-26f8f9ee859f
ENTRA_CLIENT_SECRET=...

# Token Validation
SECRET_KEY=...                   # For self-signed tokens
JWT_ISSUER=mcp-auth-server
JWT_AUDIENCE=mcp-registry
```

### Scopes Configuration (scopes.yml or MongoDB)

```yaml
# Group mappings - maps IdP group identifiers to scope names
group_mappings:
  # Entra ID uses Object IDs (GUIDs)
  "4c46ec66-a4f7-4b62-9095-b7958662f4b6":
    - registry-admins
    - mcp-servers-unrestricted/read
    - mcp-servers-unrestricted/execute

  "5f605d68-06bc-4208-b992-bb378eee12c5":
    - public-mcp-users

  # Keycloak uses group names
  "registry-admins":
    - registry-admins

  "public-mcp-users":
    - public-mcp-users
```

## Adding a New Provider

To add support for a new identity provider:

1. **Create Provider Class** (`auth_server/providers/new_provider.py`):
   - Implement `AuthProvider` base class
   - Handle OIDC/OAuth2 flows
   - Implement token validation via JWKS

2. **Create IAM Manager** (`registry/utils/new_provider_manager.py`):
   - Implement user/group CRUD operations
   - Handle provider-specific API calls

3. **Update Factory** (`registry/utils/iam_manager.py`):
   - Add new provider case to `get_iam_manager()`

4. **Update Auth Factory** (`auth_server/providers/factory.py`):
   - Add new provider case to factory function

5. **Configure Group Mappings**:
   - Add group identifiers to `scopes.yml` or MongoDB-CE/Amazon DocumentDB
   - Document group identifier format (names vs IDs)

## Security Considerations

1. **Token Validation**: Always validate JWT signatures against provider JWKS
2. **Admin Credentials**: Store IdP admin credentials securely (environment variables, secrets manager)
3. **Principle of Least Privilege**: Request minimal permissions for IAM operations
4. **Eventual Consistency**: Handle Entra ID's eventual consistency with retry logic
5. **Token Expiry**: Respect token expiration times; implement refresh where needed