Skip to content

Commit 8b4ed00

Browse files
bobymicrobybobymicroby
authored
feat(entraid): add support for azure identity (#2901)
This PR adds support for using Azure Identity's credential classes with Redis Enterprise Entra ID authentication. The main changes include: - Add a new factory method createForDefaultAzureCredential to enable using Azure Identity credentials - Add @azure/identity as a dependency to support the new authentication flow - Add support for DefaultAzureCredential, EnvironmentCredential, and any other TokenCredential implementation - Create a new AzureIdentityProvider to support DefaultAzureCredential - Update documentation and README with usage examples for DefaultAzureCredential - Add integration tests for the new authentication methods - Include a sample application demonstrating interactive browser authentication - Export constants for Redis scopes / credential mappers to simplify authentication configuration
1 parent 69d507a commit 8b4ed00

File tree

9 files changed

+655
-123
lines changed

9 files changed

+655
-123
lines changed

‎package-lock.json‎

Lines changed: 249 additions & 42 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎packages/entraid/README.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Secure token-based authentication for Redis clients using Microsoft Entra ID (fo
1111
- Managed identities (system-assigned and user-assigned)
1212
- Service principals (with or without certificates)
1313
- Authorization Code with PKCE flow
14+
- DefaultAzureCredential from @azure/identity
1415
- Built-in retry mechanisms for transient failures
1516

1617
## Installation
@@ -30,6 +31,7 @@ The first step to using @redis/entraid is choosing the right credentials provide
3031
- `createForClientCredentials`: Use when authenticating with a service principal using client secret
3132
- `createForClientCredentialsWithCertificate`: Use when authenticating with a service principal using a certificate
3233
- `createForAuthorizationCodeWithPKCE`: Use for interactive authentication flows in user applications
34+
- `createForDefaultAzureCredential`: Use when you want to leverage Azure Identity's DefaultAzureCredential
3335

3436
## Usage Examples
3537

@@ -82,6 +84,54 @@ const provider = EntraIdCredentialsProviderFactory.createForUserAssignedManagedI
8284
});
8385
```
8486

87+
### DefaultAzureCredential Authentication
88+
89+
tip: see a real sample here: [samples/interactive-browser/index.ts](./samples/interactive-browser/index.ts)
90+
91+
The DefaultAzureCredential from @azure/identity provides a simplified authentication experience that automatically tries different authentication methods based on the environment. This is especially useful for applications that need to work in different environments (local development, CI/CD, and production).
92+
93+
```typescript
94+
import { createClient } from '@redis/client';
95+
import { DefaultAzureCredential } from '@azure/identity';
96+
import { EntraIdCredentialsProviderFactory, REDIS_SCOPE_DEFAULT } from '@redis/entraid/dist/lib/entra-id-credentials-provider-factory';
97+
98+
// Create a DefaultAzureCredential instance
99+
const credential = new DefaultAzureCredential();
100+
101+
// Create a provider using DefaultAzureCredential
102+
const provider = EntraIdCredentialsProviderFactory.createForDefaultAzureCredential({
103+
// Use the same parameters you would pass to credential.getToken()
104+
credential,
105+
scopes: REDIS_SCOPE_DEFAULT, // The Redis scope
106+
// Optional additional parameters for getToken
107+
options: {
108+
// Any options you would normally pass to credential.getToken()
109+
},
110+
tokenManagerConfig: {
111+
expirationRefreshRatio: 0.8
112+
}
113+
});
114+
115+
const client = createClient({
116+
url: 'redis://your-host',
117+
credentialsProvider: provider
118+
});
119+
120+
await client.connect();
121+
```
122+
123+
#### Important Notes on Using DefaultAzureCredential
124+
125+
When using the `createForDefaultAzureCredential` method, you need to:
126+
127+
1. Create your own instance of `DefaultAzureCredential`
128+
2. Pass the same parameters to the factory method that you would use with the `getToken()` method:
129+
- `scopes`: The Redis scope (use the exported `REDIS_SCOPE_DEFAULT` constant)
130+
- `options`: Any additional options for the getToken method
131+
132+
This factory method creates a wrapper around DefaultAzureCredential that adapts it to the Redis client's
133+
authentication system, while maintaining all the flexibility of the original Azure Identity authentication.
134+
85135
## Important Limitations
86136

87137
### RESP2 PUB/SUB Limitations

‎packages/entraid/integration-tests/entraid-integration.spec.ts‎

Lines changed: 79 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
1+
import { DefaultAzureCredential, EnvironmentCredential } from '@azure/identity';
12
import { BasicAuth } from '@redis/client/dist/lib/authx';
23
import { createClient } from '@redis/client';
3-
import { EntraIdCredentialsProviderFactory } from '../lib/entra-id-credentials-provider-factory';
4+
import { EntraIdCredentialsProviderFactory, REDIS_SCOPE_DEFAULT } from '../lib/entra-id-credentials-provider-factory';
45
import { strict as assert } from 'node:assert';
56
import { spy, SinonSpy } from 'sinon';
67
import { randomUUID } from 'crypto';
@@ -51,6 +52,35 @@ describe('EntraID Integration Tests', () => {
5152
);
5253
});
5354

55+
it('client with DefaultAzureCredential should be able to authenticate/re-authenticate', async () => {
56+
57+
const azureCredential = new DefaultAzureCredential();
58+
59+
await runAuthenticationTest(() =>
60+
EntraIdCredentialsProviderFactory.createForDefaultAzureCredential({
61+
credential: azureCredential,
62+
scopes: REDIS_SCOPE_DEFAULT,
63+
tokenManagerConfig: {
64+
expirationRefreshRatio: 0.00001
65+
}
66+
})
67+
, { testingDefaultAzureCredential: true });
68+
});
69+
70+
it('client with EnvironmentCredential should be able to authenticate/re-authenticate', async () => {
71+
const envCredential = new EnvironmentCredential();
72+
73+
await runAuthenticationTest(() =>
74+
EntraIdCredentialsProviderFactory.createForDefaultAzureCredential({
75+
credential: envCredential,
76+
scopes: REDIS_SCOPE_DEFAULT,
77+
tokenManagerConfig: {
78+
expirationRefreshRatio: 0.00001
79+
}
80+
})
81+
, { testingDefaultAzureCredential: true });
82+
});
83+
5484
interface TestConfig {
5585
clientId: string;
5686
clientSecret: string;
@@ -83,15 +113,15 @@ describe('EntraID Integration Tests', () => {
83113
});
84114

85115
return {
86-
endpoints: await loadFromFile(requiredEnvVars.REDIS_ENDPOINTS_CONFIG_PATH),
87-
clientId: requiredEnvVars.AZURE_CLIENT_ID,
88-
clientSecret: requiredEnvVars.AZURE_CLIENT_SECRET,
89-
authority: requiredEnvVars.AZURE_AUTHORITY,
90-
tenantId: requiredEnvVars.AZURE_TENANT_ID,
91-
redisScopes: requiredEnvVars.AZURE_REDIS_SCOPES,
92-
cert: requiredEnvVars.AZURE_CERT,
93-
privateKey: requiredEnvVars.AZURE_PRIVATE_KEY,
94-
userAssignedManagedId: requiredEnvVars.AZURE_USER_ASSIGNED_MANAGED_ID
116+
endpoints: await loadFromFile(requiredEnvVars.REDIS_ENDPOINTS_CONFIG_PATH as string),
117+
clientId: requiredEnvVars.AZURE_CLIENT_ID as string,
118+
clientSecret: requiredEnvVars.AZURE_CLIENT_SECRET as string,
119+
authority: requiredEnvVars.AZURE_AUTHORITY as string,
120+
tenantId: requiredEnvVars.AZURE_TENANT_ID as string,
121+
redisScopes: requiredEnvVars.AZURE_REDIS_SCOPES as string,
122+
cert: requiredEnvVars.AZURE_CERT as string,
123+
privateKey: requiredEnvVars.AZURE_PRIVATE_KEY as string,
124+
userAssignedManagedId: requiredEnvVars.AZURE_USER_ASSIGNED_MANAGED_ID as string
95125
};
96126
};
97127

@@ -127,12 +157,22 @@ describe('EntraID Integration Tests', () => {
127157
}
128158
};
129159

130-
const validateTokens = (reAuthSpy: SinonSpy) => {
160+
/**
161+
* Validates authentication tokens generated during re-authentication
162+
*
163+
* @param reAuthSpy - The Sinon spy on the reAuthenticate method
164+
* @param skipUniqueCheckForDefaultAzureCredential - Skip the unique check for DefaultAzureCredential as there are no guarantees that the tokens will be unique
165+
* if the test is using default azure credential
166+
*/
167+
const validateTokens = (reAuthSpy: SinonSpy, skipUniqueCheckForDefaultAzureCredential: boolean) => {
131168
assert(reAuthSpy.callCount >= 1,
132169
`reAuthenticate should have been called at least once, but was called ${reAuthSpy.callCount} times`);
133170

134171
const tokenDetails: TokenDetail[] = reAuthSpy.getCalls().map(call => {
135172
const creds = call.args[0] as BasicAuth;
173+
if (!creds.password) {
174+
throw new Error('Expected password to be set in BasicAuth credentials');
175+
}
136176
const tokenPayload = JSON.parse(
137177
Buffer.from(creds.password.split('.')[1], 'base64').toString()
138178
);
@@ -146,38 +186,43 @@ describe('EntraID Integration Tests', () => {
146186
};
147187
});
148188

149-
// Verify unique tokens
150-
const uniqueTokens = new Set(tokenDetails.map(detail => detail.token));
151-
assert.equal(
152-
uniqueTokens.size,
153-
reAuthSpy.callCount,
154-
`Expected ${reAuthSpy.callCount} different tokens, but got ${uniqueTokens.size} unique tokens`
155-
);
189+
// we can't guarantee that the tokens will be unique when using DefaultAzureCredential
190+
if (!skipUniqueCheckForDefaultAzureCredential) {
191+
// Verify unique tokens
192+
const uniqueTokens = new Set(tokenDetails.map(detail => detail.token));
193+
assert.equal(
194+
uniqueTokens.size,
195+
reAuthSpy.callCount,
196+
`Expected ${reAuthSpy.callCount} different tokens, but got ${uniqueTokens.size} unique tokens`
197+
);
156198

157-
// Verify all tokens are not cached (i.e. have the same lifetime)
158-
const uniqueLifetimes = new Set(tokenDetails.map(detail => detail.lifetime));
159-
assert.equal(
160-
uniqueLifetimes.size,
161-
1,
162-
`Expected all tokens to have the same lifetime, but found ${uniqueLifetimes.size} different lifetimes: ${[uniqueLifetimes].join(', ')} seconds`
163-
);
199+
// Verify all tokens are not cached (i.e. have the same lifetime)
200+
const uniqueLifetimes = new Set(tokenDetails.map(detail => detail.lifetime));
201+
assert.equal(
202+
uniqueLifetimes.size,
203+
1,
204+
`Expected all tokens to have the same lifetime, but found ${uniqueLifetimes.size} different lifetimes: ${(Array.from(uniqueLifetimes).join(','))} seconds`
205+
);
164206

165-
// Verify that all tokens have different uti (unique token identifier)
166-
const uniqueUti = new Set(tokenDetails.map(detail => detail.uti));
167-
assert.equal(
168-
uniqueUti.size,
169-
reAuthSpy.callCount,
170-
`Expected all tokens to have different uti, but found ${uniqueUti.size} different uti in: ${[uniqueUti].join(', ')}`
171-
);
207+
// Verify that all tokens have different uti (unique token identifier)
208+
const uniqueUti = new Set(tokenDetails.map(detail => detail.uti));
209+
assert.equal(
210+
uniqueUti.size,
211+
reAuthSpy.callCount,
212+
`Expected all tokens to have different uti, but found ${uniqueUti.size} different uti in: ${(Array.from(uniqueUti).join(','))}`
213+
);
214+
}
172215
};
173216

174-
const runAuthenticationTest = async (setupCredentialsProvider: () => any) => {
217+
const runAuthenticationTest = async (setupCredentialsProvider: () => any, options: {
218+
testingDefaultAzureCredential: boolean
219+
} = { testingDefaultAzureCredential: false }) => {
175220
const { client, reAuthSpy } = await setupTestClient(setupCredentialsProvider());
176221

177222
try {
178223
await client.connect();
179224
await runClientOperations(client);
180-
validateTokens(reAuthSpy);
225+
validateTokens(reAuthSpy, options.testingDefaultAzureCredential);
181226
} finally {
182227
await client.destroy();
183228
}

‎packages/entraid/lib/azure-identity-provider.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import type { AccessToken } from '@azure/core-auth';
2+
3+
import { IdentityProvider, TokenResponse } from '@redis/client/dist/lib/authx';
4+
5+
export class AzureIdentityProvider implements IdentityProvider<AccessToken> {
6+
private readonly getToken: () => Promise<AccessToken>;
7+
8+
constructor(getToken: () => Promise<AccessToken>) {
9+
this.getToken = getToken;
10+
}
11+
12+
async requestToken(): Promise<TokenResponse<AccessToken>> {
13+
const result = await this.getToken();
14+
return {
15+
token: result,
16+
ttlMs: result.expiresOnTimestamp - Date.now()
17+
};
18+
}
19+
20+
}
21+
22+

‎packages/entraid/lib/entra-id-credentials-provider-factory.ts‎

Lines changed: 67 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
import type { GetTokenOptions, TokenCredential } from '@azure/core-auth';
12
import { NetworkError } from '@azure/msal-common';
23
import {
34
LogLevel,
@@ -7,8 +8,9 @@ import {
78
PublicClientApplication,
89
ConfidentialClientApplication, AuthorizationUrlRequest, AuthorizationCodeRequest, CryptoProvider, Configuration, NodeAuthOptions, AccountInfo
910
} from '@azure/msal-node';
10-
import { RetryPolicy, TokenManager, TokenManagerConfig, ReAuthenticationError } from '@redis/client/dist/lib/authx';
11-
import { EntraidCredentialsProvider } from './entraid-credentials-provider';
11+
import { RetryPolicy, TokenManager, TokenManagerConfig, ReAuthenticationError, BasicAuth } from '@redis/client/dist/lib/authx';
12+
import { AzureIdentityProvider } from './azure-identity-provider';
13+
import { AuthenticationResponse, DEFAULT_CREDENTIALS_MAPPER, EntraidCredentialsProvider, OID_CREDENTIALS_MAPPER } from './entraid-credentials-provider';
1214
import { MSALIdentityProvider } from './msal-identity-provider';
1315

1416
/**
@@ -51,7 +53,11 @@ export class EntraIdCredentialsProviderFactory {
5153
return new EntraidCredentialsProvider(
5254
new TokenManager(idp, params.tokenManagerConfig),
5355
idp,
54-
{ onReAuthenticationError: params.onReAuthenticationError, credentialsMapper: OID_CREDENTIALS_MAPPER }
56+
{
57+
onReAuthenticationError: params.onReAuthenticationError,
58+
credentialsMapper: params.credentialsMapper ?? OID_CREDENTIALS_MAPPER,
59+
onRetryableError: params.onRetryableError
60+
}
5561
);
5662
}
5763

@@ -102,7 +108,8 @@ export class EntraIdCredentialsProviderFactory {
102108
return new EntraidCredentialsProvider(new TokenManager(idp, params.tokenManagerConfig), idp,
103109
{
104110
onReAuthenticationError: params.onReAuthenticationError,
105-
credentialsMapper: OID_CREDENTIALS_MAPPER
111+
credentialsMapper: params.credentialsMapper ?? OID_CREDENTIALS_MAPPER,
112+
onRetryableError: params.onRetryableError
106113
});
107114
}
108115

@@ -138,6 +145,42 @@ export class EntraIdCredentialsProviderFactory {
138145
);
139146
}
140147

148+
/**
149+
* This method is used to create a credentials provider using DefaultAzureCredential.
150+
*
151+
* The user needs to create a configured instance of DefaultAzureCredential ( or any other class that implements TokenCredential )and pass it to this method.
152+
*
153+
* The default credentials mapper for this method is OID_CREDENTIALS_MAPPER which extracts the object ID from JWT
154+
* encoded token.
155+
*
156+
* Depending on the actual flow that DefaultAzureCredential uses, the user may need to provide different
157+
* credential mapper via the credentialsMapper parameter.
158+
*
159+
*/
160+
static createForDefaultAzureCredential(
161+
{
162+
credential,
163+
scopes,
164+
options,
165+
tokenManagerConfig,
166+
onReAuthenticationError,
167+
credentialsMapper,
168+
onRetryableError
169+
}: DefaultAzureCredentialsParams
170+
): EntraidCredentialsProvider {
171+
172+
const idp = new AzureIdentityProvider(
173+
() => credential.getToken(scopes, options).then(x => x === null ? Promise.reject('Token is null') : x)
174+
);
175+
176+
return new EntraidCredentialsProvider(new TokenManager(idp, tokenManagerConfig), idp,
177+
{
178+
onReAuthenticationError: onReAuthenticationError,
179+
credentialsMapper: credentialsMapper ?? OID_CREDENTIALS_MAPPER,
180+
onRetryableError: onRetryableError
181+
});
182+
}
183+
141184
/**
142185
* This method is used to create a credentials provider for the Authorization Code Flow with PKCE.
143186
* @param params
@@ -194,7 +237,11 @@ export class EntraIdCredentialsProviderFactory {
194237
}
195238
);
196239
const tm = new TokenManager(idp, params.tokenManagerConfig);
197-
return new EntraidCredentialsProvider(tm, idp, { onReAuthenticationError: params.onReAuthenticationError });
240+
return new EntraidCredentialsProvider(tm, idp, {
241+
onReAuthenticationError: params.onReAuthenticationError,
242+
credentialsMapper: params.credentialsMapper ?? DEFAULT_CREDENTIALS_MAPPER,
243+
onRetryableError: params.onRetryableError
244+
});
198245
}
199246
};
200247
}
@@ -214,8 +261,8 @@ export class EntraIdCredentialsProviderFactory {
214261

215262
}
216263

217-
const REDIS_SCOPE_DEFAULT = 'https://redis.azure.com/.default';
218-
const REDIS_SCOPE = 'https://redis.azure.com'
264+
export const REDIS_SCOPE_DEFAULT = 'https://redis.azure.com/.default';
265+
export const REDIS_SCOPE = 'https://redis.azure.com'
219266

220267
export type AuthorityConfig =
221268
| { type: 'multi-tenant'; tenantId: string }
@@ -234,7 +281,19 @@ export type CredentialParams = {
234281
authorityConfig?: AuthorityConfig;
235282

236283
tokenManagerConfig: TokenManagerConfig
237-
onReAuthenticationError?: (error: ReAuthenticationError) => void;
284+
onReAuthenticationError?: (error: ReAuthenticationError) => void
285+
credentialsMapper?: (token: AuthenticationResponse) => BasicAuth
286+
onRetryableError?: (error: string) => void
287+
}
288+
289+
export type DefaultAzureCredentialsParams = {
290+
scopes: string | string[],
291+
options?: GetTokenOptions,
292+
credential: TokenCredential
293+
tokenManagerConfig: TokenManagerConfig
294+
onReAuthenticationError?: (error: ReAuthenticationError) => void
295+
credentialsMapper?: (token: AuthenticationResponse) => BasicAuth
296+
onRetryableError?: (error: string) => void
238297
}
239298

240299
export type AuthCodePKCEParams = CredentialParams & {
@@ -356,16 +415,3 @@ export class AuthCodeFlowHelper {
356415
}
357416
}
358417

359-
const OID_CREDENTIALS_MAPPER = (token: AuthenticationResult) => {
360-
361-
// Client credentials flow is app-only authentication (no user context),
362-
// so only access token is provided without user-specific claims (uniqueId, idToken, ...)
363-
// this means that we need to extract the oid from the access token manually
364-
const accessToken = JSON.parse(Buffer.from(token.accessToken.split('.')[1], 'base64').toString());
365-
366-
return ({
367-
username: accessToken.oid,
368-
password: token.accessToken
369-
})
370-
371-
}

0 commit comments

Comments
 (0)