feat(auth): add Entra ID identity provider integration for Redis client authentication #2877

bobymicroby · 2024-12-05T14:54:43Z

Description

This PR adds Microsoft Entra ID (formerly Azure AD) authentication support to node-redis through:

New @redis/entraid package providing:

Multiple auth flows (managed identity, client credentials, auth code with PKCE)
MSAL node library integration
Auth code PKCE flow sample
StreamingCredentialsProvider implementation for EntraID

Core client authentication refactoring:

CredentialsProvider interface for async and streaming credentials
TokenManager and support classes for automated token lifecycle management
Pluggable authentication mechanism via providers

This enables Redis Enterprise customers to authenticate using Entra ID identities. The architecture also allows custom CredentialProvider implementations for third-party Identity Provider integration.

Checklist

[x] npm test passes (new tests added for token management / streaming credential provider )
[ ] New code is mostly tested, except for some pending test coverage in the EntraID package.
[ ] docs are in progress

- Introduce new credential providers: AsyncCredentialsProvider, StreamingCredentialsProvider - Update client handshake process to use the new CredentialsProviders and to support async credentials fetch / credentials refresh - Internal conversion of username/password to a CredentialsProvider - Modify URL parsing to accommodate the new authentication structure - Tests

packages/entraid/samples/auth-code-pkce/index.ts

bobymicroby · 2024-12-06T08:50:48Z

Note: I'm considering adding a sync-credentials-provider variant as well:

export interface SyncCredentialsProvider {
  readonly type: 'sync-credentials-provider';
  credentials: () => BasicAuth
}

Would appreciate thoughts on whether this negligible performance optimization is worth the additional API surface area.

dhensby

Looks lovely, and much more thorough and thought-out than my minimal-effort approach in #2849

❤️

dhensby · 2024-12-06T08:59:32Z

packages/client/lib/client/authx/index.ts

+import { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';
+export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError };


Suggested change

import { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';

export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError };

export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';

I believe these import/export calls can be unified - though this may be a style-guide/preference thing.

@dhensby Sure, it makes total sense to unify them.

The idea behind the 'barrel' file initially was to create a proper export so users can import from @redis/client/authx :

"exports": { ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "./authx": { "types": "./dist/lib/client/authx/index.d.ts", "default": "./dist/lib/client/authx/index.js" },

But then I found out that we already have imports in peer packages using paths like @redis/client/lib/ and even @redis/client/dist/ and many others... This can be addressed in one of these ways:

Adding more explicit exports (not ideal):

"./index": { "types": "./dist/index.d.ts", "default": "./dist/index.js" }, "./authx": { "types": "./dist/lib/client/authx/index.d.ts", "default": "./dist/lib/client/authx/index.js" }, "./lib/commands/generic-transformers": { "types": "./dist/lib/commands/generic-transformers.d.ts", "default": "./dist/lib/commands/generic-transformers.js" }, "./dist/*": { "types": "./dist/*.d.ts", "default": "./dist/*.js" }, "./lib/errors": { "types": "./dist/lib/errors.d.ts", "default": "./dist/lib/errors.js" }

Not using exports at all, keeping it as is and creating a barrel file just for user convenience

Creating a separate submodule containing only the authx support classes

For now, I've decided to stick with not using exports, but I'm considering creating a separate submodule for the authx support classes.

dhensby · 2024-12-06T09:16:27Z

packages/client/lib/client/authx/token-manager.spec.ts

+  /**
+   * Helper function to delay execution for a given number of milliseconds.
+   * @param ms
+   */
+  const delay = (ms: number) => {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }


async setTimeout is now built into node, there used to be a utility in redis for this which I think was removed in preference of the built-in functionality which is being used extensively in other tests.

Thanks @dhensby! I'll switch to using the built-ins

dhensby · 2024-12-06T09:18:47Z

packages/client/lib/client/authx/token-manager.spec.ts

+
+    describe('error scenarios', () => {
+      it('should not recover if retries are not enabled', async () => {
+        const clock = new FakeClock(0);


node allows synthetic clocks, so it may be preferred to use them over a custom faked clock?

Thanks @dhensby! You're the second node developer to suggest using node's synthetic timers. While I have a slight preference for avoiding global method replacements like setTimeout/Date.now() , you're right - it would be better to align with common practices. I'll switch to using Node's synthetic timers instead of my custom Clock approach.

dhensby · 2024-12-06T09:26:49Z

packages/client/lib/client/authx/credentials-provider.ts

@@ -0,0 +1,103 @@
+import {Disposable} from './types';


Would it be worth using TS 5.2 "native" Disposable interface (https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)

@dhensby makes total sense, i will use the built-in Disposable, thanks for the tip!

Symbol.dispose is not meant to be called directly, but to be used together with using and automatically called when the "using variable" goes out of scope (see the example from the typescript article). I don't think it fits here..

see https://github.com/tc39/proposal-explicit-resource-management for more details..

That isn't my interpretation of the spec (regarding not calling it directly). In fact it has this comment (emphasis mine):

Explicit Resource Management — Indicates a system whereby the lifetime of a "resource" is managed explicitly by the user either imperatively (by directly calling a method like Symbol.dispose) or declaratively (through a block-scoped declaration like using).^[1]

^[1]https://github.com/tc39/proposal-explicit-resource-management?tab=readme-ov-file#definitions

Preventing direct calls of the dispose method would be problematic for polyfills and also nested disposal of resources.

However, you are right that the using keyword will dispose of the resource when the variable falls out of the scope, so cleanup will need to be imperative rather than declarative. My recommendation was to use the native Dispose interface rather than re-implementing it idiosyncratically, which may be confusing given the interface and behaviour is defined in typescript already.

dhensby · 2024-12-06T09:39:51Z

Note: I'm considering adding a sync-credentials-provider variant as well:

I don't think there is any need for a sync-credentials-provider. async functions that instantly resolve are treated essentially as sync in the node runtime and if await is used instead of .then() (which it is) non-asynchronous functions could still be provided if the consumer wanted to take that risk (which they shouldn't) and it'll "just work".

bobymicroby · 2024-12-06T13:01:45Z

Note: I'm considering adding a sync-credentials-provider variant as well:

I don't think there is any need for a sync-credentials-provider. async functions that instantly resolve are treated essentially as sync in the node runtime and if await is used instead of .then() (which it is) non-asynchronous functions could still be provided if the consumer wanted to take that risk (which they shouldn't) and it'll "just work".

@dhensby I agree - I don't think adding a sync-credentials-provider would provide meaningful value. While Node.js optimizes immediately-resolving Promises, shaving off a few nanoseconds (possibly by avoiding the microtask queue) probably isn't worth the additional API surface area. Let's keep the API surface focused and minimal.

Introduces TokenManager and supporting classes to handle token acquisition, automatic refresh, and updates via identity providers. This foundation enables consistent authentication token management across different identity provider implementations. Key additions: - Add TokenManager to obtain and maintain auth tokens from identity providers with automated refresh scheduling based on TTL and configurable thresholds - Add IdentityProvider interface for token acquisition from auth providers - Implement Token class for managing token state and TTL tracking - Include configurable retry mechanism with exponential backoff and jitter - Add comprehensive test suite covering refresh cycles and error handling This change establishes the core infrastructure needed for reliable token lifecycle management across different authentication providers.

Introduces Entra ID (former Azure AD) authentication support with multiple authentication flows and automated token lifecycle management. Key additions: - Add EntraIdCredentialsProvider for handling Entra ID authentication flows - Implement MSALIdentityProvider to integrate with MSAL/EntraID authentication library - Add support for multiple authentication methods: - Managed identities (system and user-assigned) - Client credentials with certificate - Client credentials with secret - Authorization Code flow with PKCE - Add factory class with builder methods for each authentication flow - Include sample Express server implementation for Authorization Code flow - Add comprehensive configuration options for authority and token management

- Add support for configuring replica authentication with 'masterauth' - Allow default client configuration during test cluster creation This improves the testing framework's flexibility by automatically configuring replica authentication when '--requirepass' is used and enabling custom client configurations across cluster nodes.

- Add integration tests for token renewal and re-authentication flows - Update credentials provider to use uniqueId as username instead of account username - Add test utilities for loading Redis endpoint configurations - Split TypeScript configs into separate files for samples and integration tests - Remove `@redis/authx` package and nest it under `@`

dmaier-redislabs

Looks good for me. We are going to release as pre-release first.

taraspos · 2025-02-06T16:03:38Z

Hey @dmaier-redislabs, @bobymicroby any ETA when pre-release is planned?

Handle enabling/changing redis password without application restart #821

bobymicroby · 2025-02-07T12:33:22Z

Hey @taraspos,
You can try using @redis/entraid:5.0.0-next.6 and @redis/client:5.0.0-next.6. Check out the "Getting Started" guide here - just make sure to use version 5.0.0-next.6 instead of the version mentioned in the guide.

We are currently working on adding more documentation and improving module exports. Stay tuned for upcoming updates.

npm show @redis/entraid


@redis/[email protected] | MIT | deps: 1 | versions: 1
Secure token-based authentication for Redis clients using Microsoft Entra ID (formerly Azure Active Directory).
https://github.com/redis/node-redis/tree/master/packages/entraid

keywords: redis

dist
.tarball: https://registry.npmjs.org/@redis/entraid/-/entraid-5.0.0-next.6.tgz
.shasum: 1158299468b44c22027b48b31922c01ed3954ad4
.integrity: sha512-vPdONpUocKpcjpgjmkfYL/AX79G4HL1Xtnxt/Ann9jz2NunAAt3WXsM8t4CMtcsW8QyQ9d/DfUnahce9//Hr+Q==
.unpackedSize: 47.7 kB

dependencies:
@azure/msal-node: ^2.16.1

maintainers:
- leibale <[email protected]>
- dmaier-redislabs <[email protected]>
- shaya-redis <[email protected]>

dist-tags:
latest: 5.0.0-next.6  next: 5.0.0-next.6

published a week ago by dmaier-redislabs <[email protected]>

…nt authentication (redis#2877) * feat(auth): refactor authentication mechanism to use CredentialsProvider - Introduce new credential providers: AsyncCredentialsProvider, StreamingCredentialsProvider - Update client handshake process to use the new CredentialsProviders and to support async credentials fetch / credentials refresh - Internal conversion of username/password to a CredentialsProvider - Modify URL parsing to accommodate the new authentication structure - Tests * feat(auth): auth extensions Introduces TokenManager and supporting classes to handle token acquisition, automatic refresh, and updates via identity providers. This foundation enables consistent authentication token management across different identity provider implementations. Key additions: - Add TokenManager to obtain and maintain auth tokens from identity providers with automated refresh scheduling based on TTL and configurable thresholds - Add IdentityProvider interface for token acquisition from auth providers - Implement Token class for managing token state and TTL tracking - Include configurable retry mechanism with exponential backoff and jitter - Add comprehensive test suite covering refresh cycles and error handling This change establishes the core infrastructure needed for reliable token lifecycle management across different authentication providers. * feat(auth): add Entra ID identity provider integration Introduces Entra ID (former Azure AD) authentication support with multiple authentication flows and automated token lifecycle management. Key additions: - Add EntraIdCredentialsProvider for handling Entra ID authentication flows - Implement MSALIdentityProvider to integrate with MSAL/EntraID authentication library - Add support for multiple authentication methods: - Managed identities (system and user-assigned) - Client credentials with certificate - Client credentials with secret - Authorization Code flow with PKCE - Add factory class with builder methods for each authentication flow - Include sample Express server implementation for Authorization Code flow - Add comprehensive configuration options for authority and token management * feat(test-utils): improve cluster testing - Add support for configuring replica authentication with 'masterauth' - Allow default client configuration during test cluster creation This improves the testing framework's flexibility by automatically configuring replica authentication when '--requirepass' is used and enabling custom client configurations across cluster nodes. * feat(auth): add EntraId integration tests - Add integration tests for token renewal and re-authentication flows - Update credentials provider to use uniqueId as username instead of account username - Add test utilities for loading Redis endpoint configurations - Split TypeScript configs into separate files for samples and integration tests - Remove `@redis/authx` package and nest it under `@`

github-advanced-security bot found potential problems Dec 5, 2024

View reviewed changes

packages/entraid/samples/auth-code-pkce/index.ts Dismissed Show dismissed Hide dismissed

packages/entraid/samples/auth-code-pkce/index.ts Fixed Show fixed Hide fixed

bobymicroby force-pushed the auth-credentials branch 5 times, most recently from 6302566 to cb2e186 Compare December 5, 2024 16:04

bobymicroby requested a review from leibale December 5, 2024 16:46

bobymicroby mentioned this pull request Dec 6, 2024

feat: add credentialProvider option when creating clients #2849

Closed

3 tasks

bobymicroby force-pushed the auth-credentials branch from cb2e186 to 332eb85 Compare December 6, 2024 08:38

bobymicroby force-pushed the auth-credentials branch from 332eb85 to a31045c Compare December 6, 2024 09:06

dhensby reviewed Dec 6, 2024

View reviewed changes

bobymicroby force-pushed the auth-credentials branch from a31045c to ce0fd1f Compare December 13, 2024 10:04

bobymicroby force-pushed the auth-credentials branch 4 times, most recently from bc8d1fe to d0cd508 Compare December 17, 2024 13:11

bobymicroby force-pushed the auth-credentials branch from d0cd508 to 0ce5e7a Compare January 8, 2025 11:46

bobymicroby force-pushed the auth-credentials branch 6 times, most recently from 2d82e6b to b326302 Compare January 16, 2025 12:44

bobymicroby force-pushed the auth-credentials branch 15 times, most recently from 98667ef to c37d42d Compare January 22, 2025 08:47

bobymicroby force-pushed the auth-credentials branch 3 times, most recently from 32fbf6f to 5fa5406 Compare January 27, 2025 12:22

bobymicroby requested review from dmaier-redislabs and tishun and removed request for leibale January 27, 2025 12:44

bobymicroby force-pushed the auth-credentials branch from 5fa5406 to 1173864 Compare January 27, 2025 13:10

bobymicroby force-pushed the auth-credentials branch from 1173864 to bcc4bc3 Compare January 30, 2025 08:10

dmaier-redislabs approved these changes Jan 30, 2025

View reviewed changes

dmaier-redislabs merged commit 6d21de3 into redis:master Jan 30, 2025
11 checks passed

taraspos mentioned this pull request Feb 6, 2025

Redis Signer for connecting to Redis 7 using IAM authentication aws/aws-sdk-js-v3#6611

Closed

2 tasks

		import { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError } from './token-manager';
		export { TokenManager, TokenManagerConfig, TokenStreamListener, RetryPolicy, IDPError };

feat(auth): add Entra ID identity provider integration for Redis client authentication #2877

feat(auth): add Entra ID identity provider integration for Redis client authentication #2877

Uh oh!

Conversation

bobymicroby commented Dec 5, 2024

Description

Checklist

Uh oh!

Uh oh!

Uh oh!

bobymicroby commented Dec 6, 2024

Uh oh!

dhensby left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dhensby commented Dec 6, 2024

Uh oh!

bobymicroby commented Dec 6, 2024

Uh oh!

dmaier-redislabs left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

taraspos commented Feb 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bobymicroby commented Feb 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

taraspos commented Feb 6, 2025 •

edited

Loading