@trigger.dev/sdk 4.8.3 → 4.8.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/commonjs/v3/ai-shared.d.ts +3 -2
- package/dist/commonjs/v3/ai-shared.js +219 -28
- package/dist/commonjs/v3/ai-shared.js.map +1 -1
- package/dist/commonjs/v3/ai.d.ts +4 -0
- package/dist/commonjs/v3/ai.js +97 -87
- package/dist/commonjs/v3/ai.js.map +1 -1
- package/dist/commonjs/v3/auth.d.ts +1 -3
- package/dist/commonjs/v3/auth.js +1 -8
- package/dist/commonjs/v3/auth.js.map +1 -1
- package/dist/commonjs/v3/chat-server.js +3 -1
- package/dist/commonjs/v3/chat-server.js.map +1 -1
- package/dist/commonjs/v3/oidc/aws.d.ts +2 -0
- package/dist/commonjs/v3/oidc/aws.js +4 -1
- package/dist/commonjs/v3/oidc/aws.js.map +1 -1
- package/dist/commonjs/v3/oidc/infisical.d.ts +16 -0
- package/dist/commonjs/v3/oidc/infisical.js +43 -0
- package/dist/commonjs/v3/oidc/infisical.js.map +1 -0
- package/dist/commonjs/version.js +1 -1
- package/dist/esm/v3/ai-shared.d.ts +3 -2
- package/dist/esm/v3/ai-shared.js +214 -28
- package/dist/esm/v3/ai-shared.js.map +1 -1
- package/dist/esm/v3/ai.d.ts +4 -0
- package/dist/esm/v3/ai.js +98 -88
- package/dist/esm/v3/ai.js.map +1 -1
- package/dist/esm/v3/auth.d.ts +1 -3
- package/dist/esm/v3/auth.js +1 -8
- package/dist/esm/v3/auth.js.map +1 -1
- package/dist/esm/v3/chat-server.js +4 -2
- package/dist/esm/v3/chat-server.js.map +1 -1
- package/dist/esm/v3/oidc/aws.d.ts +2 -0
- package/dist/esm/v3/oidc/aws.js +4 -1
- package/dist/esm/v3/oidc/aws.js.map +1 -1
- package/dist/esm/v3/oidc/infisical.d.ts +16 -0
- package/dist/esm/v3/oidc/infisical.js +40 -0
- package/dist/esm/v3/oidc/infisical.js.map +1 -0
- package/dist/esm/version.js +1 -1
- package/docs/ai-chat/backend.mdx +2 -2
- package/docs/ai-chat/custom-agents.mdx +8 -1
- package/docs/ai-chat/lifecycle-hooks.mdx +4 -0
- package/docs/ai-chat/migrating-from-hydrate-messages.mdx +1 -1
- package/docs/ai-chat/transcript-storage.mdx +3 -1
- package/docs/apikeys/custom-access.mdx +209 -0
- package/docs/apikeys.mdx +50 -14
- package/docs/cli-preview-archive.mdx +8 -0
- package/docs/deployment/overview.mdx +2 -0
- package/docs/deployment/trusted-publishing.mdx +140 -0
- package/docs/github-actions.mdx +2 -2
- package/docs/oidc/anthropic.mdx +187 -0
- package/docs/oidc/aws.mdx +219 -0
- package/docs/oidc/custom.mdx +48 -0
- package/docs/oidc/infisical.mdx +59 -0
- package/docs/oidc.mdx +46 -233
- package/docs/self-hosting/env/webapp.mdx +7 -0
- package/docs/webhooks/public-beta.mdx +70 -0
- package/package.json +17 -2
|
@@ -0,0 +1,219 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect to AWS"
|
|
3
|
+
sidebarTitle: "AWS"
|
|
4
|
+
description: "Assume an IAM role from your tasks without storing AWS access keys."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use `awsCredentialProvider` to exchange a Trigger.dev OIDC token for temporary AWS credentials through STS. Pass it to your AWS SDK client to obtain and refresh credentials automatically.
|
|
8
|
+
|
|
9
|
+
Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
|
|
10
|
+
|
|
11
|
+
## Configure AWS
|
|
12
|
+
|
|
13
|
+
### Create an OIDC identity provider
|
|
14
|
+
|
|
15
|
+
In AWS IAM, add an OpenID Connect identity provider with:
|
|
16
|
+
|
|
17
|
+
- **Provider URL**: your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`.
|
|
18
|
+
- **Audience**: `sts.amazonaws.com`, the audience used by the SDK's AWS helper.
|
|
19
|
+
|
|
20
|
+
Reuse the provider if one already exists for this issuer in your AWS account.
|
|
21
|
+
|
|
22
|
+
### Create an IAM role
|
|
23
|
+
|
|
24
|
+
Create a role with this trust policy. Replace the AWS account ID and organization slug, and replace `YOUR_ENVIRONMENT_SUBJECT` with the **complete subject copied from the dashboard**.
|
|
25
|
+
|
|
26
|
+
```json
|
|
27
|
+
{
|
|
28
|
+
"Version": "2012-10-17",
|
|
29
|
+
"Statement": [
|
|
30
|
+
{
|
|
31
|
+
"Effect": "Allow",
|
|
32
|
+
"Principal": {
|
|
33
|
+
"Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.trigger.dev/YOUR_ORG_SLUG"
|
|
34
|
+
},
|
|
35
|
+
"Action": "sts:AssumeRoleWithWebIdentity",
|
|
36
|
+
"Condition": {
|
|
37
|
+
"StringEquals": {
|
|
38
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
|
|
39
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:sub": "YOUR_ENVIRONMENT_SUBJECT"
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Attach a permissions policy for the operations your task needs. For the S3 example below, allow `s3:GetObject` on `arn:aws:s3:::YOUR_BUCKET/trigger/*`. The trust policy controls who can assume the role; it does not grant S3 permissions. No session tags are required.
|
|
48
|
+
|
|
49
|
+
## Use the role in your task
|
|
50
|
+
|
|
51
|
+
Install the STS peer dependency and the AWS clients your task uses:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
npm install @trigger.dev/sdk@latest @aws-sdk/client-sts @aws-sdk/client-s3
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Replace the role ARN, region, bucket, and object key:
|
|
58
|
+
|
|
59
|
+
```typescript
|
|
60
|
+
import { task } from "@trigger.dev/sdk";
|
|
61
|
+
import { awsCredentialProvider } from "@trigger.dev/sdk/oidc/aws";
|
|
62
|
+
import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
|
|
63
|
+
|
|
64
|
+
export const readFromS3 = task({
|
|
65
|
+
id: "read-from-s3",
|
|
66
|
+
run: async () => {
|
|
67
|
+
const s3 = new S3Client({
|
|
68
|
+
region: "us-east-1",
|
|
69
|
+
credentials: awsCredentialProvider({
|
|
70
|
+
roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
|
|
71
|
+
region: "us-east-1",
|
|
72
|
+
}),
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
const result = await s3.send(
|
|
76
|
+
new GetObjectCommand({
|
|
77
|
+
Bucket: "YOUR_BUCKET",
|
|
78
|
+
Key: "trigger/example.txt",
|
|
79
|
+
}),
|
|
80
|
+
);
|
|
81
|
+
return { contents: await result.Body?.transformToString() };
|
|
82
|
+
},
|
|
83
|
+
});
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Redeploy with CLI 4.8.3 or later and start a new run on that deployment.
|
|
87
|
+
|
|
88
|
+
<Warning>
|
|
89
|
+
Create the AWS client inside `run` and reuse it only within that run. A
|
|
90
|
+
module-scope client can reuse a previous run's cached credentials and
|
|
91
|
+
attribute AWS activity to that run.
|
|
92
|
+
</Warning>
|
|
93
|
+
|
|
94
|
+
### Provider options
|
|
95
|
+
|
|
96
|
+
| Option | Required | Behavior |
|
|
97
|
+
| ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
|
|
98
|
+
| `roleArn` | Yes | IAM role to assume. |
|
|
99
|
+
| `region` | Yes | Region for STS. The AWS service client's region does not configure STS. |
|
|
100
|
+
| `roleSessionName` | No | Defaults to the current run ID, sanitized to AWS's allowed characters and limited to 64 characters. |
|
|
101
|
+
| `durationSeconds` | No | Defaults to 3,600 seconds (one hour), subject to the role's allowed session duration. |
|
|
102
|
+
| `sessionTags` | No | Defaults to `false`. Set to `true` to include verified identity tags. Requires `sts:TagSession` in the role trust policy. |
|
|
103
|
+
|
|
104
|
+
For local development, use your own AWS credential chain, such as an AWS SSO profile. If a task runs both locally and deployed, select local credentials explicitly when `ctx.environment.type === "DEVELOPMENT"`.
|
|
105
|
+
|
|
106
|
+
## Session tags and task-level access
|
|
107
|
+
|
|
108
|
+
By default, a role's trust policy only checks the environment subject, so **every task in that environment** can assume the role. Session tags let you restrict a role to specific tasks, or scope resource permissions by task. They are off by default; existing roles keep working unchanged.
|
|
109
|
+
|
|
110
|
+
Trigger.dev adds these tags to the signed token. Values come from the verified run, never from payloads or caller input:
|
|
111
|
+
|
|
112
|
+
| Tag | Value |
|
|
113
|
+
| --- | --- |
|
|
114
|
+
| `TriggerOrganizationId` | Organization ID |
|
|
115
|
+
| `TriggerProjectRef` | Project reference, such as `proj_...` |
|
|
116
|
+
| `TriggerEnvironmentId` | Environment ID |
|
|
117
|
+
| `TriggerEnvironmentType` | `PRODUCTION`, `STAGING`, or `PREVIEW` |
|
|
118
|
+
| `TriggerTaskId` | Task identifier, such as `read-from-s3` |
|
|
119
|
+
|
|
120
|
+
These are AWS session tags, not Trigger.dev run tags. They are not transitive across role chaining.
|
|
121
|
+
|
|
122
|
+
### Restrict a role to one task
|
|
123
|
+
|
|
124
|
+
1. Update the trust policy. Add `sts:TagSession` to `Action` and a `TriggerTaskId` condition. AWS rejects tagged tokens if `sts:TagSession` is missing.
|
|
125
|
+
|
|
126
|
+
```json
|
|
127
|
+
{
|
|
128
|
+
"Version": "2012-10-17",
|
|
129
|
+
"Statement": [
|
|
130
|
+
{
|
|
131
|
+
"Effect": "Allow",
|
|
132
|
+
"Principal": {
|
|
133
|
+
"Federated": "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.trigger.dev/YOUR_ORG_SLUG"
|
|
134
|
+
},
|
|
135
|
+
"Action": ["sts:AssumeRoleWithWebIdentity", "sts:TagSession"],
|
|
136
|
+
"Condition": {
|
|
137
|
+
"StringEquals": {
|
|
138
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
|
|
139
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:sub": "YOUR_ENVIRONMENT_SUBJECT",
|
|
140
|
+
"aws:RequestTag/TriggerTaskId": "read-from-s3"
|
|
141
|
+
}
|
|
142
|
+
}
|
|
143
|
+
}
|
|
144
|
+
]
|
|
145
|
+
}
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
2. Enable tags in the task with `@trigger.dev/sdk` 4.8.4 or later, then redeploy:
|
|
149
|
+
|
|
150
|
+
```typescript
|
|
151
|
+
awsCredentialProvider({
|
|
152
|
+
roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
|
|
153
|
+
region: "us-east-1",
|
|
154
|
+
sessionTags: true,
|
|
155
|
+
});
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Older SDKs reject `sessionTags` in TypeScript and silently ignore it in JavaScript, which sends untagged tokens that this policy rejects.
|
|
159
|
+
|
|
160
|
+
<Warning>
|
|
161
|
+
Don't keep another statement that allows untagged assumption for the same subject, or any
|
|
162
|
+
task can bypass the restriction. This protects against other tasks in the environment, not
|
|
163
|
+
against people who can deploy: anyone who can deploy to the environment can deploy a task
|
|
164
|
+
with the trusted ID.
|
|
165
|
+
</Warning>
|
|
166
|
+
|
|
167
|
+
To use tags only in permissions (below) without restricting tasks, add `sts:TagSession` to `Action` and omit the `aws:RequestTag` condition.
|
|
168
|
+
|
|
169
|
+
### Use tags in resource permissions
|
|
170
|
+
|
|
171
|
+
Tags are available in the role's permissions as `aws:PrincipalTag/...`. For example, one role can give each task its own S3 prefix:
|
|
172
|
+
|
|
173
|
+
```json
|
|
174
|
+
{
|
|
175
|
+
"Version": "2012-10-17",
|
|
176
|
+
"Statement": [
|
|
177
|
+
{
|
|
178
|
+
"Effect": "Allow",
|
|
179
|
+
"Action": "s3:GetObject",
|
|
180
|
+
"Resource": "arn:aws:s3:::YOUR_BUCKET/${aws:PrincipalTag/TriggerTaskId}/*"
|
|
181
|
+
}
|
|
182
|
+
]
|
|
183
|
+
}
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Without the helper
|
|
187
|
+
|
|
188
|
+
Request tags with `auth.getOIDCToken({ audience: "sts.amazonaws.com", awsSessionTags: true })`. Other audiences are rejected. Task IDs are sent unchanged, so a task ID that exceeds [AWS session tag limits](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html) makes the STS call fail.
|
|
189
|
+
|
|
190
|
+
## Trust all Preview branches
|
|
191
|
+
|
|
192
|
+
For a single Preview environment, use its exact subject. To allow **any task** across **all current and future Preview branches** in one project, start with the basic trust policy in [Create an IAM role](#create-an-iam-role) and replace its `Condition` with:
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"StringEquals": {
|
|
197
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com"
|
|
198
|
+
},
|
|
199
|
+
"StringLike": {
|
|
200
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:sub": "org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:PREVIEW:*"
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
For a task-restricted Preview role, keep `sts:TagSession` in `Action` and add the task condition to `StringEquals`:
|
|
206
|
+
|
|
207
|
+
```json
|
|
208
|
+
{
|
|
209
|
+
"StringEquals": {
|
|
210
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:aud": "sts.amazonaws.com",
|
|
211
|
+
"aws:RequestTag/TriggerTaskId": "read-from-s3"
|
|
212
|
+
},
|
|
213
|
+
"StringLike": {
|
|
214
|
+
"oidc.trigger.dev/YOUR_ORG_SLUG:sub": "org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:PREVIEW:*"
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
Keep the organization ID, project reference, `PREVIEW` environment type, and audience fixed. This deliberately grants access to anyone allowed to deploy a Preview branch in that project. Never wildcard the organization or project, or use this policy for a role intended only for Production or Staging.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Custom OIDC integrations"
|
|
3
|
+
sidebarTitle: "Custom integrations"
|
|
4
|
+
description: "Connect tasks to services without an official Trigger.dev OIDC integration."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Use `auth.getOIDCToken()` with a service that accepts external OIDC identities for workload authentication. You configure trust in that service and implement its authentication flow.
|
|
8
|
+
|
|
9
|
+
Support for OIDC user login does not necessarily mean a service accepts workload identities. Check the service's federation documentation before starting.
|
|
10
|
+
|
|
11
|
+
## Configure trust
|
|
12
|
+
|
|
13
|
+
Follow the [OIDC prerequisites](/oidc#prerequisites), then go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment and copy the issuer URL and subject.
|
|
14
|
+
|
|
15
|
+
In the receiving service:
|
|
16
|
+
|
|
17
|
+
1. Register your organization's issuer, `https://oidc.trigger.dev/YOUR_ORG_SLUG`, using its [discovery endpoint](/oidc#how-tokens-work) or signing keys as required.
|
|
18
|
+
2. Configure the expected audience. Use the service's required value, or choose one if it allows you to.
|
|
19
|
+
3. Restrict access to the exact environment subject, directly or through the service's identity-mapping rules.
|
|
20
|
+
4. Grant the identity only the permissions your task needs.
|
|
21
|
+
|
|
22
|
+
The service must verify the signature, issuer, audience, and expiry, and enforce the subject restriction. Trusting the issuer and audience alone does not isolate access to one environment.
|
|
23
|
+
|
|
24
|
+
## Request a token
|
|
25
|
+
|
|
26
|
+
Request a token inside your task with the exact audience configured in the receiving service:
|
|
27
|
+
|
|
28
|
+
```typescript
|
|
29
|
+
import { auth, task } from "@trigger.dev/sdk";
|
|
30
|
+
|
|
31
|
+
export const federatedTask = task({
|
|
32
|
+
id: "federated-task",
|
|
33
|
+
run: async () => {
|
|
34
|
+
const { token } = await auth.getOIDCToken({
|
|
35
|
+
audience: "https://service.example.com",
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
// Use the service's documented token exchange or authentication flow here.
|
|
39
|
+
// Never log or return the token.
|
|
40
|
+
},
|
|
41
|
+
});
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`auth.getOIDCToken({ audience })` returns `Promise<{ token: string; expiresAt: Date }>`.
|
|
45
|
+
|
|
46
|
+
Most services exchange the token for service-specific credentials. Follow their documentation for the endpoint, request format, and credential refresh behavior. Send the OIDC token directly as a bearer token only if the service explicitly supports that flow.
|
|
47
|
+
|
|
48
|
+
Keep tokens and credentials within the executing run and refresh before expiry. Redeploy with the updated CLI and SDK, then start a new run. For local Development runs, use the service's own development credentials instead.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: "Connect to Infisical"
|
|
3
|
+
sidebarTitle: "Infisical"
|
|
4
|
+
description: "Read secrets from Infisical using your task's workload identity."
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
Infisical support was added in **4.8.4**. Use `@trigger.dev/sdk` and the Trigger.dev CLI (`trigger.dev`) **4.8.4 or later**, then follow the [OIDC prerequisites](/oidc#prerequisites).
|
|
8
|
+
|
|
9
|
+
## Configure Infisical
|
|
10
|
+
|
|
11
|
+
1. In Infisical, create a **Machine Identity** and enable [OIDC Auth](https://infisical.com/docs/documentation/platform/identities/oidc-auth/general).
|
|
12
|
+
2. Go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your Trigger.dev environment and configure the identity with:
|
|
13
|
+
|
|
14
|
+
| Infisical field | Value |
|
|
15
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
|
|
16
|
+
| **OIDC Discovery URL** | Your issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`. Use the base URL, without `/.well-known/openid-configuration`. |
|
|
17
|
+
| **Issuer** | The same issuer URL. |
|
|
18
|
+
| **Subject** | The exact subject copied from the dashboard. No wildcard is needed. |
|
|
19
|
+
| **Audiences** | Your Infisical site URL, for example `https://us.infisical.com`. |
|
|
20
|
+
|
|
21
|
+
Leave **CA Certificate** blank. Set **Access Token TTL** and **Access Token Max TTL** to **900 seconds (15 minutes)** rather than relying on the defaults.
|
|
22
|
+
|
|
23
|
+
3. Add the identity to your Infisical project with read access only to the environments and secrets your task needs.
|
|
24
|
+
|
|
25
|
+
## Read a secret in your task
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
npm install @trigger.dev/sdk@latest @infisical/sdk
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import { task } from "@trigger.dev/sdk";
|
|
33
|
+
import { infisicalAccessToken } from "@trigger.dev/sdk/oidc/infisical";
|
|
34
|
+
import { InfisicalSDK } from "@infisical/sdk";
|
|
35
|
+
|
|
36
|
+
export const useSecret = task({
|
|
37
|
+
id: "use-secret",
|
|
38
|
+
run: async () => {
|
|
39
|
+
const siteUrl = "https://us.infisical.com";
|
|
40
|
+
const { accessToken } = await infisicalAccessToken({
|
|
41
|
+
identityId: "YOUR_INFISICAL_MACHINE_IDENTITY_ID",
|
|
42
|
+
siteUrl,
|
|
43
|
+
});
|
|
44
|
+
const client = new InfisicalSDK({ siteUrl });
|
|
45
|
+
client.auth().accessToken(accessToken);
|
|
46
|
+
|
|
47
|
+
const secret = await client.secrets().getSecret({
|
|
48
|
+
projectId: "YOUR_INFISICAL_PROJECT_ID",
|
|
49
|
+
environment: "prod",
|
|
50
|
+
secretName: "API_KEY",
|
|
51
|
+
});
|
|
52
|
+
// Use secret.secretValue here. Never log or return it.
|
|
53
|
+
},
|
|
54
|
+
});
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`siteUrl` defaults to `https://us.infisical.com`. Set it to `https://eu.infisical.com` for EU, or your self-hosted instance's URL. The audience defaults to `siteUrl` without a trailing slash; pass `audience` if your identity expects a different value. Optional `organizationSlug` scopes the session to an **Infisical** organization the identity can access.
|
|
58
|
+
|
|
59
|
+
The helper returns `{ accessToken, tokenType, expiresAt }` and does not cache tokens. Authenticate inside `run`, and call it again before `expiresAt` if your task needs access for longer than the configured token lifetime.
|
package/docs/oidc.mdx
CHANGED
|
@@ -1,262 +1,75 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "OpenID Connect (OIDC)"
|
|
3
|
-
|
|
3
|
+
sidebarTitle: "Overview"
|
|
4
|
+
description: "Use workload identity to access external services from your tasks without storing long-lived credentials."
|
|
4
5
|
---
|
|
5
6
|
|
|
6
|
-
|
|
7
|
-
OIDC is in private beta on Trigger.dev Cloud. [Contact us](https://trigger.dev/contact) to request
|
|
8
|
-
access.
|
|
9
|
-
</Note>
|
|
7
|
+
Trigger.dev uses **workload identity** in an OpenID Connect (OIDC) flow to let your tasks authenticate to external services without storing long-lived access keys.
|
|
10
8
|
|
|
11
|
-
|
|
9
|
+
Instead of saving a service's credentials as environment variables, configure it to trust Trigger.dev as an identity provider. Your task requests a signed, short-lived token that identifies its environment. The service verifies that identity and grants the permissions you configure, usually by exchanging the token for temporary credentials.
|
|
12
10
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
- Use `@trigger.dev/sdk` and the Trigger.dev CLI (`trigger.dev`) **4.8.3 or later**, including the CLI used by your CI or deployment integration.
|
|
16
|
-
- **Redeploy after upgrading the CLI**, then start a new run on the new deployment. Updating the SDK alone does not update the runner in an existing deployment. Replaying a run against an old deployment does not upgrade it.
|
|
17
|
-
- Request tokens inside the executing task attempt, in Production, Staging, or a Preview environment. Development runs do not receive internal run tokens.
|
|
18
|
-
|
|
19
|
-
## Set up AWS
|
|
20
|
-
|
|
21
|
-
<Steps>
|
|
22
|
-
<Step title="Select your deployed environment">
|
|
23
|
-
Open your project in the dashboard, select the Production, Staging, or Preview environment that
|
|
24
|
-
needs AWS access, then open [**OIDC**](https://cloud.trigger.dev/_/oidc) in the environment menu. Configure each environment separately.
|
|
25
|
-
</Step>
|
|
26
|
-
<Step title="Create an IAM OIDC identity provider">
|
|
27
|
-
In the AWS IAM console, open **Identity providers → Add provider → OpenID Connect**. Paste the
|
|
28
|
-
**Issuer URL** from the dashboard into **Provider URL** and use `sts.amazonaws.com` as the
|
|
29
|
-
**Audience**. You only need one provider per issuer in an AWS account; reuse it if it already exists.
|
|
30
|
-
|
|
31
|
-
Alternatively, use the AWS CLI with the exact issuer URL from the dashboard:
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
aws iam create-open-id-connect-provider \
|
|
35
|
-
--url "https://oidc.trigger.dev" \
|
|
36
|
-
--client-id-list sts.amazonaws.com
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
For Terraform-managed infrastructure, see [Terraform setup](#terraform-setup) below.
|
|
40
|
-
</Step>
|
|
41
|
-
<Step title="Create an IAM role with the exact trust policy">
|
|
42
|
-
Enter your AWS account ID in the dashboard setup page, then copy its trust policy into an IAM
|
|
43
|
-
role's **Trust relationships**. The policy allows `sts:AssumeRoleWithWebIdentity` only when both
|
|
44
|
-
the audience and the complete environment subject match.
|
|
45
|
-
|
|
46
|
-
Exact matching is the default. Keep the organization ID, project reference, environment type,
|
|
47
|
-
and audience fixed. To share a role across all Preview branches in one project, keep the
|
|
48
|
-
audience under `StringEquals` and use `StringLike` for only the subject. Replace the trust
|
|
49
|
-
policy's `Condition` with:
|
|
50
|
-
|
|
51
|
-
```json
|
|
52
|
-
{
|
|
53
|
-
"StringEquals": {
|
|
54
|
-
"oidc.trigger.dev:aud": "sts.amazonaws.com"
|
|
55
|
-
},
|
|
56
|
-
"StringLike": {
|
|
57
|
-
"oidc.trigger.dev:sub": "org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:PREVIEW:*"
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Replace the organization ID and project reference with the exact values from your dashboard
|
|
63
|
-
subject. This deliberately trusts all
|
|
64
|
-
current and future Preview branches in that project, including anyone allowed to deploy them.
|
|
65
|
-
Never wildcard the organization or project portions. Keep `PREVIEW` fixed so the role does not
|
|
66
|
-
also trust Production or Staging.
|
|
67
|
-
|
|
68
|
-
For a single Preview branch, use its persisted environment slug, not the parent environment's
|
|
69
|
-
identity or a branch display name. No session tags or `sts:TagSession` permission are required.
|
|
70
|
-
</Step>
|
|
71
|
-
<Step title="Attach a least-privilege permissions policy">
|
|
72
|
-
The trust policy controls who can assume the role. Attach a separate permissions policy that
|
|
73
|
-
controls what the role can do. For example, to read objects under one S3 prefix:
|
|
74
|
-
|
|
75
|
-
```json
|
|
76
|
-
{
|
|
77
|
-
"Version": "2012-10-17",
|
|
78
|
-
"Statement": [
|
|
79
|
-
{
|
|
80
|
-
"Effect": "Allow",
|
|
81
|
-
"Action": "s3:GetObject",
|
|
82
|
-
"Resource": "arn:aws:s3:::YOUR_BUCKET/trigger/*"
|
|
83
|
-
}
|
|
84
|
-
]
|
|
85
|
-
}
|
|
86
|
-
```
|
|
87
|
-
</Step>
|
|
88
|
-
<Step title="Install the SDK and AWS dependencies">
|
|
89
|
-
```bash
|
|
90
|
-
npm install @trigger.dev/sdk@latest @aws-sdk/client-sts @aws-sdk/client-s3
|
|
91
|
-
```
|
|
92
|
-
|
|
93
|
-
`@aws-sdk/client-sts` is an optional peer dependency of the Trigger.dev SDK. Install it explicitly
|
|
94
|
-
when using the AWS credential provider. Install the AWS service clients your task uses as well.
|
|
95
|
-
</Step>
|
|
96
|
-
<Step title="Use the credential provider and redeploy">
|
|
97
|
-
Replace the role ARN, AWS region, bucket, and object key below, or copy the personalized code
|
|
98
|
-
from the dashboard:
|
|
11
|
+
This gives you:
|
|
99
12
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
|
|
13
|
+
- **No stored access keys**: tasks obtain short-lived credentials when they need them.
|
|
14
|
+
- **Environment-specific access**: grant different permissions to Production, Staging, and individual Preview environments.
|
|
15
|
+
- **Organization-scoped trust**: each organization has its own issuer URL, `https://oidc.trigger.dev/YOUR_ORG_SLUG`.
|
|
104
16
|
|
|
105
|
-
|
|
106
|
-
id: "read-from-s3",
|
|
107
|
-
run: async () => {
|
|
108
|
-
const s3 = new S3Client({
|
|
109
|
-
region: "us-east-1",
|
|
110
|
-
credentials: awsCredentialProvider({
|
|
111
|
-
roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
|
|
112
|
-
region: "us-east-1",
|
|
113
|
-
}),
|
|
114
|
-
});
|
|
17
|
+
## Get started
|
|
115
18
|
|
|
116
|
-
|
|
117
|
-
new GetObjectCommand({ Bucket: "YOUR_BUCKET", Key: "trigger/example.txt" })
|
|
118
|
-
);
|
|
119
|
-
return { contents: await result.Body?.transformToString() };
|
|
120
|
-
},
|
|
121
|
-
});
|
|
122
|
-
```
|
|
19
|
+
Choose an official integration, or connect a service that supports external OIDC workload identities yourself.
|
|
123
20
|
|
|
124
|
-
|
|
125
|
-
npx trigger.dev@latest deploy
|
|
126
|
-
```
|
|
127
|
-
</Step>
|
|
128
|
-
</Steps>
|
|
21
|
+
### Official integrations
|
|
129
22
|
|
|
130
|
-
<
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
</
|
|
23
|
+
<CardGroup cols={2}>
|
|
24
|
+
<Card title="AWS" href="/oidc/aws">
|
|
25
|
+
Assume an IAM role using the SDK's AWS credential provider.
|
|
26
|
+
</Card>
|
|
27
|
+
<Card title="Anthropic" href="/oidc/anthropic">
|
|
28
|
+
Call Claude from tasks and chat agents without an API key.
|
|
29
|
+
</Card>
|
|
30
|
+
<Card title="Infisical" href="/oidc/infisical">
|
|
31
|
+
Read secrets using your task's workload identity.
|
|
32
|
+
</Card>
|
|
33
|
+
</CardGroup>
|
|
134
34
|
|
|
135
|
-
|
|
35
|
+
For other services, follow [Custom integrations](/oidc/custom) to request a token and implement the service's authentication flow.
|
|
136
36
|
|
|
137
|
-
##
|
|
138
|
-
|
|
139
|
-
Use these resources instead of creating the provider and role through the console. Copy the exact
|
|
140
|
-
issuer URL and subject from the environment's OIDC page into the input variables. This example uses
|
|
141
|
-
exact subject matching; attach a least-privilege permissions policy to the role separately, as in
|
|
142
|
-
the setup steps above.
|
|
143
|
-
|
|
144
|
-
```hcl
|
|
145
|
-
terraform {
|
|
146
|
-
required_providers {
|
|
147
|
-
aws = {
|
|
148
|
-
source = "hashicorp/aws"
|
|
149
|
-
}
|
|
150
|
-
}
|
|
151
|
-
}
|
|
152
|
-
|
|
153
|
-
provider "aws" {
|
|
154
|
-
region = "us-east-1"
|
|
155
|
-
}
|
|
156
|
-
|
|
157
|
-
variable "trigger_oidc_issuer" {
|
|
158
|
-
type = string
|
|
159
|
-
}
|
|
37
|
+
## Prerequisites
|
|
160
38
|
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
39
|
+
- Use `@trigger.dev/sdk` and the Trigger.dev CLI (`trigger.dev`) **4.8.3 or later**, including the CLI used in CI.
|
|
40
|
+
- **Redeploy after upgrading the CLI**, then start a new run on that deployment. Updating the SDK alone or replaying a run against an old deployment does not update its runner.
|
|
41
|
+
- Request tokens inside an executing task attempt in Production, Staging, or Preview. Local Development runs cannot mint OIDC tokens; use the service's local credentials instead.
|
|
164
42
|
|
|
165
|
-
|
|
166
|
-
issuer_host = trimsuffix(trimprefix(var.trigger_oidc_issuer, "https://"), "/")
|
|
167
|
-
}
|
|
43
|
+
## Connection details
|
|
168
44
|
|
|
169
|
-
|
|
170
|
-
url = var.trigger_oidc_issuer
|
|
171
|
-
client_id_list = ["sts.amazonaws.com"]
|
|
172
|
-
}
|
|
45
|
+
Go to the [OIDC](https://cloud.trigger.dev/_/oidc) page for your environment. Copy the exact values from that page when configuring your service.
|
|
173
46
|
|
|
174
|
-
|
|
175
|
-
|
|
47
|
+
| Value | Purpose |
|
|
48
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
49
|
+
| **Issuer URL** (`iss`) | Your organization's identity provider URL, such as `https://oidc.trigger.dev/YOUR_ORG_SLUG`. The service uses it to verify who issued the token. |
|
|
50
|
+
| **Subject** (`sub`) | Identifies your organization, project, and environment. The service uses it to decide which identity receives access. |
|
|
51
|
+
| **Audience** (`aud`) | Identifies the intended recipient. Request the value the service expects and configure it to require the same value. The AWS helper uses `sts.amazonaws.com`; other services may require something different. |
|
|
176
52
|
|
|
177
|
-
|
|
178
|
-
Version = "2012-10-17"
|
|
179
|
-
Statement = [{
|
|
180
|
-
Effect = "Allow"
|
|
181
|
-
Action = "sts:AssumeRoleWithWebIdentity"
|
|
182
|
-
Principal = {
|
|
183
|
-
Federated = aws_iam_openid_connect_provider.trigger.arn
|
|
184
|
-
}
|
|
185
|
-
Condition = {
|
|
186
|
-
StringEquals = {
|
|
187
|
-
"${local.issuer_host}:aud" = "sts.amazonaws.com"
|
|
188
|
-
"${local.issuer_host}:sub" = var.trigger_oidc_subject
|
|
189
|
-
}
|
|
190
|
-
}
|
|
191
|
-
}]
|
|
192
|
-
})
|
|
193
|
-
}
|
|
194
|
-
```
|
|
53
|
+
The audience is supplied when requesting a token, not a fixed setting on your environment. Some services require a particular value; others let you choose one. Checking only the issuer and audience is not enough to restrict access to one environment: configure an exact subject match or the service's equivalent identity mapping too.
|
|
195
54
|
|
|
196
|
-
|
|
55
|
+
Subjects have this format:
|
|
197
56
|
|
|
198
|
-
```
|
|
199
|
-
|
|
200
|
-
arn:aws:iam::YOUR_AWS_ACCOUNT_ID:oidc-provider/oidc.trigger.dev
|
|
57
|
+
```text
|
|
58
|
+
org:YOUR_ORG_ID:project:YOUR_PROJECT_REF:env:ENVIRONMENT_TYPE:ENVIRONMENT_SLUG
|
|
201
59
|
```
|
|
202
60
|
|
|
203
|
-
|
|
61
|
+
Copy the full subject rather than constructing it. For Preview environments, it uses the individual environment's persisted slug, not a branch display name. The subject stays the same across integrations and identifies every task in that environment, not an individual task.
|
|
204
62
|
|
|
205
|
-
|
|
206
|
-
More first-party OIDC integrations will be added soon.
|
|
207
|
-
</Note>
|
|
63
|
+
## How tokens work
|
|
208
64
|
|
|
209
|
-
|
|
65
|
+
Tokens are signed with `RS256` and expire after five minutes. They include the issuer, subject, audience, issue time (`iat`), and expiry (`exp`). Credentials issued by the receiving service can have a different lifetime.
|
|
210
66
|
|
|
211
|
-
|
|
212
|
-
import { auth, task } from "@trigger.dev/sdk";
|
|
67
|
+
Services can discover your organization's issuer at:
|
|
213
68
|
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
run: async () => {
|
|
217
|
-
const { token } = await auth.getOIDCToken({ audience: "https://service.example.com" });
|
|
218
|
-
// Exchange this token using your service's federation API. Never log the token.
|
|
219
|
-
const response = await fetch("https://service.example.com/federated-resource", {
|
|
220
|
-
headers: { Authorization: `Bearer ${token}` },
|
|
221
|
-
});
|
|
222
|
-
if (!response.ok) throw new Error(`Service request failed: ${response.status}`);
|
|
223
|
-
return response.json();
|
|
224
|
-
},
|
|
225
|
-
});
|
|
69
|
+
```text
|
|
70
|
+
https://oidc.trigger.dev/YOUR_ORG_SLUG/.well-known/openid-configuration
|
|
226
71
|
```
|
|
227
72
|
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
Token-request failures throw `OIDCTokenError`, exported from `@trigger.dev/sdk`, for both local validation and API errors. It extends `ApiError` and preserves the error code, message, HTTP status and headers; API failures retain the original error as `cause`.
|
|
231
|
-
|
|
232
|
-
## Local development
|
|
233
|
-
|
|
234
|
-
`trigger dev` does not receive internal run tokens and cannot mint external OIDC tokens. Use your own development credentials, such as an AWS SSO profile. If the same task needs to work locally and deployed, explicitly choose local credentials for Development:
|
|
235
|
-
|
|
236
|
-
```typescript
|
|
237
|
-
import { task } from "@trigger.dev/sdk";
|
|
238
|
-
import { awsCredentialProvider } from "@trigger.dev/sdk/oidc/aws";
|
|
239
|
-
import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";
|
|
240
|
-
|
|
241
|
-
export const readFromS3 = task({
|
|
242
|
-
id: "read-from-s3",
|
|
243
|
-
run: async (_, { ctx }) => {
|
|
244
|
-
const s3 = new S3Client({
|
|
245
|
-
region: "us-east-1",
|
|
246
|
-
credentials:
|
|
247
|
-
ctx.environment.type === "DEVELOPMENT"
|
|
248
|
-
? undefined // Use your own local AWS credential chain, for example AWS_PROFILE.
|
|
249
|
-
: awsCredentialProvider({
|
|
250
|
-
roleArn: "arn:aws:iam::YOUR_AWS_ACCOUNT_ID:role/YOUR_ROLE_NAME",
|
|
251
|
-
region: "us-east-1",
|
|
252
|
-
}),
|
|
253
|
-
});
|
|
254
|
-
const result = await s3.send(
|
|
255
|
-
new GetObjectCommand({ Bucket: "YOUR_BUCKET", Key: "trigger/example.txt" })
|
|
256
|
-
);
|
|
257
|
-
return { contents: await result.Body?.transformToString() };
|
|
258
|
-
},
|
|
259
|
-
});
|
|
260
|
-
```
|
|
73
|
+
Public signing keys are available at `https://oidc.trigger.dev/YOUR_ORG_SLUG/.well-known/jwks.json`. Configure the service to validate the token's signature, issuer, audience, expiry, and authorized subject. Merely decoding a token does not verify it.
|
|
261
74
|
|
|
262
|
-
|
|
75
|
+
Keep tokens and credentials within the executing run. Do not log them, return them as task output, or silently fall back to static credentials if OIDC fails in a deployed environment. OIDC tokens for external services cannot be used to call Trigger.dev APIs.
|