Skip to content

BAI-1609 add identity_assertion to the MCP auth values - #171

Merged
imranq2 merged 2 commits into
mainfrom
IQ-BAI-1609
Nov 9, 2026
Merged

imranq2 merged 2 commits into
mainfrom
IQ-BAI-1609

Conversation

@imranq2

@imranq2 imranq2 commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What

Adds identity_assertion to the MCP server auth values in both schemas that define them (AgentConfig.auth in config_schema.py and McpServerEntry.auth in mcp_json_schema.py), with updated descriptions and tests (a parametrized accept/reject test over every value, and an .mcp.json resolution test).

identity_assertion means the consuming service sends the MCP server a short-lived token it signs itself, carrying only the person id and addressed to that server, instead of the caller's own token. This library only carries the value; there is no behavior keyed on it here. The consumer (baileyai-skills-service) implements it.

Why

Part of the plugin MCP tool approval work (baileyai-skills-service #380, #382, #385; BAI-1609). A plugin's .mcp.json requests an auth type and the service's approvals file grants it, so a person-scoped vendor token needs to be a value the .mcp.json can request. Today auth rejects any value outside the existing five.

Scope boundary

Covers only the two Literal values, descriptions and tests. Defers: the consumer-side handling (baileyai-skills-service), and the version bump there after release. No existing value changes and no default changes; configs that omit the value are unaffected.

Consumers affected and how they were checked

  • This library: the only code that reads auth is mcp_json_reader.py (copies the value through; oauth still overrides it to jwt_token, now covered by a test for identity_assertion as well as pass_through) and responses_api_request_wrapper.py (sets headers only). Nothing branches on the new value.
  • baileyai-skills-service: validates plugin MCP entries against this Literal through AgentConfig.model_validate (registry_loader.py), so it rejects identity_assertion until it bumps to the release of this PR. Handling of the value is in its #385. Its docstring at registry_loader.py:262 lists the old five values and gets updated there.
  • baileyai: a search of its Python source finds no code that branches on auth values (only an unrelated pass_through_headers setting), and configs that omit the value are unaffected. Not run against a build of this change.
  • Not done: no consumer test suite was run against a build of this change; that happens when #385 bumps the floor.

Governing artifacts

  • Design and TDD: baileyai-skills-service #380 (BAI-1571); Tech Design Review EA-2892; plan #382; ADR docs/adr/0015-plugin-mcp-tool-approval.md (in #385). The signer, audience and consumer contract for identity_assertion are specified there, not here.
  • Open: decision D6 (service-minted person-scoped token versus token exchange) is still awaiting EA and Security acceptance. Until then the consumer's issuer is unset in every environment, so the value is accepted by this library's schema but nothing issues the token. Whether the token follows a standard OAuth/OIDC assertion profile is decided under D6, not by this PR.
  • The name identity_assertion is the one used in the design, ADR and the baileyai-configuration approvals schema (baileyai-configuration Improve MCP tool error handling and search_tools category-aware resolution #36), so it is kept for consistency.
  • Follow-up, not in this PR: the auth Literal is duplicated in config_schema.py and mcp_json_schema.py (pre-existing); a shared alias is a separate change.

Tests

tests/configs passes (255 tests). Pre-commit passes.

@gecko-security gecko-security Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gecko PR Review

No vulnerabilities found, LGTM.

Summary

This PR adds an identity_assertion value to the auth Literal in languagemodelcommon/configs/schemas/config_schema.py and languagemodelcommon/configs/schemas/mcp_json_schema.py, so both the agent config and the MCP JSON entry now accept it. The library only validates and carries the value; the consuming service must generate and sign the short-lived, server-addressed token, so the security guarantees depend on that out-of-repo implementation. The new tests/configs/test_auth_values.py checks that every documented auth value validates, but the diff is truncated and does not show whether invalid values or the token-signing contract are tested. No wiki context was provided, so this assessment relies only on the diff.

Important Files Changed

2 important files out of 4 changed

File Path Why it matters
languagemodelcommon/configs/schemas/config_schema.py Adds identity_assertion to the AuthenticationConfig.auth Literal, which widens the set of accepted authentication modes for agent configs and is the schema the consumer relies on for validation.
languagemodelcommon/configs/schemas/mcp_json_schema.py Mirrors the same identity_assertion Literal in McpServerEntry.auth, so MCP server JSON entries can now request a consumer-signed identity token, and both schemas must stay in sync.

Omitted 2 lower-signal changed files.

Sequence Diagram

sequenceDiagram
  participant Reviewer
  participant PR as Changed Files
  Reviewer->>PR: Inspect changed files and control flow
  Reviewer->>Reviewer: Validate security assumptions
Loading

Edit Gecko PR Settings | Reviewed commit: 04c659e

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed this PR and found no bugs. It is worth a human look because it changes which auth modes are accepted. Before this PR, a config with auth: identity_assertion failed validation. Now it passes, and what happens next depends on each consumer of this library.

What was reviewed:

  • The auth Literal in AuthenticationConfig (config_schema.py) and McpServerEntry (mcp_json_schema.py). The six values match in both, and no existing value or default changed.
  • resolve_mcp_servers in mcp_json_reader.py copies the value through unchanged. When oauth is set it still overrides auth to jwt_token, as it does for every other value. The only auto-set rule, headers, runs only when auth is unset.
  • Nothing else in languagemodelcommon/ branches on auth, so this library adds no behavior. A consumer on the new version that doesn't handle identity_assertion may fall back to its default path, which could mean forwarding the caller's token. Please check each consumer, not just baileyai-skills-service.
Extended reasoning...

The change adds one value to the auth Literal in two Pydantic schemas, rewords the field descriptions, and adds tests for accepting and rejecting values and for passing the value through .mcp.json resolution. The tests follow the keyword-only and parametrize conventions. No auth logic changes in this repo, and CODEOWNERS covers only AGENTS.md and CLAUDE.md. This is still a defer because the field controls how a caller's credentials reach MCP servers. A config that used to fail validation now passes, so whether that is safe depends on downstream services this review cannot see.

@alvinhenrick alvinhenrick left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at 04c659e.

What I checked:

  • config_schema.py (AuthenticationConfig.auth) and mcp_json_schema.py (McpServerEntry.auth): both Literals gain exactly identity_assertion, the six values match across the two schemas, and no default or existing value changed. Purely additive.
  • tests/configs/test_auth_values.py: these are real Pydantic validations, not mocks. The accept case is parametrized over all six values on both models. The reject case covers the near-miss identity-assertion and an empty string, which catches a typo'd config.
  • test_identity_assertion_auth_is_kept_as_is runs the real resolve_mcp_servers, so the pass-through is checked on the actual resolution path.

Non-blocking, for the release notes: once a consumer bumps to this version, configs with auth: identity_assertion validate where they used to fail. Any consumer that matches on auth (baileyai, mcp-fhir-agent, not just skills-service) needs either an explicit branch for the new value or a default branch that fails closed. Otherwise an unhandled value could fall through to a path that forwards the caller's token. Pin the skills-service floor as planned and check the other consumers' match defaults before they bump.

Single commit, Jira key present, no AI-attribution trailer. I can't verify CI status through this integration (the check-runs/status endpoints 403), so this approval rests on reading the diff, not on CI.

@imranq2

imranq2 commented Nov 9, 2026

Copy link
Copy Markdown
Contributor Author

EA Review: PR #171

Merge Readiness: READY_WITH_FIXES

Risk label: none present, and this repo has no label gate or classifier, so the tier is unknown. No label was applied by this run. CI: all checks pass (build_and_test, Check Commit Message, Gecko, Aikido).

Fixed during this review

  • Rule 01 (test gap): identity_assertion combined with oauth resolves to jwt_token, but no test asserted it. test_oauth_takes_precedence_over_pass_through_auth is now parametrized over pass_through and identity_assertion (8532e0a).
  • Rule 04 / REVIEW.md rule 4 (consumers named): the PR body now lists the consumers affected and how each was checked, including that no consumer suite was run against a build of this change.

Should-fix

  • Rule 08 (architectural sign-off), open question. identity_assertion introduces a consumer-signed token mode, and this diff carries no ADR, Tech Design Review or EA sign-off reference; the field description is the only record of the design. Please confirm (a) where the mode was decided (ticket, ADR or TDR) and (b) that the token is a standard OAuth/OIDC assertion profile rather than a bespoke scheme, per the org baseline. Suggestion: add an MADR under adrs/ covering the signer, audience and consumer contract, or record the EA confirmation on the PR.

Nits

  • Rule 10: the six-value auth Literal and its description are hand-maintained in config_schema.py and mcp_json_schema.py. The duplication predates this PR, which extends it. Suggestion: a shared AuthMode alias, tracked as a follow-up ticket rather than done here (minimal diff).
  • Rule 09: "identity assertion" is often used for an assertion issued by an identity provider, while here the consumer signs it. Suggestion: confirm the term against the team glossary.

Other

  • baileyai-skills-service registry_loader.py:262 has a docstring listing the old five values; it should be updated in that repo's PR (#385).
  • No issues found for the remaining rules; rules 05, 14, 15, 16, 18, 21, 22, 25 and 28 are not applicable to this diff.

@imranq2
imranq2 merged commit 7a5a093 into main Nov 9, 2026
7 checks passed
@imranq2
imranq2 deleted the IQ-BAI-1609 branch November 9, 2026 16:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants