Configuring OAuth 2.0 and OIDC Authentication¶

The Actian MCP Server supports OAuth 2.0 and OpenID Connect (OIDC) authentication. When you enable this feature, every client request must include a valid JSON Web Token (JWT) issued by a trusted identity provider (IdP).

Working with OAuth¶

The Actian MCP Server acts as an OIDC Relying Party by redirecting unauthenticated AI clients to the identity provider for secure login and token issuance. Once authenticated, the client includes this bearer token in all subsequent requests, allowing the server to validate the session and securely fulfill database queries.

%%{init: {'theme': 'dark', 'themeVariables': {'fontSize': '18px', 'fontFamily': 'arial'}}}%%
sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server (OIDCProxy)
    participant Browser as Browser
    participant IdP as Identity Provider (Auth0 / Keycloak)

    Client->>Server: Connect (no token)
    Server->>Browser: Redirect to IdP login
    Browser->>IdP: User enters credentials
    IdP->>Browser: Authorization code
    Browser->>Server: Callback with auth code
    Server->>IdP: Exchange code for tokens
    IdP->>Server: Access token + ID token
    Server->>Client: Session established

    loop Every request
        Client->>Server: Request + Bearer token
        Server->>Server: Validate JWT
        Server->>Client: Response
    end

Configuring oauth Block¶

To enable authentication, add an oauth object to the conf.json file. The server reads the following data during startup:

Example¶

{
  "oauth": {
    "FASTMCP_SERVER_AUTH_CONFIG_URL": "https://dev-abc123.us.auth0.com/.well-known/openid-configuration",
    "FASTMCP_SERVER_AUTH_CLIENT_ID": "wNXUdrp9aBcDeFgHiJkLmN",
    "FASTMCP_SERVER_AUTH_CLIENT_SECRET": "a1B2c3D4e5F6g7H8i9J0kLmNoPqRsTuVwXyZ",
    "FASTMCP_SERVER_AUTH_BASE_URL": "https://<mcp-server-host>:8000",
    "FASTMCP_SERVER_AUTH_AUDIENCE": "<your-audience>",
    "user_impersonation": true
  }
}

User Impersonation¶

By default, the user_impersonation field is set to true. The server extracts a username from the authenticated user's JWT and runs SET SESSION AUTHORIZATION "<username>" before executing a database query. This ensures users only interact with data their specific database account is permitted to see.

Extracting Username¶

When user impersonation is active, the server extracts the database username from the token using the following priority order:

%%{init: {'theme': 'default', 'themeVariables': {'fontSize': '16px', 'fontFamily': 'arial'}}}%%
flowchart TD
    A[Incoming Request with JWT] --> B{user_impersonation?}
    B -- false --> C[Run query as service account]
    B -- true --> D[Query userinfo endpoint]
    D --> E{username claim?}
    E -- found --> K[Use username]
    E -- not found --> F{preferred_username?}
    F -- found --> K
    F -- not found --> G{email claim?}
    G -- found --> H["Extract prefix (jdoe@example.com → jdoe)"]
    H --> K
    G -- not found --> I{sub claim?}
    I -- found --> J["Sanitize sub (auth0|12345 → 12345)"]
    J --> K
    K --> L["SET SESSION AUTHORIZATION 'username'"]
    L --> M[Execute query]

Secure Remote Deployments with HTTPS and TLS¶

OAuth 2.0 requires HTTPS. If you configure OAuth, the server mandates HTTPS and refuses to start unless you provide the ssl_certfile and ssl_keyfile paths.

Step 1: Generate a Certificate¶

For remote testing, generate a self-signed certificate with a Subject Alternative Name (SAN).

openssl req -x509 -newkey rsa:4096 -keyout server.key -out server.crt \
  -days 365 -nodes \
  -subj "/CN=<your-ip-or-hostname>" \
  -addext "subjectAltName=IP:<your-ip>"
chmod 600 server.key

Step 2: Configure TLS in conf.json¶

Add the ssl_certfile certificate and ssl_keyfile key paths to the top level of the conf.json file (outside the oauth block). Ensure the usage of https:// in BASE_URL:

{
  "ssl_certfile": "/app/server.crt",
  "ssl_keyfile": "/app/server.key",
  "oauth": {
    "FASTMCP_SERVER_AUTH_BASE_URL": "https://<your-ip-or-hostname>:8000"
  }
}

The server validates the existance of both paths at startup, and the usage of https:// for BASE_URL when SSL is active.

Step 3: Deploy the Docker¶

Mount the certificate and key into the container using volume flags:

docker run -p 8000:8000 \
  -v /path/to/server.crt:/app/server.crt:ro \
  -v /path/to/server.key:/app/server.key:ro \
  -v /path/to/conf.json:/app/conf.json:ro \
  actian/analytics-engine-mcp-server:latest

Reference the container paths in conf.json:

{
  "ssl_certfile": "/app/server.crt",
  "ssl_keyfile": "/app/server.key"
}

Step 4: Trust the Certificate in the MCP Client¶

By default, Node.js-based MCP clients (VS Code and Cursor) reject self-signed certificates. You must explicitly trust the certificate on your development machine.

1. Securely copy the certificate to your machine:

     scp user@<your-vm>:/path/to/server.crt ~/server.crt
   

2. Configure the operating system:

# Add to system keychain
sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/server.crt

# Ensure VS Code's Node.js runtime picks it up
launchctl setenv NODE_EXTRA_CA_CERTS "$HOME/server.crt"

# Fully restart VS Code (Cmd+Q, then reopen)

sudo cp ~/server.crt /usr/local/share/ca-certificates/mcp-server.crt
sudo update-ca-certificates

# For VS Code / Node.js:
export NODE_EXTRA_CA_CERTS="$HOME/server.crt"
# Add to ~/.bashrc or ~/.profile to persist across sessions

# Import into Trusted Root store (run PowerShell as Administrator)
Import-Certificate -FilePath "$env:USERPROFILE\server.crt" `
  -CertStoreLocation Cert:\LocalMachine\Root

# For VS Code / Node.js:
[System.Environment]::SetEnvironmentVariable(
  "NODE_EXTRA_CA_CERTS",
  "$env:USERPROFILE\server.crt",
  "User"
)

# Fully restart VS Code after setting the variable

Security Best Practices¶

Provider Setup Guides¶

Choose your identity provider for step-by-step setup instructions: