> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mlm-platform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# External Auth Providers

> Configure OIDC federation to allow users from your external system to access the MLM Platform

# External Auth Providers

External auth providers enable **federated authentication** between your application and the MLM Platform. This allows users authenticated by your identity provider to seamlessly access MLM Platform features without creating separate credentials.

## Overview

When you configure an external auth provider, users can:

1. Authenticate with your identity provider (IdP)
2. Exchange their JWT token for an MLM Platform token
3. Access MLM Platform APIs and features using the exchanged token

This is ideal for scenarios where:

* You have an existing user base with established authentication
* You want single sign-on (SSO) between your app and the MLM Platform
* You need to integrate MLM features into your existing application

## Prerequisites

Before configuring an external auth provider, ensure you have:

* An OIDC-compliant identity provider (e.g., Auth0, Okta, Azure AD, Cognito, Supabase Auth)
* Access to your IdP's configuration (issuer URL, JWKS endpoint)
* The audience value(s) configured in your IdP for tokens

## Initial Setup (For MLM Platform Admins)

When onboarding a new tenant, MLM Platform administrators can configure the initial external auth provider during tenant creation. The following information is required from the tenant:

### Required Information

| Field                 | Description                         | Example                                          |
| --------------------- | ----------------------------------- | ------------------------------------------------ |
| **Provider ID**       | Unique identifier for this provider | `my-app`, `production-auth`                      |
| **Display Name**      | Human-readable name                 | `My Application`                                 |
| **Issuer URL**        | OIDC issuer URL (must be HTTPS)     | `https://auth.example.com`                       |
| **JWKS URI**          | JSON Web Key Set endpoint           | `https://auth.example.com/.well-known/jwks.json` |
| **Allowed Audiences** | Valid audience values in tokens     | `api://my-app`, `https://api.example.com`        |

### Optional Configuration

| Field                       | Default    | Description                                                     |
| --------------------------- | ---------- | --------------------------------------------------------------- |
| **Auto-create Users**       | `true`     | Automatically create MLM Platform users on first token exchange |
| **Default Membership Tier** | `ORDINARY` | Tier assigned to auto-created users                             |
| **User ID Claim**           | `sub`      | JWT claim containing the user's external ID                     |
| **Email Claim**             | `email`    | JWT claim containing the user's email                           |
| **Name Claim**              | `name`     | JWT claim containing the user's display name                    |

## Managing Providers via API

Tenant administrators can manage external auth providers using the Admin API.

### List Providers

```bash theme={null}
GET /api/v1/admin/auth/providers
Authorization: Bearer <admin-token>
```

### Create or Update Provider

```bash theme={null}
POST /api/v1/admin/auth/providers
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "provider_id": "my-app",
  "display_name": "My Application",
  "issuer": "https://auth.example.com",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "allowed_audiences": ["api://my-app"],
  "auto_create_users": true,
  "default_membership_tier": "ORDINARY",
  "user_id_claim": "sub",
  "email_claim": "email",
  "name_claim": "name",
  "is_active": true
}
```

### Response

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "provider_id": "my-app",
  "display_name": "My Application",
  "issuer": "https://auth.example.com",
  "jwks_uri": "https://auth.example.com/.well-known/jwks.json",
  "allowed_audiences": ["api://my-app"],
  "auto_create_users": true,
  "default_membership_tier": "ORDINARY",
  "is_active": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

## Token Exchange Flow

Once configured, your application can exchange tokens using the `/api/v1/auth/exchange` endpoint:

```bash theme={null}
POST /api/v1/auth/exchange
Content-Type: application/json
X-Tenant-ID: <tenant-id>

{
  "provider": "my-app",
  "token": "<jwt-from-your-idp>"
}
```

### Successful Response

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "user-uuid",
    "email": "user@example.com",
    "name": "John Doe",
    "membership_tier": "ORDINARY"
  }
}
```

## Security Considerations

### HTTPS Required

All URLs (issuer, JWKS URI) must use HTTPS. This ensures:

* Token verification requests are encrypted
* JWKS responses cannot be tampered with
* Man-in-the-middle attacks are prevented

### Audience Validation

The `allowed_audiences` field restricts which tokens are accepted. Only tokens with an `aud` claim matching one of the allowed values will be exchanged. This prevents:

* Tokens issued for other services being used
* Cross-tenant token reuse

### Token Expiration

Exchanged tokens have their own expiration independent of the original token. The MLM Platform issues:

* Access tokens: 1 hour validity
* Refresh tokens: 7 days validity

## Troubleshooting

### "External provider not configured"

This error occurs when:

* The `provider` value in the exchange request doesn't match any configured provider
* The provider exists but is marked as inactive

**Solution**: Verify the provider ID matches exactly and the provider is active.

### "Invalid token signature"

This error occurs when:

* The JWKS URI is incorrect or unreachable
* The token was signed with a key not in the JWKS
* The token has been tampered with

**Solution**: Verify the JWKS URI is correct and accessible from the MLM Platform servers.

### "Audience mismatch"

This error occurs when:

* The token's `aud` claim doesn't match any allowed audience

**Solution**: Add the token's audience value to the `allowed_audiences` list.

## Managing Providers in the Admin UI

Tenant administrators can also manage external auth providers through the **Developers** page in the admin dashboard:

1. Navigate to **Developers** in the admin navigation
2. Find the **External Auth Providers** section
3. Click **Add Provider** to create a new provider
4. Fill in the required fields and click **Create Provider**

The UI provides the same functionality as the API with a user-friendly interface.