Registry / messaging / aws-msk-iam-sasl-signer-js

aws-msk-iam-sasl-signer-js

library1.0.3jsnpmunverified

A library for signing Kafka client connections to Amazon MSK using IAM authentication via SASL/SCRAM or OAUTHBEARER. Current stable version is 1.0.3, released in 2023 with monthly minor updates. It integrates with the AWS SDK for JavaScript v3 to fetch credentials and generates auth tokens for Kafka clients like KafkaJS. Key differentiators: native AWS IAM support without custom JAAS configs, full ESM/TypeScript support, and minimal dependencies. Compared to manual signing, it handles token refresh and credential resolution automatically. Requires Node.js 14+. Ships bundled type definitions.

messaging

npm install aws-msk-iam-sasl-signer-js

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · AWS-MSK-IAM-SASL-S

aws-msk-iam-sasl-signer-js

messagingjavascriptv1.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

generateAuthToken

✓ import { generateAuthToken } from 'aws-msk-iam-sasl-signer-js'

✗ const generateAuthToken = require('aws-msk-iam-sasl-signer-js/generateAuthToken')

Default export is not available. Must use named import. The package is ESM-only for Node 14+.

generateAuthTokenFromProfile

✓ import { generateAuthTokenFromProfile } from 'aws-msk-iam-sasl-signer-js'

✗ const { generateAuthTokenFromProfile } = require('aws-msk-iam-sasl-signer-js')

Works in both ESM and CJS environments if using a bundler that handles ESM properly. Avoid require() in pure CJS.

generateAuthTokenFromRole

✓ import { generateAuthTokenFromRole } from 'aws-msk-iam-sasl-signer-js'

✗ const generateAuthTokenFromRole = require('aws-msk-iam-sasl-signer-js').default

There is no default export. Using .default will return undefined.

generateAuthTokenFromCredentialsProvider

✓ import { generateAuthTokenFromCredentialsProvider } from 'aws-msk-iam-sasl-signer-js'

Accepts any AWS credential provider (e.g., from @aws-sdk/credential-providers). TypeScript types are included.

Demonstrates basic producer setup with KafkaJS and IAM OAuth bearer token provider using default credentials.

import { Kafka } from 'kafkajs'; import { generateAuthToken } from 'aws-msk-iam-sasl-signer-js'; async function oauthBearerTokenProvider(region: string) { const authTokenResponse = await generateAuthToken({ region }); return { value: authTokenResponse.token }; } const kafka = new Kafka({ clientId: 'my-app', brokers: ['kafka1:9092', 'kafka2:9092'], ssl: true, sasl: { mechanism: 'oauthbearer', oauthBearerProvider: () => oauthBearerTokenProvider('us-east-1') } }); async function run() { const producer = kafka.producer(); await producer.connect(); await producer.send({ topic: 'test-topic', messages: [{ value: 'Hello KafkaJS user!' }] }); await producer.disconnect(); } run().catch(console.error);

Debug

Known issues

deprecatedThe @aws-sdk packages used internally may become deprecated; monitor AWS SDK v3 releases.

fix

Update to latest version of aws-msk-iam-sasl-signer-js when available.

affects: >=1.0.0

gotchaThe token is valid for 15 minutes by default; token refresh must be handled by the Kafka client (e.g., oauthBearerProvider).

fix

Ensure your oauthBearerProvider is called on each new connection or token expiry; KafkaJS does this automatically.

affects: >=1.0.0

gotchaIf using EC2 IAM roles, the credentials may not be immediately available; the provider chain can fail with 'CredentialsError'.

fix

Use explicit credential provider (e.g., fromNodeProviderChain) with retries or fallback.

affects: >=1.0.0

breakingVersion 1.0.0 changed the return shape of generateAuthToken from { token: string } to { token: string, tokenExpiry: number }.

fix

If you relied on tokenExpiry before, check the return value. Add type guards if using TypeScript.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: generateAuthToken is not a function

Importing incorrectly, e.g., using require on ESM package without bundler support.

fix

Use ESM import syntax or configure your bundler to handle ESM properly. Example: import { generateAuthToken } from 'aws-msk-iam-sasl-signer-js'

ERROR: CredentialsProviderError: Could not load credentials from any providers

No AWS credentials found in environment variables, credential file, or IAM role.

fix

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables, or configure a credential profile, or run on an EC2 with IAM role.

Error [ERR_REQUIRE_ESM]: require() of ES Module

Using CommonJS require() on an ESM-only package in Node.js <14 or with type:"commonjs" in package.json.

fix

Use import() dynamic import or switch to ESM by adding type:"module" to your package.json or use .mjs extension.

Upgrade

Version history

1.0.3latest on npm

Audit

Dependencies

@aws-sdk/credential-provider-nodeoptionalUses default credential provider chain when no explicit provider given

kafkajsoptionalCommon integration target; not required by signer but needed to use the token

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/aws/aws-msk-iam-sasl-signer-js ↗

packageaws-msk-iam-sasl-signer-js ↗

homepagehttps://github.com/aws/aws-msk-iam-sasl-signer-js#readme ↗