provider
IdentityAssertionParams
Bases: BaseModel
Validated parameters of a SEP-990 identity-assertion (RFC 7523 jwt-bearer) request.
Passed to OAuthAuthorizationServerProvider.exchange_identity_assertion. assertion is the
ID-JAG (a signed JWT) the enterprise identity provider issued; the provider validates it per
RFC 7523 §3 and the SEP-990 §5.1 processing rules before issuing an access token.
Source code in src/mcp/server/auth/provider.py
19 20 21 22 23 24 25 26 27 28 29 | |
principal_components
The (client_id, issuer, subject) triple identifying the principal a token represents.
The single source for "who is this token's principal": session ownership and
request-state binding both build on it. Components the token verifier does
not supply are None, so comparisons degrade to the remaining components.
Source code in src/mcp/server/auth/provider.py
62 63 64 65 66 67 68 69 70 | |
TokenVerifier
Bases: Protocol
Protocol for verifying bearer tokens.
Source code in src/mcp/server/auth/provider.py
123 124 125 126 127 | |
verify_token
async
verify_token(token: str) -> AccessToken | None
Verify a bearer token and return access info if valid.
Source code in src/mcp/server/auth/provider.py
126 127 | |
OAuthAuthorizationServerProvider
Bases: Protocol, Generic[AuthorizationCodeT, RefreshTokenT, AccessTokenT]
Source code in src/mcp/server/auth/provider.py
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |
get_client
async
get_client(
client_id: str,
) -> OAuthClientInformationFull | None
Retrieves client information by client ID.
Implementors MAY raise NotImplementedError if dynamic client registration is disabled in ClientRegistrationOptions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_id
|
str
|
The ID of the client to retrieve. |
required |
Returns:
| Type | Description |
|---|---|
OAuthClientInformationFull | None
|
The client information, or None if the client does not exist. |
Source code in src/mcp/server/auth/provider.py
138 139 140 141 142 143 144 145 146 147 148 149 | |
register_client
async
register_client(
client_info: OAuthClientInformationFull,
) -> None
Saves client information as part of registering it.
Implementors MAY raise NotImplementedError if dynamic client registration is disabled in ClientRegistrationOptions.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client_info
|
OAuthClientInformationFull
|
The client metadata to register. |
required |
Raises:
| Type | Description |
|---|---|
RegistrationError
|
If the client metadata is invalid. |
Source code in src/mcp/server/auth/provider.py
151 152 153 154 155 156 157 158 159 160 161 162 | |
authorize
async
authorize(
client: OAuthClientInformationFull,
params: AuthorizationParams,
) -> str
Handle the /authorize endpoint and return a URL that the client will be redirected to.
Many MCP implementations will redirect to a third-party provider to perform a second OAuth exchange with that provider. In this sort of setup, the client has an OAuth connection with the MCP server, and the MCP server has an OAuth connection with the 3rd-party provider. At the end of this flow, the client should be redirected to the redirect_uri from params.redirect_uri.
+--------+ +------------+ +-------------------+ | | | | | | | Client | --> | MCP Server | --> | 3rd Party OAuth | | | | | | Server | +--------+ +------------+ +-------------------+ | ^ | +------------+ | | | | | | | Redirect | |redirect_uri|<-----+ +------------------+ | | +------------+
Implementations will need to define another handler on the MCP server's return flow to perform the second redirect, and generate and store an authorization code as part of completing the OAuth authorization step.
Implementations SHOULD generate an authorization code with at least 160 bits of entropy, and MUST generate an authorization code with at least 128 bits of entropy. See https://datatracker.ietf.org/doc/html/rfc6749#section-10.10.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The client requesting authorization. |
required |
params
|
AuthorizationParams
|
The parameters of the authorization request. |
required |
Returns:
| Type | Description |
|---|---|
str
|
A URL to redirect the client to for authorization. |
Raises:
| Type | Description |
|---|---|
AuthorizeError
|
If the authorization request is invalid. |
Source code in src/mcp/server/auth/provider.py
164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 | |
load_authorization_code
async
load_authorization_code(
client: OAuthClientInformationFull,
authorization_code: str,
) -> AuthorizationCodeT | None
Loads an AuthorizationCode by its code.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The client that requested the authorization code. |
required |
authorization_code
|
str
|
The authorization code to get the challenge for. |
required |
Returns:
| Type | Description |
|---|---|
AuthorizationCodeT | None
|
The AuthorizationCode, or None if not found. |
Source code in src/mcp/server/auth/provider.py
207 208 209 210 211 212 213 214 215 216 217 218 219 | |
exchange_authorization_code
async
exchange_authorization_code(
client: OAuthClientInformationFull,
authorization_code: AuthorizationCodeT,
) -> OAuthToken
Exchanges an authorization code for an access token and refresh token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The client exchanging the authorization code. |
required |
authorization_code
|
AuthorizationCodeT
|
The authorization code to exchange. |
required |
Returns:
| Type | Description |
|---|---|
OAuthToken
|
The OAuth token, containing access and refresh tokens. |
Raises:
| Type | Description |
|---|---|
TokenError
|
If the request is invalid. |
Source code in src/mcp/server/auth/provider.py
221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 | |
load_refresh_token
async
load_refresh_token(
client: OAuthClientInformationFull, refresh_token: str
) -> RefreshTokenT | None
Loads a RefreshToken by its token string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The client that is requesting to load the refresh token. |
required |
refresh_token
|
str
|
The refresh token string to load. |
required |
Returns:
| Type | Description |
|---|---|
RefreshTokenT | None
|
The RefreshToken object if found, or None if not found. |
Source code in src/mcp/server/auth/provider.py
238 239 240 241 242 243 244 245 246 247 248 | |
exchange_refresh_token
async
exchange_refresh_token(
client: OAuthClientInformationFull,
refresh_token: RefreshTokenT,
scopes: list[str],
) -> OAuthToken
Exchanges a refresh token for an access token and refresh token.
Implementations SHOULD rotate both the access token and refresh token.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The client exchanging the refresh token. |
required |
refresh_token
|
RefreshTokenT
|
The refresh token to exchange. |
required |
scopes
|
list[str]
|
Optional scopes to request with the new access token. |
required |
Returns:
| Type | Description |
|---|---|
OAuthToken
|
The OAuth token, containing access and refresh tokens. |
Raises:
| Type | Description |
|---|---|
TokenError
|
If the request is invalid. |
Source code in src/mcp/server/auth/provider.py
250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | |
load_access_token
async
load_access_token(token: str) -> AccessTokenT | None
Loads an access token by its token string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token
|
str
|
The access token to verify. |
required |
Returns:
| Type | Description |
|---|---|
AccessTokenT | None
|
The access token, or None if the token is invalid. |
Source code in src/mcp/server/auth/provider.py
273 274 275 276 277 278 279 280 281 | |
revoke_token
async
revoke_token(token: AccessTokenT | RefreshTokenT) -> None
Revokes an access or refresh token.
If the given token is invalid or already revoked, this method should do nothing.
Implementations SHOULD revoke both the access token and its corresponding refresh token, regardless of which of the access token or refresh token is provided.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token
|
AccessTokenT | RefreshTokenT
|
The token to revoke. |
required |
Source code in src/mcp/server/auth/provider.py
283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 | |
exchange_identity_assertion
async
exchange_identity_assertion(
client: OAuthClientInformationFull,
params: IdentityAssertionParams,
) -> OAuthToken
Exchanges an Identity Assertion Authorization Grant (ID-JAG) for an access token.
This is leg 2 of SEP-990: the client presents an ID-JAG - issued by the enterprise
identity provider - using the RFC 7523 urn:ietf:params:oauth:grant-type:jwt-bearer
grant, and receives an access token for this MCP server. The default implementation
rejects every request as an unsupported grant type; override it to enable the grant.
The implementation is responsible for validating params.assertion per RFC 7523 §3
and the SEP-990 §5.1 processing rules, in particular:
- verify the JWT signature,
iss, andexp, and thattypisoauth-id-jag+jwt; - require
audto identify this authorization server (its own issuer); - require a
sub(RFC 7523 §3 makes it mandatory) identifying the end user; - reject replays - enforce
exp, and trackjtifor the assertion's lifetime; - require the ID-JAG's
client_idclaim to match the authenticatedclient- do NOT derive authorization fromclient.client_idalone, which for a confidential client is authenticated but for any client is ultimately self-asserted in the request; - audience-restrict the issued access token to the resource named in the ID-JAG's
resourceclaim, not merelyparams.resource(which the client controls); - derive the granted scopes from the ID-JAG and policy rather than granting
params.scopesverbatim.
The handler guarantees client is confidential (it rejects clients without a stored
secret before calling this hook), but the ID-JAG remains the authoritative grant.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
client
|
OAuthClientInformationFull
|
The authenticated client presenting the assertion. |
required |
params
|
IdentityAssertionParams
|
The validated jwt-bearer request parameters (the ID-JAG and indicators). |
required |
Returns:
| Name | Type | Description |
|---|---|---|
OAuthToken
|
The OAuth token, containing the issued access token. A refresh token SHOULD NOT be |
|
issued |
OAuthToken
|
SEP-990 relies on the IdP to control session lifetime via re-issued ID-JAGs. |
Raises:
| Type | Description |
|---|---|
TokenError
|
If the assertion or request is invalid. Use |
Source code in src/mcp/server/auth/provider.py
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 | |
ProviderTokenVerifier
Bases: TokenVerifier
Token verifier that uses an OAuthAuthorizationServerProvider.
This is provided for backwards compatibility with existing auth_server_provider configurations. For new implementations using AS/RS separation, consider using the TokenVerifier protocol with a dedicated implementation like IntrospectionTokenVerifier.
Source code in src/mcp/server/auth/provider.py
358 359 360 361 362 363 364 365 366 367 368 369 370 371 | |
verify_token
async
verify_token(token: str) -> AccessToken | None
Verify token using the provider's load_access_token method.
Source code in src/mcp/server/auth/provider.py
369 370 371 | |