AiMcpOauth2PluginConfig

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/AiMcpOauth2PluginConfig",
  "title": "AiMcpOauth2PluginConfig",
  "x-speakeasy-entity": "PluginAiMcpOauth2",
  "properties": {
    "config": {
      "description": "The configuration for MCP authorization in OAuth2. If this is enabled, make sure the configured metadata_endpoint is also covered by the same route so the authorization can be applied correctly.",
      "type": "object",
      "properties": {
        "args": {
          "description": "Additional arguments to send in the POST body.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "authorization_servers": {
          "type": "array",
          "items": {
            "description": "The authorization server identifier.",
            "type": "string"
          },
          "minLength": 1
        },
        "cache_introspection": {
          "description": "If enabled, the plugin will cache the introspection response for the access token. This can improve performance by reducing the number of introspection requests to the authorization server.",
          "type": "boolean",
          "default": true
        },
        "claim_to_header": {
          "description": "Map top-level token claims to upstream headers. Mutually exclusive with upstream_headers.",
          "type": "array",
          "items": {
            "properties": {
              "claim": {
                "description": "The claim name to be used in the access token.",
                "type": "string"
              },
              "header": {
                "description": "The HTTP header name to be used for forwarding the claim value to the upstream.",
                "type": "string"
              }
            },
            "required": [
              "claim",
              "header"
            ],
            "type": "object"
          },
          "minLength": 1
        },
        "client_alg": {
          "description": "The client JWT signing algorithm.",
          "type": "string",
          "enum": [
            "ES256",
            "ES384",
            "ES512",
            "EdDSA",
            "HS256",
            "HS384",
            "HS512",
            "PS256",
            "PS384",
            "PS512",
            "RS256",
            "RS384",
            "RS512"
          ]
        },
        "client_auth": {
          "description": "The client authentication method.",
          "type": "string",
          "enum": [
            "client_secret_basic",
            "client_secret_jwt",
            "client_secret_post",
            "none",
            "private_key_jwt",
            "self_signed_tls_client_auth",
            "tls_client_auth"
          ]
        },
        "client_id": {
          "description": "The client ID for authentication.",
          "type": "string",
          "x-referenceable": true
        },
        "client_jwk": {
          "description": "The client JWK for private_key_jwt authentication.",
          "type": "string",
          "x-encrypted": true,
          "x-referenceable": true
        },
        "client_secret": {
          "description": "The client secret for authentication.",
          "type": "string",
          "x-encrypted": true,
          "x-referenceable": true
        },
        "consumer_by": {
          "description": "Consumer fields used for mapping: - `id`: try to find the matching Consumer by `id` - `username`: try to find the matching Consumer by `username` - `custom_id`: try to find the matching Consumer by `custom_id`.",
          "type": "array",
          "items": {
            "enum": [
              "custom_id",
              "id",
              "username"
            ],
            "type": "string"
          },
          "default": [
            "custom_id",
            "username"
          ],
          "minLength": 1
        },
        "consumer_claim": {
          "description": "The claim used for consumer mapping. If multiple values are set, it means the claim is inside a nested object of the token payload.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "minLength": 1
        },
        "consumer_groups_claim": {
          "description": "The claim used for consumer groups mapping. If multiple values are set, it means the claim is inside a nested object of the token payload.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "minLength": 1
        },
        "consumer_groups_optional": {
          "description": "Do not terminate the request if consumer groups mapping fails.",
          "type": "boolean",
          "default": false
        },
        "consumer_optional": {
          "description": "Do not terminate the request if consumer mapping fails.",
          "type": "boolean",
          "default": false
        },
        "credential_claim": {
          "description": "The claim used to derive virtual credentials (e.g. to be consumed by the rate-limiting plugin), in case the consumer mapping is not used. If multiple values are set, it means the claim is inside a nested object of the token payload.",
          "type": "array",
          "items": {
            "type": "string"
          },
          "default": [
            "sub"
          ]
        },
        "headers": {
          "description": "Additional headers for the introspection request.",
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "http_proxy": {
          "description": "HTTP proxy to use.",
          "type": "string"
        },
        "http_proxy_authorization": {
          "description": "HTTP proxy authorization header.",
          "type": "string"
        },
        "http_version": {
          "description": "The HTTP version used for requests.",
          "type": "number",
          "default": 1.1
        },
        "https_proxy": {
          "description": "HTTPS proxy to use.",
          "type": "string"
        },
        "https_proxy_authorization": {
          "description": "HTTPS proxy authorization header.",
          "type": "string"
        },
        "insecure_relaxed_audience_validation": {
          "description": "If enabled, the plugin will not validate the audience of the access token. Disable it if the authorization server does not correctly set the audience claim according to RFC 8707 and MCP specification.",
          "type": "boolean",
          "default": false
        },
        "introspection_endpoint": {
          "description": "The Token Introspection Endpoint. If not provided, the plugin will attempt to use JWKS to verify the token. If the token is opaque, this field must be provided.",
          "type": "string"
        },
        "introspection_format": {
          "description": "Controls introspection response format.",
          "type": "string",
          "enum": [
            "base64",
            "base64url",
            "string"
          ]
        },
        "jwks_cache_ttl": {
          "description": "The cache TTL in seconds for JWKS.",
          "type": "integer",
          "default": 3600
        },
        "jwks_endpoint": {
          "description": "The JWKS endpoint URL for fetching the authorization server's public keys. If not provided, the plugin will attempt to discover it from the authorization server metadata.",
          "type": "string"
        },
        "jwt_claims_leeway": {
          "description": "The leeway in seconds for JWT claims validation (exp, nbf). This allows tokens that are slightly expired or not yet valid due to clock skew.",
          "type": "integer",
          "default": 0
        },
        "keepalive": {
          "description": "Enable HTTP keepalive for requests.",
          "type": "boolean",
          "default": true
        },
        "max_request_body_size": {
          "description": "max allowed body size allowed to be handled as MCP request. 0 means unlimited, but the size of this body will still be limited by Nginx's client_max_body_size.",
          "type": "integer",
          "default": 1048576
        },
        "metadata_cache_ttl": {
          "description": "The cache TTL in seconds for discovered authorization server metadata.",
          "type": "integer",
          "default": 3600
        },
        "metadata_discovery_endpoint": {
          "description": "Custom OAuth 2.0 authorization server metadata discovery URL. If provided, the plugin will use this URL directly instead of trying standard well-known discovery paths. The custom endpoint URL should end with either '/.well-known/openid-configuration' or '/.well-known/oauth-authorization-server'.",
          "type": "string"
        },
        "metadata_discovery_retry": {
          "description": "The number of retry attempts for metadata discovery requests per URL.",
          "type": "integer",
          "default": 3
        },
        "metadata_endpoint": {
          "description": "The path for OAuth 2.0 Protected Resource Metadata. Default to $resource/.well-known/oauth-protected-resource. For example, if the configured resource is https://api.example.com/mcp, the metadata endpoint is /mcp/.well-known/oauth-protected-resource.",
          "type": "string"
        },
        "mtls_introspection_endpoint": {
          "description": "The mTLS alias for the introspection endpoint.",
          "type": "string"
        },
        "no_proxy": {
          "description": "Comma-separated list of hosts to exclude from proxy.",
          "type": "string"
        },
        "passthrough_credentials": {
          "description": "Keep the credentials used for authentication in the request. If multiple credentials are sent with the same request, the plugin will keep those that were used for successful authentication.",
          "type": "boolean",
          "default": false
        },
        "resource": {
          "description": "The resource identifier.",
          "type": "string"
        },
        "scopes_supported": {
          "type": "array",
          "items": {
            "description": "Recommended scopes that are used in authorization requests to request access to this protected resource.",
            "type": "string"
          },
          "minLength": 1
        },
        "ssl_verify": {
          "description": "Verify the SSL certificate.",
          "type": "boolean",
          "default": true
        },
        "timeout": {
          "description": "Network I/O timeout in milliseconds.",
          "type": "number",
          "default": 10000
        },
        "tls_client_auth_cert": {
          "description": "PEM-encoded client certificate for mTLS.",
          "type": "string"
        },
        "tls_client_auth_key": {
          "description": "PEM-encoded private key for mTLS.",
          "type": "string"
        },
        "tls_client_auth_ssl_verify": {
          "description": "Verify server certificate in mTLS.",
          "type": "boolean",
          "default": true
        },
        "token_exchange": {
          "description": "Configuration details about token exchange that should happen before reaching upstream MCP server",
          "type": "object",
          "properties": {
            "cache": {
              "type": "object",
              "properties": {
                "enabled": {
                  "description": "Whether to cache exchanged token",
                  "type": "boolean",
                  "default": true
                },
                "ttl": {
                  "description": "The default cache TTL to store exchanged token. If the exchange endpoint does not provide 'expires_in' data when token is exchanged this TTL value will be used to cache it.",
                  "type": "integer",
                  "default": 3600
                }
              }
            },
            "client_auth": {
              "description": "The type of authentication method to use with the exchange endpoint. Use 'inherit' to use the same client_id, and secret as in introspection_endpoint.",
              "type": "string",
              "default": "client_secret_basic",
              "enum": [
                "client_secret_basic",
                "client_secret_post",
                "inherit",
                "none"
              ]
            },
            "client_id": {
              "description": "The client ID for authentication.",
              "type": "string",
              "x-referenceable": true
            },
            "client_secret": {
              "description": "The client secret for authentication.",
              "type": "string",
              "x-encrypted": true,
              "x-referenceable": true
            },
            "enabled": {
              "description": "Whether Token Exchange should be enabled",
              "type": "boolean",
              "default": false
            },
            "request": {
              "type": "object",
              "properties": {
                "actor_token": {
                  "description": "Static actor token value (when source is config).",
                  "type": "string"
                },
                "actor_token_header": {
                  "description": "Header name containing actor token (when source is header).",
                  "type": "string"
                },
                "actor_token_source": {
                  "description": "Where to obtain actor token.",
                  "type": "string",
                  "default": "none",
                  "enum": [
                    "config",
                    "header",
                    "none"
                  ]
                },
                "actor_token_type": {
                  "description": "The token type identifier of actor token.",
                  "type": "string",
                  "default": "urn:ietf:params:oauth:token-type:access_token"
                },
                "audience": {
                  "description": "Audiences used in the token exchange request.",
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "minLength": 1
                },
                "requested_token_type": {
                  "description": "The desired output token type.",
                  "type": "string",
                  "default": "urn:ietf:params:oauth:token-type:access_token"
                },
                "resource": {
                  "description": "The absolute URI of target MCP service where token will be used.",
                  "type": "string"
                },
                "scopes": {
                  "description": "Scopes used in the token exchange request.",
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "minLength": 1
                },
                "subject_token_type": {
                  "description": "The type of token to be exchanged.",
                  "type": "string",
                  "default": "urn:ietf:params:oauth:token-type:access_token"
                }
              }
            },
            "token_endpoint": {
              "description": "The token exchange endopint.",
              "type": "string"
            }
          },
          "required": [
            "token_endpoint"
          ]
        },
        "upstream_headers": {
          "description": "Map token claims to upstream headers using path-based access. Each entry specifies a header name and a path (array of strings) to traverse the token claims. Mutually exclusive with claim_to_header.",
          "type": "array",
          "items": {
            "properties": {
              "header": {
                "description": "The name of the header.",
                "type": "string"
              },
              "path": {
                "description": "The path of the header value.",
                "type": "array",
                "items": {
                  "type": "string"
                },
                "minLength": 1
              }
            },
            "required": [
              "header",
              "path"
            ],
            "type": "object"
          }
        }
      },
      "required": [
        "authorization_servers",
        "resource"
      ]
    },
    "name": {
      "const": "ai-mcp-oauth2"
    },
    "protocols": {
      "description": "A set of strings representing HTTP protocols.",
      "type": "array",
      "items": {
        "enum": [
          "grpc",
          "grpcs",
          "http",
          "https"
        ],
        "type": "string"
      },
      "format": "set",
      "default": [
        "grpc",
        "grpcs",
        "http",
        "https"
      ]
    },
    "route": {
      "description": "If set, the plugin will only activate when receiving requests via the specified route. Leave unset for the plugin to activate regardless of the route being used.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string"
        }
      }
    },
    "service": {
      "description": "If set, the plugin will only activate when receiving requests via one of the routes belonging to the specified Service. Leave unset for the plugin to activate regardless of the Service being matched.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "config"
  ]
}