Skip to content

Commit 12a89c8

Browse files
Merge pull request #33984 from David-Engel/patch-1
Add notes about AccessTokens and pooling considerations
2 parents bc6d6bb + 43690a2 commit 12a89c8

File tree

1 file changed

+10
-1
lines changed

1 file changed

+10
-1
lines changed

docs/connect/ado-net/sql/azure-active-directory-authentication.md

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Describes how to use supported Microsoft Entra authentication modes
44
author: David-Engel
55
ms.author: davidengel
66
ms.reviewer: davidengel
7-
ms.date: 09/13/2024
7+
ms.date: 05/01/2025
88
ms.service: sql
99
ms.subservice: connectivity
1010
ms.topic: conceptual
@@ -363,6 +363,12 @@ The following example shows how to set an application client ID through a config
363363

364364
Available in version 5.2 onwards, there's a new [AccessTokenCallback](/dotnet/api/microsoft.data.sqlclient.sqlconnection.accesstokencallback) property on [SqlConnection](/dotnet/api/microsoft.data.sqlclient.sqlconnection). Use the `AccessTokenCallback` property to define a custom function that returns an access token given the incoming parameters. Using the callback is better than using the [AccessToken](/dotnet/api/microsoft.data.sqlclient.sqlconnection.accesstoken) property because it allows the access token to be refreshed within a connection pool. When using the `AccessToken` property, the token can't be updated after opening the connection. There's also no associated expiration date provided through the property. Once the token expires, new connection requests fail with a server authentication error and pools using it must be manually cleared.
365365

366+
> [!IMPORTANT]
367+
> An `AccessTokenCallback` must return access tokens of the same security context for the same input parameters. If the security context is different, a pooled connection with the wrong security context may be returned for a connection request.
368+
369+
> [!NOTE]
370+
> `AccessTokenCallback` is part of the key used to identify connection pools. Avoid creating a new function callback for every creation of a SqlConnection since that results in a new pool every time. Reference the same instance of a function for connections you want to be considered for pooling. The connection pool key includes parameters passed to the callback to partition connection pools appropriately.
371+
366372
The following code snippet is an example of using the `AccessTokenCallback` property in **Microsoft.Data.SqlClient v5.2 onwards**.
367373

368374
[!code-csharp [AADAuthenticationAccessTokenCallback#1](~/../sqlclient/doc/samples/SqlConnection_AccessTokenCallback.cs#1)]
@@ -371,6 +377,9 @@ The following code snippet is an example of using the `AccessTokenCallback` prop
371377

372378
Given more flexibility, the client application can also use its own provider for Microsoft Entra authentication instead of using the `ActiveDirectoryAuthenticationProvider` class. The custom authentication provider needs to be a subclass of `SqlAuthenticationProvider` with overridden methods. It then must register the custom provider, overriding one or more of the existing `Active Directory*` authentication methods.
373379

380+
> [!IMPORTANT]
381+
> An authentication provider must return access tokens of the same security context for the same input parameters. If the security context is different, a pooled connection with the wrong security context may be returned for a connection request.
382+
374383
The following example shows how to use a new authentication provider for `Active Directory Device Code Flow` authentication.
375384

376385
[!code-csharp [CustomDeviceCodeFlowAzureAuthenticationProvider#1](~/../sqlclient/doc/samples/CustomDeviceCodeFlowAzureAuthenticationProvider.cs#1)]

0 commit comments

Comments
 (0)