Set up authentication
This guide walks through configuring each authentication mode. For a deeper explanation of how the auth architecture works — sequence diagrams, the two-layer model, audit logs, and branch-placeholder resolution — see Authentication architecture.
Choosing a mode
| Mode | When to use | Transport | Identity per request |
|---|---|---|---|
none (default) | Local development, single-user workstations, VPN-only deployments | stdio or HTTP | Shared INFRAHUB_API_TOKEN |
token-passthrough | Multi-tenant HTTP deployments where each user should act as themselves in Infrahub | HTTP only | Client sends own Infrahub API token |
oidc | Enterprise SSO (Google, Okta, Entra, Keycloak) with centralized identity and optional scope-based write gating | HTTP only | OIDC token validated per request |
Username/password authentication is not supported — use OIDC when you need external identity.
No authentication (default)
No configuration needed beyond Infrahub connection variables:
export INFRAHUB_ADDRESS=https://infrahub.example.com
export INFRAHUB_API_TOKEN=your-token
infrahub-mcp --transport streamable-http
All clients share the same Infrahub credentials. Use this for local development or behind a VPN.
Token passthrough
Each client sends their own Infrahub API token. No shared server-side credentials required.
export INFRAHUB_ADDRESS=https://infrahub.example.com
export INFRAHUB_MCP_AUTH_MODE=token-passthrough
# No INFRAHUB_API_TOKEN needed — credentials come from the client
infrahub-mcp --transport streamable-http
Clients include their token in the request header:
Authorization: Bearer <infrahub-api-token>
To use a different header (for example, X-Infrahub-Token), set:
export INFRAHUB_MCP_TOKEN_PASSTHROUGH_HEADER=X-Infrahub-Token
Token passthrough requires Streamable HTTP transport. The server rejects --transport stdio at startup since stdio has no HTTP headers.
For per-client .mcp.json configuration examples, see Streamable HTTP with authentication.
Basic passthrough
Same fail-closed passthrough model as token passthrough, but clients send Infrahub username and password via the standard HTTP Basic scheme:
export INFRAHUB_ADDRESS=https://infrahub.example.com
export INFRAHUB_MCP_AUTH_MODE=basic-passthrough
# No INFRAHUB_USERNAME/INFRAHUB_PASSWORD needed — credentials come from the client
infrahub-mcp --transport streamable-http
Clients include their credentials in the request header:
Authorization: Basic <base64(username:password)>
The server decodes the header per request, constructs a fresh InfrahubClient with those credentials, and resets the per-request context after the call so credentials are never shared between requests.
Basic passthrough requires Streamable HTTP transport, same as token passthrough.
To encode your credentials for the Authorization header:
echo -n "username:password" | base64
# dXNlcm5hbWU6cGFzc3dvcmQ=
For per-client .mcp.json configuration examples, see Streamable HTTP with authentication.
OIDC
Step 1: Register an OAuth client
In your Identity Provider, create an OAuth/OIDC client application:
- Application type: Web application
- Redirect URI:
<your-mcp-base-url>/oauth/callback(FastMCP handles this automatically) - Scopes: At minimum,
openid,email, andprofile. Add a custom scope (for example,writeorinfrahub:write) if you want to gate write access.
The client can be confidential, with a client secret, or public, without one. Step 2 shows the server settings for each type.
Record the client ID, the client secret if the client has one, and the OIDC discovery URL.
Step 2: Configure the MCP server
export INFRAHUB_MCP_AUTH_MODE=oidc
export INFRAHUB_MCP_OIDC_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration
export INFRAHUB_MCP_OIDC_CLIENT_ID=my-mcp-client
export INFRAHUB_MCP_OIDC_BASE_URL=https://mcp.example.com
export INFRAHUB_MCP_OIDC_CLIENT_SECRET=my-secret
For a public client, leave INFRAHUB_MCP_OIDC_CLIENT_SECRET unset and set a signing key instead. Generate the key once, for example with openssl rand -hex 32, and store it with your other secrets:
export INFRAHUB_MCP_OIDC_JWT_SIGNING_KEY=<generated-key>
Without a client secret, the server sends only the client ID to the identity provider's token endpoint. The client type does not turn PKCE on or off.
The signing key signs the tokens the server issues to MCP clients and encrypts the OAuth state the server stores. With a client secret, the server derives this key from the secret, and setting INFRAHUB_MCP_OIDC_JWT_SIGNING_KEY replaces the derived key.
The server stores that OAuth state, including the record of each token it issued, on local disk under the FastMCP home folder. Set FASTMCP_HOME to choose the folder. Issued tokens keep working after a restart only when both of these hold:
- The signing key is the same as before.
- The FastMCP home folder persists across the restart, for example on a container volume.
Otherwise users sign in again and MCP clients register again. Replicas do not share this folder, so a token works only on the replica that issued it.
The server checks the OIDC settings at startup. If a required setting is missing, including both the client secret and the signing key, the server stops with an error that names the missing environment variables.
Step 3: Configure write scopes (optional)
By default, any authenticated user can call both read and write tools. To restrict write access to users with a specific scope in their token:
# Only users whose token contains "infrahub:write" can call write tools
export INFRAHUB_MCP_AUTH_SCOPES_WRITE=infrahub:write
When configured, tools tagged write (node_upsert, node_delete, propose_changes, mutate_graphql) are:
- Hidden from discovery — users without the required scope never see write tools in
tools/list. - Blocked at call time — even if a client hardcodes a tool name, the call is rejected.
The same scope applies to the make_infra_change prompt, which is also tagged write. Users without the write scope do not see it in prompts/list, and a request to fetch it is rejected.
Users without the write scope effectively get a read-only experience without needing INFRAHUB_MCP_READ_ONLY=true.
Step 4: Verify
Start the server and confirm the OIDC configuration in the logs:
INFO oidc_auth enabled=true config_url=https://accounts.google.com/... client_id=my-mcp-client public_client=false
INFO auth_middleware enabled=true auth_mode=oidc write_scopes=['infrahub:write']
Provider examples
Google
INFRAHUB_MCP_AUTH_MODE=oidc
INFRAHUB_MCP_OIDC_CONFIG_URL=https://accounts.google.com/.well-known/openid-configuration
INFRAHUB_MCP_OIDC_CLIENT_ID=123456789.apps.googleusercontent.com
INFRAHUB_MCP_OIDC_CLIENT_SECRET=GOCSPX-...
INFRAHUB_MCP_OIDC_BASE_URL=https://mcp.example.com
Okta
INFRAHUB_MCP_AUTH_MODE=oidc
INFRAHUB_MCP_OIDC_CONFIG_URL=https://your-org.okta.com/.well-known/openid-configuration
INFRAHUB_MCP_OIDC_CLIENT_ID=0oa...
INFRAHUB_MCP_OIDC_CLIENT_SECRET=your-client-secret
INFRAHUB_MCP_OIDC_BASE_URL=https://mcp.example.com
INFRAHUB_MCP_AUTH_SCOPES_WRITE=infrahub:write
Microsoft Entra
INFRAHUB_MCP_AUTH_MODE=oidc
INFRAHUB_MCP_OIDC_CONFIG_URL=https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration
INFRAHUB_MCP_OIDC_CLIENT_ID=your-app-id
INFRAHUB_MCP_OIDC_CLIENT_SECRET=your-client-secret
INFRAHUB_MCP_OIDC_BASE_URL=https://mcp.example.com
INFRAHUB_MCP_OIDC_AUDIENCE=api://your-app-id
Keycloak
INFRAHUB_MCP_AUTH_MODE=oidc
INFRAHUB_MCP_OIDC_CONFIG_URL=https://keycloak.example.com/realms/infrahub/.well-known/openid-configuration
INFRAHUB_MCP_OIDC_CLIENT_ID=infrahub-mcp
INFRAHUB_MCP_OIDC_CLIENT_SECRET=your-client-secret
INFRAHUB_MCP_OIDC_BASE_URL=https://mcp.example.com
INFRAHUB_MCP_AUTH_SCOPES_WRITE=write
Configuration reference
For the complete list of environment variables, see the Configuration reference. For an architectural deep-dive on each mode, see Authentication architecture.
| Variable | Required | Default | Description |
|---|---|---|---|
INFRAHUB_MCP_AUTH_MODE | No | none | Authentication mode (none, oidc, token-passthrough, basic-passthrough) |
INFRAHUB_MCP_OIDC_CONFIG_URL | Yes (oidc) | OIDC discovery endpoint URL | |
INFRAHUB_MCP_OIDC_CLIENT_ID | Yes (oidc) | OAuth client ID registered with the IdP | |
INFRAHUB_MCP_OIDC_CLIENT_SECRET | Yes (oidc, confidential client) | OAuth client secret. Leave unset for a public client and set INFRAHUB_MCP_OIDC_JWT_SIGNING_KEY instead | |
INFRAHUB_MCP_OIDC_JWT_SIGNING_KEY | Yes (oidc, public client) | Key that signs the tokens the server issues and encrypts its stored OAuth state. Optional with a client secret. Keep it the same across restarts | |
INFRAHUB_MCP_OIDC_BASE_URL | Yes (oidc) | Public URL where the MCP server is accessible | |
INFRAHUB_MCP_OIDC_AUDIENCE | No | Token audience claim | |
INFRAHUB_MCP_OIDC_USER_CLAIM | No | email | JWT claim used for user identity |
INFRAHUB_MCP_AUTH_SCOPES_WRITE | No | write | Scopes required for write operations (comma-separated) |
INFRAHUB_MCP_TOKEN_PASSTHROUGH_HEADER | No | Authorization | HTTP header carrying the Infrahub API token (token-passthrough mode) |