Configuring Auth0¶

Set up an Auth0 application and API to enable OAuth 2.0 and OpenID Connect (OIDC) authentication for your Actian MCP Server. After you complete these steps, you can see the credentials required for the oauth block in the conf.json configuration file.

For details on shared security concepts like TLS and user impersonation, see Authentication Overview.

Quick Start - Existing Auth0 User¶

If you are an experienced Auth0 user, use the following checklist to set up the environment:

1. Create an API: Navigate to Applications > APIs > Create API. The Identifier serves as the FASTMCP_SERVER_AUTH_AUDIENCE.
2. Create an Application: Navigate to Applications > Applications > Create Application. Select Machine to Machine. Authorize it for the API when prompted. Copy the Client ID and Client Secret.

3. Authorize the Application: In your API settings, verify that User Access and Client Access are set to Authorized.

   Warning

   If you skip this step, Auth0 returns an invalid_request error.

4. Enable Authorization Code Grant: In Advanced Settings > Grant Types, select Authorization Code.

5. Set Callback URLs: Add <BASE_URL>/auth/callback to Allowed Callback URLs.
6. Update Configuration: Add your Auth0 domain and credentials to conf.json.
7. Start the server: Launch the server using the --transport sse or http / streamable-http flag.

Prerequisites - New Auth0 User¶

• An Auth0 account (sign up free).
• An Auth0 Tenant (created automatically on sign-up, for example, dev-abc123).
• Actian MCP Server installed and ready to run.

Step 1: Create an Auth0 API¶

The API represents the Actian MCP Server as a protected resource in Auth0. Tokens issued by Auth0 include the API's identifier as the audience claim.

1. Log in to the Auth0 Dashboard.
2. In the left sidebar, navigate to Applications > APIs**.
3. Select + Create API.

4. Fill the form as follows:

   Field	Value	Notes
   Name	Actian MCP Server	Display name (any descriptive string).
   Identifier (Audience)	https://<mcp-server-host>:8000/mcp	Logical identifier (may not be a reachable URL). This becomes your FASTMCP_SERVER_AUTH_AUDIENCE.
   Signing Algorithm	RS256	Default, leave the value as is.

5. Select Create.

Output of Step 1¶

Step 2: Create an Auth0 Application¶

The Application represents the MCP server's OAuth client. It holds client_id and client_secret used during the OAuth handshake.

1. In the Auth0 Dashboard, navigate to Applications > Applications.
2. Select + Create Application.

3. Enter the values for the following fields:

   Field	Value
   Name	Actian MCP Server App
   Application Type	Machine to Machine Applications

4. Select Create.

5. When prompted, select your Actian MCP Server API and grant all scopes (You can also do this later in Step 3.
6. The application's Settings tab opens.

Configure Application Settings¶

On the Settings tab, configure the following:

Select Save Changes.

Configure Grant Types¶

Machine to Machine applications should have Authorization Code enabled by default, but you should always verify since some tenants or configurations may differ.

1. On the Settings tab, select Show Advanced Settings.
2. Select the Grant Types tab.
3. Enable Authorization Code (required for the browser-based OAuth login flow).
4. Keep Client Credentials enabled.
5. Optionally enable Refresh Token for token refresh support.
6. Select Save Changes.

Output of Step 2¶

All values appear on the Settings tab of your application:

Step 3: Authorize the Application for the API¶

You can authorize from either the application's APIs tab or the API's Application Access tab:

Option A - Authorize from Application:

1. Navigate to Applications > Applications > your app. For example, Actian MCP Server App.
2. Select the APIs tab.
3. Search your API. For example, mcp_server with the identifier https://<mcp-server-host>:8000/mcp.
4. Select Edit next to your API.
5. Authorize both access types:
   • User Access: Set to Authorized. This is required for the browser-based login flow and user impersonation.
   • Client Access: Set to Authorized. This may already be authorized if you selected the API during Machine to Machine application creation.
6. Select Update to save.

Option B - Authorize From API:

1. Navigate to Applications > APIs > your API. For example, mcp_server.
2. Select the Application Access tab.
3. Search your application and select Edit.
4. Authorize both User Access and Client Access as described in Option A, step 5.

After saving, the application displays two AUTHORIZED badges — User Access and Client Access.

Step 4: Create Auth0 Users (if Using User Impersonation)¶

If user_impersonation is true, the authenticated user's identity is forwarded to the database through SET SESSION AUTHORIZATION. Each Auth0 user must have a matching database account. For more information, see User Impersonation.

Step 4.1: Create the User in Auth0¶

1. In the Auth0 Dashboard, navigate to User Management > Users.
2. Select + Create User.

3. Enter the values for the following fields:

   Field	Value	Notes
   Email	jdoe@example.com	Value before @ (jdoe) becomes the database username
   Password	A secure password	Used for Auth0 login
   Connection	Username-Password-Authentication	Default database connection

4. Select Create.

Step 4.2: Create the Matching Database User¶

=== Example

Auth0 handles authentication, but the Actian database still needs the user to exist for impersonation to work:

-- Create the user account (no DB password needed — Auth0 handles authentication)
CREATE USER jdoe;

-- Grant access to the database
GRANT ACCESS ON DATABASE mydb TO jdoe;

-- Grant the necessary table permissions (adjust per your schema)
GRANT SELECT ON TABLE orders TO jdoe;
GRANT SELECT ON TABLE products TO jdoe;

-- Create the user account (DB password not used — Auth0 handles authentication)
CREATE USER mcpuser with password 'mcpuser' properties user 'daemon';;

-- Grant access to the database
GRANT CONNECT TO mcpuser;

-- Grant the necessary table permissions (adjust per your schema)
GRANT SELECT ON TABLE orders TO mcpuser;
GRANT SELECT ON TABLE products TO mcpuser;

-- Set session authorization to the privleged database_user passed to mcp server in conf.json
GRANT SETSESSIONAUTH ON 'mcpuser' TO 'database_user';

Step 5: Assemble the Final Configuration¶

Mapping Summary¶

Example conf.json¶

{
    "driver": "{Ingres}",
    "server": "@<db-host>,tcp_ip,<port>",
    "database": "mydb",
    "database_user": "<database_user>",
    "database_password": "<database_password>",
    "max_connections": 10,
    "host": "0.0.0.0",
    "port": 8000,
    "ssl_certfile": "/app/server.crt",
    "ssl_keyfile":  "/app/server.key",
    "oauth": {
        "FASTMCP_SERVER_AUTH_CONFIG_URL": "https://<your-auth0-domain>/.well-known/openid-configuration",
        "FASTMCP_SERVER_AUTH_CLIENT_ID": "<your-client-id>",
        "FASTMCP_SERVER_AUTH_CLIENT_SECRET": "<your-client-secret>",
        "FASTMCP_SERVER_AUTH_BASE_URL": "https://<your-server-host>:8000",
        "FASTMCP_SERVER_AUTH_AUDIENCE": "<your-api-identifier>",
        "user_impersonation": true
    }
}

For TLS setup details (certificate generation, Docker deployment, trusting self-signed certs), see HTTPS / TLS for Remote Deployments.

For security best practices (file permissions, .gitignore, secrets management), see Security Best Practices.

Verify End-to-End¶

After starting the MCP server container with OAuth configured:

1. Open a browser and navigate to your server's /mcp endpoint, for example, https://<your-server-host>:8000/mcp.
2. You should be redirected to the Auth0 login page.
3. After logging in, Auth0 redirects you back to the MCP server with a valid token.
4. Check the server logs for Stored database username: <username> to confirm user impersonation is active.

Troubleshooting¶

Verify OIDC Discovery Endpoint¶

curl https://dev-abc123.us.auth0.com/.well-known/openid-configuration \
  | python3 -m json.tool

You should see issuer, authorization_endpoint, token_endpoint, jwks_uri, and similar.

Common Errors¶

Clearing Visual Studio Code OAuth Cache¶

If the MCP server's Docker container is recreated, Visual Studio Code's cached OAuth client registration becomes stale. To clear it:

1. Quit Visual Studio Code completely (Cmd+Q on macOS, or close all windows on Linux/Windows).

2. Run the appropriate command for your OS:

   macOSLinuxWindows

   sqlite3 ~/Library/"Application Support"/Code/User/globalStorage/state.vscdb \
     "DELETE FROM ItemTable WHERE key LIKE '%dynamicAuth%<your-server-host>%';"
   

   sqlite3 ~/.config/Code/User/globalStorage/state.vscdb \
     "DELETE FROM ItemTable WHERE key LIKE '%dynamicAuth%<your-server-host>%';"
   

   sqlite3 "$env:APPDATA\Code\User\globalStorage\state.vscdb" `
     "DELETE FROM ItemTable WHERE key LIKE '%dynamicAuth%<your-server-host>%';"
   

3. Reopen Visual Studio Code. It will re-register with the server automatically.

Replace <your-server-host> with your server's IP or hostname, for example, 35.185.60.76. This only clears the registration for that specific server.

docker run ... -v mcp-auth-data:/root/.local/share/fastmcp ...

Token Expiration¶

Auth0 tokens have a configurable lifetime:

1. Navigate to Applications > APIs > your API > Settings.
2. Check Token Expiration (Seconds). Default is 86400 (24 hours).
3. Adjust as needed.

Staging versus Production¶