feat: support External IdP authentication and current Claude Code clients

[robert-mcdermott]

Summary

This PR improves compatibility with current Kiro IDE enterprise sessions and Claude Code clients.

It adds:

• External OIDC identity-provider authentication, including Microsoft Entra ID
• Support for Claude Code inline system messages
• Additional fallback model identifiers currently exposed by Kiro IDE

Motivation

Current Kiro IDE versions may authenticate enterprise users through an external OIDC provider. These credentials contain fields such as:

• authMethod: "external_idp"
• clientId
• issuerUrl
• tokenEndpoint
• scopes

The gateway previously classified these credentials as Kiro Desktop authentication and sent the refresh token to:

https://prod.<region>.auth.desktop.kiro.dev/refreshToken

That endpoint rejects External IdP refresh tokens with HTTP 401.

Additionally, current Claude Code versions can place system-role messages inside the messages array. The gateway's Anthropic request model rejected these requests during Pydantic validation with HTTP 422.

Changes

External IdP authentication

• Add an EXTERNAL_IDP authentication type
• Detect credentials using authMethod: "external_idp" or provider: "ExternalIdp"
• Refresh access tokens through the OIDC tokenEndpoint recorded by Kiro
• Use the OAuth public-client refresh-token grant without requiring a client secret
• Normalize string and list-based OIDC scopes
• Persist rotated access and refresh tokens to JSON credentials or the kiro-cli SQLite database
• Reload credentials managed by Kiro before refreshing an expiring token
• Reload credentials once after a 400 or 401 response in case Kiro rotated the refresh token
• Retry rate-limit, server, timeout, and transport failures with bounded exponential backoff
• Send the required TokenType: EXTERNAL_IDP header to Kiro runtime and MCP endpoints
• Discover the selected profileArn from Kiro IDE extension storage when it is absent from the credential file
• Derive the API region from the discovered profile ARN when possible

Security

External IdP endpoints are validated before use:

• The token endpoint must use HTTPS
• Embedded URL credentials are rejected
• When an issuer URL is available, its host must match the token endpoint host
• Tokens and credentials are not written to logs

Claude Code compatibility

• Accept system as an Anthropic message role
• Extract inline system messages before converting conversation history
• Promote their text into Kiro's system prompt
• Combine inline instructions with the standard top-level Anthropic system field
• Preserve the original user and assistant message ordering
• Keep the actual user prompt as Kiro's active message
• Support the same request shape for streaming, non-streaming, and /v1/messages/count_tokens
• Continue rejecting unknown roles such as developer

This fixes errors such as:

422 Input should be 'user' or 'assistant'
location: body.messages.1.role
input: system

Fallback model list

Add the following model identifiers to the fallback /v1/models response:

• claude-opus-5
• claude-sonnet-5
• claude-opus-4.8
• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna

These entries help clients that require model selection from /v1/models. Model resolution remains pass-through, so Kiro remains the final authority on whether a model is available to the authenticated account.

Documentation

• Document External IdP credential detection and refresh behavior
• Document automatic Kiro IDE profile ARN discovery
• Document Claude Code inline system-message compatibility
• Update the architecture documentation and .env.example

Testing

Full test suite:

uv run pytest -q
1732 passed, 4 warnings

Coverage includes:

• External IdP detection from JSON and SQLite credentials
• Scope normalization
• Refresh-token rotation and persistence
• Credential reload after authentication failure
• Transient failure retries and retry exhaustion
• Invalid, mismatched, or unsafe provider endpoints
• Missing and malformed provider responses
• Runtime and MCP TokenType headers
• Profile ARN and region discovery
• Inline system-message validation and extraction
• Multiple and empty inline system messages
• Combined top-level and inline system prompts
• Streaming and non-streaming Anthropic requests
• Claude Code token-count requests
• Fallback model advertisement and exact model resolution

Manual verification

Verified with:

• Kiro IDE authenticated through a company Microsoft Entra ID tenant
• External IdP credentials managed by the running Kiro IDE
• Gateway running locally on port 9001
• Successful model discovery and streaming completions
• A Claude Code-shaped request containing a user message followed by an inline system message

The previously failing Claude Code request now returns HTTP 200 and a valid Anthropic SSE response.

[cla-bot]

Thanks for the PR! 🎉

Before merge, we need a one-time CLA confirmation.
It confirms that you have the right to contribute this code and allow the project to use it.

Full CLA text:
https://github.com/jwadow/kiro-gateway/blob/main/CLA.md

Please reply once with:

I have read the CLA and I accept its terms

You need to write once, all further messages from me can be ignored.

[robert-mcdermott]

I have read the CLA and I accept its terms

[ankitcharolia]

@robert-mcdermott could you please give a try to this gateway: https://github.com/ankitcharolia/kiro-gateway

It works quite well with All AI harness and actively being developed. The most important thing is that it is ACP compliant. Happy to have your Feedback. Thank you!