# Security Considerations for MetaMCP's OIDC Implementation: A Complete Guide

> Learn about MetaMCP OIDC security considerations. Discover PKCE enforcement, auto-discovery, and runtime flags for a robust SSO architecture. Secure your implementation today.

- Repository: [metatool-ai/metamcp](https://github.com/metatool-ai/metamcp)
- Tags: best-practices
- Published: 2026-03-07

---

**MetaMCP enforces PKCE by default for all OIDC flows, uses auto-discovery to eliminate endpoint misconfiguration, and provides runtime feature flags to disable basic authentication and granularly control user registration, creating a defense-in-depth SSO architecture.**

MetaMCP, the open-source AI tool management platform from `metatool-ai/metamcp`, integrates OpenID Connect (OIDC) as a first-class authentication provider using the `better-auth` library. Understanding the security considerations for MetaMCP's OIDC implementation is essential for administrators deploying single sign-on in production, as the platform combines modern OAuth 2.0 best practices with flexible runtime controls that adapt to varying threat models.

## Core OIDC Security Architecture

### PKCE Enforcement and Authorization Flow Protection

MetaMCP's OIDC implementation mandates **Proof Key for Code Exchange (PKCE)** to protect against authorization code interception attacks. In [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts), the `pkce` parameter defaults to `true` unless explicitly disabled via the `OIDC_PKCE` environment variable set to `"false"` (lines 44–45).

```typescript
// apps/backend/src/auth.ts – PKCE configuration
pkce: process.env.OIDC_PKCE !== "false", // Defaults to true for security

```

This default behavior ensures that even if administrators omit PKCE configuration, the authorization code flow remains protected against malicious actors intercepting codes on public clients or compromised networks.

### Auto-Discovery and Endpoint Validation

The implementation leverages **OpenID Connect Discovery** to automatically retrieve provider metadata, eliminating manual endpoint configuration errors. The `discoveryUrl` parameter reads from `OIDC_DISCOVERY_URL` (line 45), while the `authorizationUrl` explicitly uses `OIDC_AUTHORIZATION_URL` to work around a known limitation in `better-auth` (line 46).

```typescript
// apps/backend/src/auth.ts – Endpoint configuration
discoveryUrl: process.env.OIDC_DISCOVERY_URL,
authorizationUrl: process.env.OIDC_AUTHORIZATION_URL, // Required by better-auth

```

By validating HTTPS-only discovery documents and enforcing explicit authorization endpoints, MetaMCP prevents man-in-the-middle attacks that could redirect authentication flows to attacker-controlled servers.

### Scope Restriction and Minimal Data Access

MetaMCP follows the principle of least privilege by requesting only essential scopes. The default `scopes` array includes `openid`, `email`, and `profile` (line 43), providing sufficient identity information without requesting unnecessary permissions that could expand the attack surface in case of token leakage.

```typescript
// apps/backend/src/auth.ts – Scope configuration
scopes: (process.env.OIDC_SCOPES || "openid email profile").split(" "),

```

## Runtime Security Controls and Configuration

### Disabling Basic Authentication

Administrators can enforce OIDC-only authentication by disabling basic email/password login. The `DISABLE_BASIC_AUTH` flag in [`apps/backend/src/lib/config.service.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/lib/config.service.ts) (lines 36–44) blocks traditional authentication routes when enabled, preventing fallback to weaker credential-based authentication in SSO-mandated environments.

### Fine-Grained Sign-Up Restrictions

MetaMCP provides distinct controls for user registration through [`config.service.ts`](https://github.com/metatool-ai/metamcp/blob/main/config.service.ts):

- **`DISABLE_SIGNUP`**: Blocks all UI-driven account creation (lines 5–12)
- **`DISABLE_SSO_SIGNUP`**: Specifically prevents new account creation via OIDC/OAuth while allowing existing users to authenticate (lines 21–28)

The authentication middleware in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts) implements these checks in user creation hooks (lines 35–57), throwing explicit errors when registration attempts violate the current policy:

```typescript
// apps/backend/src/auth.ts – Registration guard implementation
const isSsoRegistration =
  context?.path?.includes("/callback/") ||
  context?.path?.includes("/oauth/") ||
  context?.path?.includes("/oidc/");

if (isSsoRegistration) {
  if (isSsoSignupDisabled) {
    throw new Error("New user registration via SSO/OAuth is currently disabled.");
  }
} else {
  if (isSignupDisabled) {
    throw new Error("New user registration is currently disabled.");
  }
}

```

### Environment Variable Hygiene

All OIDC credentials load exclusively from environment variables at runtime. The configuration in [`auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/auth.ts) (lines 38–51) conditionally registers the OIDC provider only when both `OIDC_CLIENT_ID` and `OIDC_CLIENT_SECRET` are present, preventing partial configuration that could lead to authentication bypasses.

Required environment variables include:
- `OIDC_CLIENT_ID`
- `OIDC_CLIENT_SECRET`
- `OIDC_DISCOVERY_URL`
- `OIDC_AUTHORIZATION_URL`

Source: [`README.md`](https://github.com/metatool-ai/metamcp/blob/main/README.md) OIDC configuration section (lines 62–73) and `example.env`.

## Session Management and Cookie Security

MetaMCP configures `better-auth` with security-focused session parameters in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts):

- **Session Expiry**: Tokens expire after 7 days (`session.expiresIn`, line 112)
- **Token Rotation**: Sessions refresh daily (`session.updateAge`, line 113)
- **Cross-Subdomain Support**: Cookies work across subdomains when enabled (`crossSubDomainCookies.enabled`, lines 124–126)

These settings limit the window for session hijacking while maintaining usability in multi-subdomain deployments.

## Configuration Examples for Secure Deployment

### Enabling OIDC with PKCE

```bash

# .env configuration

OIDC_CLIENT_ID=your-client-id
OIDC_CLIENT_SECRET=your-client-secret
OIDC_DISCOVERY_URL=https://auth.example.com/.well-known/openid-configuration
OIDC_AUTHORIZATION_URL=https://auth.example.com/oauth2/authorize
OIDC_PKCE=true
OIDC_SCOPES=openid email profile

```

### Locking Down Registration

```bash

# Disable all sign-ups except existing OIDC users

DISABLE_SIGNUP=true
DISABLE_SSO_SIGNUP=false
DISABLE_BASIC_AUTH=true

```

## Summary

MetaMCP's OIDC implementation provides enterprise-grade security through multiple defensive layers:

- **PKCE enforcement** protects authorization codes from interception attacks by default
- **Auto-discovery** with HTTPS validation prevents endpoint misconfiguration and man-in-the-middle attacks
- **Runtime feature flags** allow administrators to disable basic auth, UI sign-up, or SSO registration without code changes
- **Secure session management** with 7-day expiry and daily rotation limits exposure from stolen tokens
- **Environment-only secrets** ensure credentials never leak through source control

By leveraging these controls in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts) and [`apps/backend/src/lib/config.service.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/lib/config.service.ts), operators can deploy OIDC authentication that aligns with zero-trust principles while maintaining flexibility for diverse organizational requirements.

## Frequently Asked Questions

### Is PKCE mandatory in MetaMCP's OIDC implementation?

PKCE is enabled by default and effectively mandatory for secure deployments. While the `OIDC_PKCE` environment variable can explicitly disable it by setting the value to `"false"`, the default configuration in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts) (line 44) sets `pkce: process.env.OIDC_PKCE !== "false"`, ensuring protection against authorization code interception attacks unless an administrator explicitly opts out.

### How can I disable basic authentication when using OIDC?

Set the `DISABLE_BASIC_AUTH` environment variable or use the configuration service to enable this flag. When active, MetaMCP blocks all email and password authentication routes, forcing users to authenticate exclusively through the configured OIDC provider. This prevents fallback attacks where users might bypass SSO using local credentials. The check occurs in the authentication middleware defined in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts).

### What environment variables are required for secure OIDC configuration?

At minimum, you must provide `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET`, `OIDC_DISCOVERY_URL`, and `OIDC_AUTHORIZATION_URL`. Optional but recommended variables include `OIDC_PKCE` (set to `true`), `OIDC_SCOPES` (defaults to `openid email profile`), and `OIDC_PROVIDER_ID` (defaults to `oidc`). These are loaded at runtime from [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts) and should never be committed to source control, as demonstrated in the `example.env` template.

### Can I prevent new user registration while keeping OIDC login active for existing users?

Yes, by setting `DISABLE_SSO_SIGNUP` to `true` while keeping `DISABLE_SIGNUP` and `DISABLE_BASIC_AUTH` configured according to your needs. This configuration allows existing users to authenticate via OIDC but blocks the creation of new accounts through SSO, effectively enforcing a closed user base. The registration guard in [`apps/backend/src/auth.ts`](https://github.com/metatool-ai/metamcp/blob/main/apps/backend/src/auth.ts) (lines 35-57) distinguishes between SSO and UI registration attempts to enforce these policies independently.