Skip to content

Commit f527f90

Browse files
Add provider-local workload identity federation for Anthropic and OpenAI (#10512)
Co-authored-by: Tim Smart <[email protected]>
1 parent f056504 commit f527f90

13 files changed

Lines changed: 1312 additions & 11 deletions
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"effect": patch
3+
"@effect/ai-anthropic": patch
4+
"@effect/ai-openai": patch
5+
---
6+
7+
Add `WorkloadIdentity` helpers for Anthropic and OpenAI authentication, and report OpenAI WebSocket client-transform failures as `AiError` instead of defects.
Lines changed: 213 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,213 @@
1+
/**
2+
* The `AnthropicWorkloadIdentity` module authenticates `AnthropicClient` with
3+
* [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation).
4+
*
5+
* @stability unstable
6+
* @since 4.1.3
7+
*/
8+
import * as WorkloadIdentity from "effect/ai/WorkloadIdentity"
9+
import * as Effect from "effect/Effect"
10+
import * as HttpClient from "effect/http/HttpClient"
11+
import * as HttpClientRequest from "effect/http/HttpClientRequest"
12+
import * as Layer from "effect/Layer"
13+
import type * as Redacted from "effect/Redacted"
14+
15+
const OAUTH_BETA = "oauth-2025-04-20"
16+
const FEDERATION_BETA = "oidc-federation-2026-04-01"
17+
18+
const withOAuthBeta = (request: HttpClientRequest.HttpClientRequest): HttpClientRequest.HttpClientRequest => {
19+
const betas = request.headers["anthropic-beta"]?.split(",").map((beta) => beta.trim()).filter(Boolean) ?? []
20+
return betas.includes(OAUTH_BETA)
21+
? request
22+
: HttpClientRequest.setHeader(request, "anthropic-beta", [...betas, OAUTH_BETA].join(","))
23+
}
24+
25+
/**
26+
* Options for authenticating Anthropic requests with Workload Identity
27+
* Federation.
28+
*
29+
* @see {@link make} for creating a client transform from these options
30+
* @see {@link layer} for providing a transformed `HttpClient` from these options
31+
*
32+
* @stability unstable
33+
* @category options
34+
* @since 4.1.3
35+
*/
36+
export type Options<E = never, R = never> = {
37+
/**
38+
* Produces the identity token to exchange. Runs again on every exchange.
39+
*/
40+
readonly identityToken: Effect.Effect<Redacted.Redacted<string>, E, R>
41+
/**
42+
* Tagged ID (`fdrl_...`) of the federation rule to evaluate.
43+
*/
44+
readonly federationRuleId: string
45+
/**
46+
* UUID of the Anthropic organization.
47+
*/
48+
readonly organizationId: string
49+
/**
50+
* Tagged ID (`svac_...`) of the service account the token acts as.
51+
*/
52+
readonly serviceAccountId?: string | undefined
53+
/**
54+
* Tagged ID (`wrkspc_...`) of the workspace to scope the token to. Required
55+
* when the federation rule is enabled for more than one workspace.
56+
*/
57+
readonly workspaceId?: string | undefined
58+
/**
59+
* The base URL of the Anthropic API, used for the token exchange. Pass the
60+
* same value as the `apiUrl` option of `AnthropicClient`.
61+
*
62+
* @default "https://api.anthropic.com"
63+
*/
64+
readonly apiUrl?: string | undefined
65+
}
66+
67+
/**
68+
* Creates an `HttpClient` transform that authenticates Anthropic requests with
69+
* Workload Identity Federation.
70+
*
71+
* **When to use**
72+
*
73+
* Use as the `transformClient` option of `AnthropicClient` instead of an API key.
74+
*
75+
* **Details**
76+
*
77+
* The first request runs `identityToken` and exchanges the result at
78+
* `${apiUrl}/v1/oauth/token` with the `jwt-bearer` grant. The access token is
79+
* cached and sent as `Authorization: Bearer` with the `oauth-2025-04-20` beta
80+
* until shortly before it expires. Concurrent requests share one exchange.
81+
* `identityToken` runs again on every exchange, so a token read from a file is
82+
* picked up after it rotates. Surrounding whitespace is trimmed.
83+
*
84+
* Exchanges use the `HttpClient` captured by `make`, not the transformed client.
85+
* Failures are `HttpClientError`s, mapped to `AiError` by `AnthropicClient`.
86+
* A failing or empty `identityToken` produces an `EncodeError`. Source failures
87+
* are preserved as causes and must not contain secrets. Exchange errors redact
88+
* the literal identity token, including JSON-escaped occurrences.
89+
*
90+
* **Gotchas**
91+
*
92+
* - No background refresh: the next request after expiry waits for an exchange.
93+
* - A 401 invalidates only the token used by that request, without replay.
94+
* - The exchange client must not follow redirects or log request bodies.
95+
* `FetchHttpClient` redirects are disabled; redirect responses fail the exchange.
96+
* - Anthropic accepts an identity token with a `jti` claim once, so the
97+
* exchange is never retried and `identityToken` must yield a new token for
98+
* each exchange.
99+
* - The token URL must use `https`, or `http` on `localhost`, `127.0.0.1` or
100+
* `::1`. Any other URL is a defect.
101+
* - Leave the `apiKey` option of `AnthropicClient` unset.
102+
*
103+
* **Example** (Reading a projected Kubernetes token)
104+
*
105+
* ```ts
106+
* import { AnthropicClient, AnthropicWorkloadIdentity } from "@effect/ai-anthropic"
107+
* import { Effect, FileSystem, Layer, Redacted } from "effect"
108+
*
109+
* // Provide an `HttpClient` and a `FileSystem` to this layer.
110+
* const AnthropicLayer = Layer.unwrap(Effect.gen(function*() {
111+
* const fs = yield* FileSystem.FileSystem
112+
* const transformClient = yield* AnthropicWorkloadIdentity.make({
113+
* identityToken: Effect.map(
114+
* fs.readFileString("/var/run/secrets/anthropic.com/token"),
115+
* Redacted.make
116+
* ),
117+
* federationRuleId: "fdrl_...",
118+
* organizationId: "00000000-0000-0000-0000-000000000000",
119+
* serviceAccountId: "svac_..."
120+
* })
121+
* return AnthropicClient.layer({ transformClient })
122+
* }))
123+
* ```
124+
*
125+
* @see {@link layer} for providing the transformed `HttpClient` as a layer
126+
*
127+
* @stability unstable
128+
* @category constructors
129+
* @since 4.1.3
130+
*/
131+
export const make = <E = never, R = never>(options: Options<E, R>): Effect.Effect<
132+
(client: HttpClient.HttpClient) => HttpClient.HttpClient,
133+
never,
134+
HttpClient.HttpClient | R
135+
> =>
136+
Effect.map(
137+
WorkloadIdentity.make({
138+
tokenUrl: `${options.apiUrl ?? "https://api.anthropic.com"}/v1/oauth/token`,
139+
identityToken: options.identityToken,
140+
exchangeRequest: (request, assertion) =>
141+
request.pipe(
142+
HttpClientRequest.setHeader("anthropic-beta", `${OAUTH_BETA},${FEDERATION_BETA}`),
143+
HttpClientRequest.bodyJsonUnsafe({
144+
grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
145+
assertion,
146+
federation_rule_id: options.federationRuleId,
147+
organization_id: options.organizationId,
148+
service_account_id: options.serviceAccountId,
149+
workspace_id: options.workspaceId
150+
})
151+
)
152+
}),
153+
(transform) => (client) => transform(HttpClient.mapRequest(client, withOAuthBeta))
154+
)
155+
156+
/**
157+
* Provides the current `HttpClient` authenticated with workload identity federation.
158+
*
159+
* **When to use**
160+
*
161+
* Use with `Layer.provide` to authenticate `AnthropicClient` without
162+
* setting its `transformClient` option.
163+
*
164+
* **Details**
165+
*
166+
* Applies `make` to the current client, which also performs token exchanges.
167+
* The layer requires the services needed by `identityToken`.
168+
*
169+
* **Gotchas**
170+
*
171+
* - Every request carries the access token regardless of URL. Provide this
172+
* layer only to `AnthropicClient`, not the whole application.
173+
* - The gotchas of `make` apply.
174+
*
175+
* **Example** (Providing an authenticated client to `AnthropicClient`)
176+
*
177+
* ```ts
178+
* import { AnthropicClient, AnthropicWorkloadIdentity } from "@effect/ai-anthropic"
179+
* import { Effect, FileSystem, Layer, Redacted } from "effect"
180+
*
181+
* const WorkloadIdentity = AnthropicWorkloadIdentity.layer({
182+
* identityToken: Effect.gen(function*() {
183+
* const fs = yield* FileSystem.FileSystem
184+
* return Redacted.make(yield* fs.readFileString("/var/run/secrets/anthropic.com/token"))
185+
* }),
186+
* federationRuleId: "fdrl_...",
187+
* organizationId: "00000000-0000-0000-0000-000000000000",
188+
* serviceAccountId: "svac_..."
189+
* })
190+
*
191+
* // Requires an `HttpClient` and a `FileSystem`.
192+
* const AnthropicLayer = AnthropicClient.layer({}).pipe(
193+
* Layer.provide(WorkloadIdentity)
194+
* )
195+
* ```
196+
*
197+
* @see {@link make} for the client transform this layer applies
198+
*
199+
* @stability unstable
200+
* @category layers
201+
* @since 4.1.3
202+
*/
203+
export const layer = <E = never, R = never>(
204+
options: Options<E, R>
205+
): Layer.Layer<HttpClient.HttpClient, never, HttpClient.HttpClient | R> =>
206+
Layer.effect(
207+
HttpClient.HttpClient,
208+
Effect.gen(function*() {
209+
const client = yield* HttpClient.HttpClient
210+
const transform = yield* make(options)
211+
return transform(client)
212+
})
213+
)

‎packages/ai/anthropic/src/index.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,12 @@ export * as AnthropicTelemetry from "./AnthropicTelemetry.ts"
4141
*/
4242
export * as AnthropicTool from "./AnthropicTool.ts"
4343

44+
/**
45+
* @stability unstable
46+
* @since 4.1.3
47+
*/
48+
export * as AnthropicWorkloadIdentity from "./AnthropicWorkloadIdentity.ts"
49+
4450
/**
4551
* @stability unstable
4652
* @since 4.0.0
Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
import { AnthropicClient, AnthropicWorkloadIdentity } from "@effect/ai-anthropic"
2+
import { assert, describe, it } from "@effect/vitest"
3+
import { Effect, Layer, Redacted } from "effect"
4+
import { HttpClient, type HttpClientRequest, HttpClientResponse } from "effect/http"
5+
6+
const IDENTITY_TOKEN = "identity.token.signature"
7+
const TOKEN_URL = "https://api.anthropic.com/v1/oauth/token"
8+
9+
describe("AnthropicWorkloadIdentity", () => {
10+
it.effect("exchanges the identity token and adds the OAuth beta to authenticated requests", () =>
11+
Effect.gen(function*() {
12+
const http = makeHttp()
13+
const client = yield* HttpClient.HttpClient.pipe(
14+
Effect.provide(AnthropicWorkloadIdentity.layer({
15+
...options,
16+
serviceAccountId: "svac_1",
17+
workspaceId: "wrkspc_1"
18+
})),
19+
Effect.provideService(HttpClient.HttpClient, http.client)
20+
)
21+
22+
yield* client.get("https://api.anthropic.com/v1/messages", {
23+
headers: { "anthropic-beta": "files-api-2025-04-14" }
24+
})
25+
26+
const [exchange, request] = http.requests
27+
assert.strictEqual(exchange.url, TOKEN_URL)
28+
assert.isUndefined(exchange.headers.authorization)
29+
assert.strictEqual(exchange.headers["anthropic-beta"], "oauth-2025-04-20,oidc-federation-2026-04-01")
30+
assert.deepStrictEqual(bodyJson(exchange), {
31+
grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
32+
assertion: IDENTITY_TOKEN,
33+
federation_rule_id: "fdrl_1",
34+
organization_id: "org_1",
35+
service_account_id: "svac_1",
36+
workspace_id: "wrkspc_1"
37+
})
38+
assert.strictEqual(request.headers.authorization, "Bearer access-1")
39+
assert.strictEqual(request.headers["anthropic-beta"], "files-api-2025-04-14,oauth-2025-04-20")
40+
}))
41+
42+
it.effect("maps a rejected exchange to an AiError without the identity token", () =>
43+
Effect.gen(function*() {
44+
const http = makeHttp(() =>
45+
new Response(
46+
JSON.stringify({
47+
type: "error",
48+
error: { type: "authentication_error", message: `Authentication failed for ${IDENTITY_TOKEN}` }
49+
}).replaceAll(".", "\\u002e"),
50+
{ status: 401, headers: { "www-authenticate": `Bearer error_description="${IDENTITY_TOKEN}"` } }
51+
)
52+
)
53+
const client = yield* AnthropicClient.AnthropicClient.pipe(
54+
Effect.provide(AnthropicClient.layer({}).pipe(Layer.provide(AnthropicWorkloadIdentity.layer(options)))),
55+
Effect.provideService(HttpClient.HttpClient, http.client)
56+
)
57+
58+
const error = yield* Effect.flip(client.createMessage({
59+
payload: { model: "claude-sonnet-4-20250514", max_tokens: 1, messages: [{ role: "user", content: "hello" }] }
60+
}))
61+
62+
assert.strictEqual(error.reason._tag, "AuthenticationError")
63+
assert.include(error.message, "Authentication failed for <redacted>")
64+
}))
65+
})
66+
67+
const options = {
68+
identityToken: Effect.succeed(Redacted.make(IDENTITY_TOKEN)),
69+
federationRuleId: "fdrl_1",
70+
organizationId: "org_1"
71+
}
72+
73+
const makeHttp = (token = () => Response.json({ access_token: "access-1", expires_in: 3600 })) => {
74+
const requests: Array<HttpClientRequest.HttpClientRequest> = []
75+
const client = HttpClient.make((request) => {
76+
requests.push(request)
77+
return Effect.succeed(HttpClientResponse.fromWeb(request, request.url === TOKEN_URL ? token() : new Response()))
78+
})
79+
return { client, requests }
80+
}
81+
82+
const bodyJson = (request: HttpClientRequest.HttpClientRequest) =>
83+
request.body._tag === "Uint8Array" ? JSON.parse(new TextDecoder().decode(request.body.body)) : undefined
Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { AnthropicClient, AnthropicConfig } from "@effect/ai-anthropic"
2+
import { HttpClient } from "effect/http"
3+
import { describe, expect, it } from "tstyche"
4+
5+
describe("AnthropicWorkloadIdentity", () => {
6+
it("leaves the existing client transforms accepted", () => {
7+
expect(AnthropicClient.layer).type.toBeCallableWith({ transformClient: HttpClient.timeout("30 seconds") })
8+
expect(AnthropicClient.layer).type.toBeCallableWith({ transformClient: HttpClient.filterStatusOk })
9+
expect(AnthropicClient.layer).type.toBeCallableWith({ transformClient: (client: HttpClient.HttpClient) => client })
10+
expect(AnthropicConfig.withClientTransform).type.toBeCallableWith(HttpClient.timeout("30 seconds"))
11+
expect(AnthropicConfig.withClientTransform).type.toBeCallableWith(HttpClient.filterStatusOk)
12+
expect(AnthropicConfig.withClientTransform).type.toBeCallableWith((client: HttpClient.HttpClient) => client)
13+
})
14+
})

0 commit comments

Comments
 (0)