grpc-node-oauth2

library1.2.0jsnpmunverified

gRPC interceptor for OAuth 2.0 client credentials flow in Node.js. Current version is 1.2.0. This library provides a gRPC interceptor that automatically manages OAuth 2.0 token acquisition, caching, and refresh, attaching the token as a metadata bearer token. It integrates with @grpc/grpc-js and supports TypeScript. Unlike manual token management, it handles retries and token expiry transparently. It is lightweight, with no other runtime dependencies beyond the gRPC library.

security

npm install grpc-node-oauth2

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-NODE-OAUTH2

grpc-node-oauth2

securityjavascriptv1.2.0

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.

createInterceptor

✓ import { createInterceptor } from 'grpc-node-oauth2'

✗ const createInterceptor = require('grpc-node-oauth2').createInterceptor

ESM import; CommonJS require also works but TypeScript exports favor named import.

InterceptorOptions

✓ import { InterceptorOptions } from 'grpc-node-oauth2'

Type-only import for TypeScript users.

Creates a gRPC interceptor for OAuth 2.0 client credentials and attaches it to a gRPC client.

import { createInterceptor } from 'grpc-node-oauth2'; import * as grpc from '@grpc/grpc-js'; const interceptor = createInterceptor({ clientId: process.env.OAUTH_CLIENT_ID ?? '', clientSecret: process.env.OAUTH_CLIENT_SECRET ?? '', tokenUrl: 'https://example.com/oauth/token', retryIntervalMs: 10e3, retryMaxAttempts: 10, }); const client = new grpc.Client('localhost:50051', grpc.credentials.createInsecure(), { interceptors: [interceptor], });

Debug

Known issues

breakingv1.0.0 removed the old callback-based API; only async interceptor supported.

fix

Migrate to async interceptor using createInterceptor(options).

affects: <1.0.0

deprecatedPassing tokenUrl without trailing slash may cause issues with some OAuth servers.

fix

Ensure tokenUrl ends with proper path (e.g., '/token').

affects: >=0.0.0

gotchaInterceptorOptions.retryIntervalMs and retryMaxAttempts are required; no defaults.

fix

Always provide both retryIntervalMs and retryMaxAttempts.

affects: >=1.0.0

gotchaThe interceptor does not support refresh tokens; use client credentials flow only.

fix

If refresh token flow needed, consider alternative libraries or manual implementation.

affects: >=0.0.0

Errors

Common errors & fixes

Error: No interceptor options provided

createInterceptor() called without arguments or with empty object.

fix

Pass an object with required fields: clientId, clientSecret, tokenUrl, retryIntervalMs, retryMaxAttempts.

TypeError: clientId is not a string

clientId property is missing or not a string.

fix

Ensure clientId is a non-empty string.

Error: retryMaxAttempts must be a positive integer

retryMaxAttempts is not a number or is negative.

fix

Set retryMaxAttempts to a positive integer (e.g., 10).

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredpeer dependency: required for gRPC client interceptor API

Agent activity

14 hits · last 30 days

node

Resources

githubhttps://github.com/entwico/grpc-node-oauth2 ↗

packagegrpc-node-oauth2 ↗

homepagehttps://github.com/entwico/grpc-node-oauth2#readme ↗