Skip to main content

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​

ModeWhen to useTransportIdentity per request
none (default)Local development, single-user workstations, VPN-only deploymentsstdio or HTTPShared INFRAHUB_API_TOKEN
token-passthroughMulti-tenant HTTP deployments where each user should act as themselves in InfrahubHTTP onlyClient sends own Infrahub API token
oidcEnterprise SSO (Google, Okta, Entra, Keycloak) with centralized identity and optional scope-based write gatingHTTP onlyOIDC 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
note

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.

note

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, and profile. Add a custom scope (for example, write or infrahub: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:

  1. Hidden from discovery — users without the required scope never see write tools in tools/list.
  2. 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.

VariableRequiredDefaultDescription
INFRAHUB_MCP_AUTH_MODENononeAuthentication mode (none, oidc, token-passthrough, basic-passthrough)
INFRAHUB_MCP_OIDC_CONFIG_URLYes (oidc)OIDC discovery endpoint URL
INFRAHUB_MCP_OIDC_CLIENT_IDYes (oidc)OAuth client ID registered with the IdP
INFRAHUB_MCP_OIDC_CLIENT_SECRETYes (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_KEYYes (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_URLYes (oidc)Public URL where the MCP server is accessible
INFRAHUB_MCP_OIDC_AUDIENCENoToken audience claim
INFRAHUB_MCP_OIDC_USER_CLAIMNoemailJWT claim used for user identity
INFRAHUB_MCP_AUTH_SCOPES_WRITENowriteScopes required for write operations (comma-separated)
INFRAHUB_MCP_TOKEN_PASSTHROUGH_HEADERNoAuthorizationHTTP header carrying the Infrahub API token (token-passthrough mode)