Skip to main content

​
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

FieldDescriptionExample
Provider IDUnique identifier for this providermy-app, production-auth
Display NameHuman-readable nameMy Application
Issuer URLOIDC issuer URL (must be HTTPS)https://auth.example.com
JWKS URIJSON Web Key Set endpointhttps://auth.example.com/.well-known/jwks.json
Allowed AudiencesValid audience values in tokensapi://my-app, https://api.example.com

​
Optional Configuration

FieldDefaultDescription
Auto-create UserstrueAutomatically create MLM Platform users on first token exchange
Default Membership TierORDINARYTier assigned to auto-created users
User ID ClaimsubJWT claim containing the user’s external ID
Email ClaimemailJWT claim containing the user’s email
Name ClaimnameJWT claim containing the user’s display name

​
Managing Providers via API

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

​
List Providers

GET /api/v1/admin/auth/providers
Authorization: Bearer <admin-token>

​
Create or Update Provider

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

{
  "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: 
POST /api/v1/auth/exchange
Content-Type: application/json
X-Tenant-ID: <tenant-id>

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

​
Successful Response

{
  "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.