Generic OIDC Auth

Getting Started

The Generic Auth Service allows you to integrate with any OpenID Connect (OIDC) compliant identity provider (IDP). It discovers the JWKS (JSON Web Key Set) URL either through the provider’s /.well-known/openid-configuration endpoint or directly via the provided authorizationServer.

To configure this auth service, you need to provide the audience (the expected aud claim in the token), the authorizationServer of your identity provider, and optionally a list of scopesRequired that must be present in the token’s claims.

[!NOTE] The only time the aud claim matches the client_id is inside an ID Token (a concept from OpenID Connect used to verify a user’s identity). Because an ID token is intended to be consumed by the client application itself, the client is the audience.

Usage Modes

The Generic Auth Service supports two distinct modes of operation:

1. Toolbox Auth

This mode is used for Toolbox’s native authentication/authorization features. It is active when you reference the auth service in a tool’s configuration and mcpEnabled is set to false.

• Header: Expects the token in a custom header matching <name>_token (e.g., my-generic-auth_token).
• Token Type: Only supports JWT (OIDC) tokens.
• Usage: Used for Authenticated Parameters and Authorized Invocations.

Token Validation

When a request is received in this mode, the service will:

1. Extract the token from the <name>_token header.
2. Treat it as a JWT (opaque tokens are not supported in this mode).
3. Validates signature using JWKS fetched from authorizationServer.
4. Verifies expiration (exp) and audience (aud).
5. Verifies required scopes in scope claim.

Example

kind: authService
name: my-generic-auth
type: generic
audience: ${YOUR_OIDC_AUDIENCE}
authorizationServer: https://your-idp.example.com
# mcpEnabled: false
scopesRequired:
  - read
  - write

Tool Usage Example

To use this auth service for Authenticated Parameters or Authorized Invocations, reference it in your tool configuration:

kind: tool
name: secure_query
type: postgres-sql
source: my-pg-instance
statement: |
  SELECT * FROM data WHERE user_id = $1
parameters:
  - name: user_id
    type: strings
    description: Auto-populated from token
    authServices:
      - name: my-generic-auth
        field: sub # Extract 'sub' claim from JWT
authRequired:
  - my-generic-auth # Require valid token for invocation

2. MCP Authorization

This mode enforces global authentication for all MCP endpoints. It is active when mcpEnabled is set to true in the auth service configuration.

• Header: Expects the token in the standard Authorization: Bearer <token> header.
• Token Type: Supports both JWT and Opaque tokens.
• Usage: Used to secure the entire MCP server.

Token Validation

When a request is received in this mode, the service will:

1. Extract the token from the Authorization header after Bearer prefix.
2. Determine if the token is a JWT or an opaque token based on format (JWTs contain exactly two dots).
3. For JWTs:
   • Validates signature using JWKS fetched from authorizationServer.
   • Verifies expiration (exp) and audience (aud).
   • Verifies required scopes in scope claim.
4. For Opaque Tokens:
   • Calls the introspection endpoint (either configured via introspectionEndpoint or discovered from the authorizationServer’s OIDC configuration).
   • Verifies expiration (exp) and audience (aud or "audience" fallback).
   • Verifies required scopes in scope field.

Example

kind: authService
name: my-generic-auth
type: generic
audience: ${YOUR_TOKEN_AUDIENCE}
authorizationServer: https://your-idp.example.com
mcpEnabled: true
scopesRequired:
  - read
  - write

Google Authentication Note

[!WARNING] Do not configure Google’s tokeninfo endpoint (https://oauth2.googleapis.com/tokeninfo) using type: generic. Because the generic OIDC service strictly enforces the presence and validity of the active claim (RFC 7662), and Google’s tokeninfo endpoint does not return this claim, validation will fail.

To authenticate with Google tokens, use the native Google Sign-In auth service (type: google) instead, which natively handles Google’s endpoints and token formats.

Okta OIDC Configuration Example

To secure your MCP server or tools using Okta as the identity provider:

kind: authService
name: okta-auth
type: generic
audience: api://default # Or your custom Okta audience
authorizationServer: https://your-subdomain.okta.com/oauth2/default
mcpEnabled: true
scopesRequired:
  - openid
  - profile

[!NOTE] If you are using Okta’s Org Authorization Server (instead of a Custom Authorization Server), your authorizationServer URL will be https://your-subdomain.okta.com.

Tool-Level Scopes

When using MCP Authorization (with mcpEnabled: true in the auth service), you can enforce granular tool-level scope authorization by specifying the scopesRequired field in the tool configuration.

This ensures that a client can only invoke the tool if their authorization token contains all the specified scopes.

kind: tool
name: update_flight_status
type: postgres-sql
source: my-pg-instance
statement: |
  UPDATE flights SET status = $1 WHERE flight_number = $2
description: Update flight status
authRequired:
  - my-generic-auth
scopesRequired:
  - execute:sql
  - write:flights

If a client attempts to invoke this tool without the required scopes, the server will return an HTTP 403 Forbidden response with a WWW-Authenticate header challenge indicating the missing scopes, as per the MCP Auth specification.

Reference