0
# Authentication & Configuration
1
2
Flexible authentication mechanisms and configuration options for AWS service integration, supporting multiple credential types, custom client configurations, and regional deployment patterns.
3
4
## Capabilities
5
6
### Credential Types
7
8
Core credential types supported across all @langchain/aws classes for AWS service authentication.
9
10
```typescript { .api }
11
/**
12
* AWS credential types supporting various authentication methods
13
*/
14
type CredentialType = AwsCredentialIdentity | Provider<AwsCredentialIdentity>;
15
16
interface AwsCredentialIdentity {
17
/** AWS access key ID */
18
accessKeyId: string;
19
20
/** AWS secret access key */
21
secretAccessKey: string;
22
23
/** Optional session token for temporary credentials */
24
sessionToken?: string;
25
26
/** Optional expiration time for temporary credentials */
27
expiration?: Date;
28
}
29
30
/**
31
* Provider function for dynamic credential resolution
32
*/
33
type Provider<T> = () => Promise<T>;
34
```
35
36
### Authentication Methods
37
38
#### 1. Environment Variables
39
40
The most common authentication method using environment variables.
41
42
**For Traditional AWS Credentials:**
43
```bash
44
export BEDROCK_AWS_REGION="us-east-1"
45
export BEDROCK_AWS_SECRET_ACCESS_KEY="your-secret-access-key"
46
export BEDROCK_AWS_ACCESS_KEY_ID="your-access-key-id"
47
48
# Alternative region setting
49
export AWS_DEFAULT_REGION="us-east-1"
50
```
51
52
**For API Key Authentication:**
53
```bash
54
export BEDROCK_AWS_REGION="us-east-1"
55
export AWS_BEARER_TOKEN_BEDROCK="your-bearer-token"
56
```
57
58
**Usage Examples:**
59
60
```typescript
61
import { ChatBedrockConverse, BedrockEmbeddings } from "@langchain/aws";
62
63
// Automatically uses environment variables
64
const chatModel = new ChatBedrockConverse({
65
region: process.env.BEDROCK_AWS_REGION ?? "us-east-1"
66
// credentials will be automatically loaded from environment
67
});
68
69
const embeddings = new BedrockEmbeddings({
70
region: process.env.BEDROCK_AWS_REGION ?? "us-east-1",
71
model: "amazon.titan-embed-text-v1"
72
// credentials automatically loaded
73
});
74
```
75
76
#### 2. Direct Credential Configuration
77
78
Programmatically provide credentials for fine-grained control.
79
80
**Usage Examples:**
81
82
```typescript
83
// Direct credential specification
84
const chatModel = new ChatBedrockConverse({
85
region: "us-east-1",
86
credentials: {
87
accessKeyId: "AKIA...",
88
secretAccessKey: "...",
89
sessionToken: "..." // Optional for temporary credentials
90
},
91
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
92
});
93
94
// Using credentials from external source
95
const dynamicCredentials = {
96
accessKeyId: await getAccessKeyFromSecretManager(),
97
secretAccessKey: await getSecretKeyFromSecretManager()
98
};
99
100
const embeddings = new BedrockEmbeddings({
101
region: "us-west-2",
102
credentials: dynamicCredentials,
103
model: "amazon.titan-embed-text-v1"
104
});
105
```
106
107
#### 3. AWS Profile-Based Authentication
108
109
Leverage AWS profiles for different environments and roles.
110
111
**Usage Examples:**
112
113
```typescript
114
import { fromIni } from "@aws-sdk/credential-provider-ini";
115
116
// Use specific AWS profile
117
const profileCredentials = fromIni({ profile: "production" });
118
119
const chatModel = new ChatBedrockConverse({
120
region: "us-east-1",
121
credentials: profileCredentials,
122
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
123
});
124
125
// With profile-specific configuration
126
const stagingCredentials = fromIni({
127
profile: "staging",
128
filepath: "~/.aws/credentials",
129
configFilepath: "~/.aws/config"
130
});
131
132
const stagingModel = new ChatBedrockConverse({
133
region: "us-west-2",
134
credentials: stagingCredentials
135
});
136
```
137
138
#### 4. IAM Role Authentication
139
140
Use IAM roles for EC2 instances, ECS tasks, or Lambda functions.
141
142
**Usage Examples:**
143
144
```typescript
145
import { fromInstanceMetadata } from "@aws-sdk/credential-provider-imds";
146
import { fromContainerMetadata } from "@aws-sdk/credential-provider-imds";
147
148
// For EC2 instances
149
const ec2Credentials = fromInstanceMetadata({
150
timeout: 1000,
151
maxRetries: 3
152
});
153
154
const ec2ChatModel = new ChatBedrockConverse({
155
region: "us-east-1",
156
credentials: ec2Credentials
157
});
158
159
// For ECS tasks
160
const ecsCredentials = fromContainerMetadata({
161
timeout: 1000,
162
maxRetries: 3
163
});
164
165
const ecsEmbeddings = new BedrockEmbeddings({
166
region: "us-east-1",
167
credentials: ecsCredentials,
168
model: "amazon.titan-embed-text-v1"
169
});
170
```
171
172
#### 5. AssumeRole Authentication
173
174
Assume IAM roles for cross-account access or enhanced security.
175
176
**Usage Examples:**
177
178
```typescript
179
import { fromTemporaryCredentials } from "@aws-sdk/credential-provider-sts";
180
181
// Assume role with MFA
182
const assumeRoleCredentials = fromTemporaryCredentials({
183
params: {
184
RoleArn: "arn:aws:iam::123456789012:role/CrossAccountRole",
185
RoleSessionName: "langchain-aws-session",
186
SerialNumber: "arn:aws:iam::123456789012:mfa/user-name",
187
TokenCode: "123456" // MFA token
188
}
189
});
190
191
const crossAccountModel = new ChatBedrockConverse({
192
region: "us-east-1",
193
credentials: assumeRoleCredentials
194
});
195
196
// Assume role with external ID
197
const externalIdCredentials = fromTemporaryCredentials({
198
params: {
199
RoleArn: "arn:aws:iam::123456789012:role/ExternalRole",
200
RoleSessionName: "external-session",
201
ExternalId: "unique-external-id"
202
}
203
});
204
```
205
206
#### 6. Web Identity Token Authentication
207
208
Use OIDC identity providers for authentication (useful for GitHub Actions, etc.).
209
210
**Usage Examples:**
211
212
```typescript
213
import { fromWebToken } from "@aws-sdk/credential-provider-web-identity";
214
215
// GitHub Actions OIDC
216
const githubCredentials = fromWebToken({
217
roleArn: "arn:aws:iam::123456789012:role/GitHubActionsRole",
218
webIdentityToken: process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN!,
219
roleSessionName: "github-actions-session"
220
});
221
222
const cicdModel = new ChatBedrockConverse({
223
region: "us-east-1",
224
credentials: githubCredentials
225
});
226
```
227
228
### Default Credential Provider Chain
229
230
The AWS SDK uses a credential provider chain that automatically tries multiple sources.
231
232
```typescript { .api }
233
/**
234
* Default credential provider chain configuration options
235
*/
236
interface DefaultProviderInit {
237
/** AWS profile name to use */
238
profile?: string;
239
240
/** Path to credentials file */
241
filepath?: string;
242
243
/** Path to config file */
244
configFilepath?: string;
245
246
/** Whether to ignore credential cache */
247
ignoreCache?: boolean;
248
249
/** MFA code provider function */
250
mfaCodeProvider?: (serialNumber: string) => Promise<string>;
251
252
/** Role assumer function */
253
roleAssumer?: (params: AssumeRoleParams) => Promise<Credentials>;
254
255
/** Role ARN to assume */
256
roleArn?: string;
257
258
/** Web identity token file path */
259
webIdentityTokenFile?: string;
260
261
/** Role assumer with web identity */
262
roleAssumerWithWebIdentity?: (params: AssumeRoleWithWebIdentityParams) => Promise<Credentials>;
263
}
264
```
265
266
**Usage Examples:**
267
268
```typescript
269
// Let AWS SDK automatically discover credentials
270
const autoModel = new ChatBedrockConverse({
271
region: "us-east-1"
272
// No credentials specified - uses default provider chain:
273
// 1. Environment variables
274
// 2. AWS credentials file
275
// 3. EC2/ECS instance metadata
276
// 4. AWS SSO
277
});
278
279
// Customize default provider chain
280
const customChainModel = new ChatBedrockConverse({
281
region: "us-east-1",
282
profile: "production",
283
ignoreCache: true,
284
mfaCodeProvider: async (serialNumber) => {
285
// Custom MFA code input logic
286
return await promptUserForMFACode(serialNumber);
287
}
288
});
289
```
290
291
### Client Configuration
292
293
Advanced client configuration options for performance tuning and customization.
294
295
#### BedrockRuntimeClient Configuration
296
297
```typescript { .api }
298
interface BedrockRuntimeClientConfig {
299
/** AWS region */
300
region?: string;
301
302
/** Credentials provider */
303
credentials?: CredentialType;
304
305
/** Custom endpoint URL */
306
endpoint?: string;
307
308
/** Maximum retry attempts */
309
maxAttempts?: number;
310
311
/** Request handler for HTTP configuration */
312
requestHandler?: RequestHandler;
313
314
/** Custom user agent */
315
customUserAgent?: string;
316
317
/** Disable host prefix injection */
318
disableHostPrefix?: boolean;
319
}
320
```
321
322
**Usage Examples:**
323
324
```typescript
325
import { NodeHttpHandler } from "@aws-sdk/node-http-handler";
326
import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
327
import https from "https";
328
329
// Custom client configuration
330
const customClientConfig = {
331
region: "us-east-1",
332
maxAttempts: 5,
333
requestHandler: new NodeHttpHandler({
334
connectionTimeout: 10000,
335
socketTimeout: 120000,
336
httpAgent: new https.Agent({
337
keepAlive: true,
338
maxSockets: 50
339
})
340
})
341
};
342
343
// Use with ChatBedrockConverse
344
const chatModel = new ChatBedrockConverse({
345
clientOptions: customClientConfig,
346
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
347
});
348
349
// Or provide custom client directly
350
const customClient = new BedrockRuntimeClient(customClientConfig);
351
const chatModelWithClient = new ChatBedrockConverse({
352
client: customClient
353
});
354
```
355
356
#### Kendra and Knowledge Base Client Configuration
357
358
```typescript { .api }
359
interface KendraClientConfig {
360
region?: string;
361
credentials?: CredentialType;
362
endpoint?: string;
363
maxAttempts?: number;
364
requestHandler?: RequestHandler;
365
}
366
367
interface BedrockAgentRuntimeClientConfig {
368
region?: string;
369
credentials?: CredentialType;
370
endpoint?: string;
371
maxAttempts?: number;
372
requestHandler?: RequestHandler;
373
}
374
```
375
376
**Usage Examples:**
377
378
```typescript
379
// Kendra with custom client options
380
const kendraRetriever = new AmazonKendraRetriever({
381
indexId: "your-index-id",
382
topK: 10,
383
region: "us-east-1",
384
clientOptions: {
385
maxAttempts: 3,
386
requestHandler: new NodeHttpHandler({
387
connectionTimeout: 5000,
388
socketTimeout: 30000
389
})
390
}
391
});
392
393
// Knowledge Base with custom configuration
394
const kbRetriever = new AmazonKnowledgeBaseRetriever({
395
knowledgeBaseId: "your-kb-id",
396
topK: 5,
397
region: "us-east-1",
398
clientOptions: {
399
maxAttempts: 3,
400
requestHandler: new NodeHttpHandler({
401
connectionTimeout: 8000,
402
socketTimeout: 60000
403
})
404
}
405
});
406
```
407
408
### Regional Configuration
409
410
Best practices for regional deployment and configuration.
411
412
**Usage Examples:**
413
414
```typescript
415
// Multi-region configuration
416
const regions = ["us-east-1", "us-west-2", "eu-west-1"];
417
418
const multiRegionModels = regions.map(region => ({
419
region,
420
model: new ChatBedrockConverse({
421
region,
422
model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
423
credentials: {
424
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
425
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
426
}
427
})
428
}));
429
430
// Smart region selection based on latency
431
async function selectOptimalRegion(testRegions: string[]): Promise<string> {
432
const latencyTests = testRegions.map(async region => {
433
const start = Date.now();
434
try {
435
const model = new ChatBedrockConverse({ region });
436
await model.invoke([new HumanMessage("test")]);
437
return { region, latency: Date.now() - start };
438
} catch (error) {
439
return { region, latency: Infinity };
440
}
441
});
442
443
const results = await Promise.all(latencyTests);
444
const optimal = results.reduce((best, current) =>
445
current.latency < best.latency ? current : best
446
);
447
448
return optimal.region;
449
}
450
```
451
452
### Error Handling and Debugging
453
454
Comprehensive error handling patterns for authentication and configuration issues.
455
456
**Usage Examples:**
457
458
```typescript
459
async function createAuthenticatedModel(): Promise<ChatBedrockConverse> {
460
try {
461
const model = new ChatBedrockConverse({
462
region: process.env.BEDROCK_AWS_REGION ?? "us-east-1",
463
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
464
});
465
466
// Test authentication with a simple call
467
await model.invoke([new HumanMessage("test")]);
468
return model;
469
470
} catch (error) {
471
if (error.name === "CredentialsProviderError") {
472
console.error("Authentication failed - check AWS credentials");
473
console.error("Ensure one of the following:");
474
console.error("1. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY");
475
console.error("2. AWS credentials file: ~/.aws/credentials");
476
console.error("3. IAM role for EC2/ECS instance");
477
console.error("4. AWS SSO profile");
478
} else if (error.name === "UnknownEndpoint") {
479
console.error("Invalid region or service not available in region");
480
} else if (error.name === "AccessDeniedException") {
481
console.error("Access denied - check IAM permissions for Bedrock");
482
} else {
483
console.error("Model initialization failed:", error.message);
484
}
485
throw error;
486
}
487
}
488
489
// Debug credential resolution
490
async function debugCredentials(): Promise<void> {
491
const { defaultProvider } = await import("@aws-sdk/credential-provider-node");
492
493
try {
494
const credentialProvider = defaultProvider();
495
const credentials = await credentialProvider();
496
497
console.log("Credentials resolved successfully:");
498
console.log("Access Key ID:", credentials.accessKeyId?.substring(0, 8) + "...");
499
console.log("Has Secret Key:", !!credentials.secretAccessKey);
500
console.log("Has Session Token:", !!credentials.sessionToken);
501
console.log("Expiration:", credentials.expiration);
502
503
} catch (error) {
504
console.error("Credential resolution failed:", error.message);
505
console.error("Check your AWS configuration:");
506
console.error("- aws configure list");
507
console.error("- aws sts get-caller-identity");
508
}
509
}
510
```
511
512
### Common AWS SDK Errors
513
514
Understanding and handling common error types that may occur when using @langchain/aws.
515
516
```typescript { .api }
517
/**
518
* Common AWS SDK error types and their meanings
519
*/
520
interface AWSErrorTypes {
521
CredentialsProviderError: "Authentication credentials not found or invalid";
522
UnknownEndpoint: "Invalid region or service not available in region";
523
AccessDeniedException: "Insufficient IAM permissions for the requested operation";
524
ThrottlingException: "Request rate limit exceeded, retry with exponential backoff";
525
ResourceNotFoundException: "Requested AWS resource (index, knowledge base, etc.) not found";
526
ValidationException: "Request parameters are invalid or malformed";
527
ServiceException: "AWS service encountered an internal error";
528
}
529
```
530
531
**Error Handling Examples:**
532
533
```typescript
534
import { ChatBedrockConverse } from "@langchain/aws";
535
import { HumanMessage } from "@langchain/core/messages";
536
537
async function robustChatModelUsage() {
538
const model = new ChatBedrockConverse({
539
region: "us-east-1",
540
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
541
});
542
543
try {
544
const response = await model.invoke([
545
new HumanMessage("Hello, world!")
546
]);
547
return response.content;
548
549
} catch (error: any) {
550
switch (error.name) {
551
case "CredentialsProviderError":
552
console.error("Authentication failed - check AWS credentials");
553
console.error("Solutions:");
554
console.error("1. Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY");
555
console.error("2. Configure AWS CLI: aws configure");
556
console.error("3. Use IAM roles for EC2/ECS instances");
557
break;
558
559
case "UnknownEndpoint":
560
console.error("Invalid region or service not available");
561
console.error("Check: region setting and Bedrock availability");
562
break;
563
564
case "AccessDeniedException":
565
console.error("Insufficient permissions");
566
console.error("Required IAM permissions:");
567
console.error("- bedrock:InvokeModel");
568
console.error("- bedrock:InvokeModelWithResponseStream");
569
break;
570
571
case "ThrottlingException":
572
console.error("Rate limit exceeded - implement retry logic");
573
// Implement exponential backoff
574
await new Promise(resolve => setTimeout(resolve, 1000));
575
// Retry the request
576
break;
577
578
case "ValidationException":
579
console.error("Invalid request parameters:", error.message);
580
break;
581
582
case "ServiceException":
583
console.error("AWS service error - retry may help:", error.message);
584
break;
585
586
default:
587
console.error("Unexpected error:", error.message);
588
}
589
throw error;
590
}
591
}
592
593
// Retry logic for transient errors
594
async function withRetry<T>(
595
operation: () => Promise<T>,
596
maxRetries: number = 3
597
): Promise<T> {
598
for (let attempt = 1; attempt <= maxRetries; attempt++) {
599
try {
600
return await operation();
601
} catch (error: any) {
602
const isRetryable = [
603
"ThrottlingException",
604
"ServiceException",
605
"InternalFailureException"
606
].includes(error.name);
607
608
if (!isRetryable || attempt === maxRetries) {
609
throw error;
610
}
611
612
// Exponential backoff: 1s, 2s, 4s, etc.
613
const delay = Math.pow(2, attempt - 1) * 1000;
614
console.log(`Retry attempt ${attempt} after ${delay}ms`);
615
await new Promise(resolve => setTimeout(resolve, delay));
616
}
617
}
618
throw new Error("Max retries exceeded");
619
}
620
621
// Usage with retry logic
622
const responseWithRetry = await withRetry(async () => {
623
return await model.invoke([new HumanMessage("Hello!")]);
624
});
625
```
626
627
### Security Best Practices
628
629
Guidelines for secure credential management and configuration.
630
631
**Best Practices:**
632
633
1. **Never hardcode credentials** in source code
634
2. **Use least privilege** IAM policies
635
3. **Rotate credentials** regularly
636
4. **Use temporary credentials** when possible
637
5. **Enable CloudTrail logging** for API calls
638
6. **Use VPC endpoints** for private communication
639
640
**Usage Examples:**
641
642
```typescript
643
// Secure configuration patterns
644
class SecureAWSConfiguration {
645
private static validateEnvironment(): void {
646
const requiredVars = ["BEDROCK_AWS_REGION"];
647
const missing = requiredVars.filter(v => !process.env[v]);
648
649
if (missing.length > 0) {
650
throw new Error(`Missing required environment variables: ${missing.join(", ")}`);
651
}
652
}
653
654
static createChatModel(): ChatBedrockConverse {
655
this.validateEnvironment();
656
657
return new ChatBedrockConverse({
658
region: process.env.BEDROCK_AWS_REGION!,
659
// Let AWS SDK handle credential resolution
660
// Never put credentials in code
661
model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
662
clientOptions: {
663
// Use secure configurations
664
maxAttempts: 3
665
}
666
});
667
}
668
669
static createEmbeddings(): BedrockEmbeddings {
670
this.validateEnvironment();
671
672
return new BedrockEmbeddings({
673
region: process.env.BEDROCK_AWS_REGION!,
674
model: "amazon.titan-embed-text-v1"
675
});
676
}
677
}
678
679
// Use in application
680
const secureModel = SecureAWSConfiguration.createChatModel();
681
const secureEmbeddings = SecureAWSConfiguration.createEmbeddings();
682
```
683
684
### Configuration Examples by Environment
685
686
#### Development Environment
687
688
```typescript
689
// Development with local AWS credentials
690
const devModel = new ChatBedrockConverse({
691
region: "us-east-1",
692
// Uses ~/.aws/credentials [default] profile
693
model: "anthropic.claude-3-haiku-20240307-v1:0", // Cheaper model for dev
694
temperature: 0.8,
695
maxTokens: 500
696
});
697
```
698
699
#### Production Environment
700
701
```typescript
702
// Production with IAM role
703
const prodModel = new ChatBedrockConverse({
704
region: process.env.AWS_REGION!, // From environment
705
model: "anthropic.claude-3-5-sonnet-20240620-v1:0",
706
temperature: 0.3,
707
maxTokens: 2000,
708
clientOptions: {
709
maxAttempts: 5,
710
requestHandler: new NodeHttpHandler({
711
connectionTimeout: 10000,
712
socketTimeout: 120000
713
})
714
}
715
});
716
```
717
718
#### CI/CD Environment
719
720
```typescript
721
// CI/CD with OIDC
722
const cicdModel = new ChatBedrockConverse({
723
region: "us-east-1",
724
credentials: fromWebToken({
725
roleArn: process.env.AWS_ROLE_ARN!,
726
webIdentityToken: process.env.ACTIONS_ID_TOKEN_REQUEST_TOKEN!,
727
roleSessionName: "github-actions"
728
}),
729
model: "anthropic.claude-3-5-sonnet-20240620-v1:0"
730
});
731
```