Skip to content

Commit a1f7b8a

Browse files
authored
Enhance documentation on ACCESSTOKEN usage
Clarify the requirements and constraints for using the ACCESSTOKEN structure in SQL Server authentication, including allocation and renewal details.
1 parent 3f15440 commit a1f7b8a

1 file changed

Lines changed: 5 additions & 1 deletion

File tree

docs/connect/odbc/using-azure-active-directory.md

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,11 @@ typedef struct AccessToken
189189
} ACCESSTOKEN;
190190
```
191191

192-
The `ACCESSTOKEN` is a variable-length structure consisting of a 4-byte _length_ followed by _length_ bytes of opaque data that form the access token. Because of how SQL Server handles access tokens, one obtained via an [OAuth 2.0](/azure/active-directory/develop/active-directory-authentication-scenarios) JSON response must be expanded so that each byte is followed by a zero padding byte, similar to a UCS-2 string containing only ASCII characters. However, the token is an opaque value and the length specified, in bytes, must NOT include any null terminator. Because of their considerable length and format constraints, this method of authentication is only available programmatically via the `SQL_COPT_SS_ACCESS_TOKEN` connection attribute. There's no corresponding DSN or connection string keyword. The connection string must not contain `UID`, `PWD`, `Authentication`, or `Trusted_Connection` keywords.
192+
The `ACCESSTOKEN` is a variable-length structure consisting of a 4-byte _length_ followed by _length_ bytes of opaque data that form the access token. Because of how SQL Server handles access tokens, one obtained via an [OAuth 2.0](/azure/active-directory/develop/active-directory-authentication-scenarios) JSON response must be expanded so that each byte is followed by a zero padding byte, similar to a UCS-2 string containing only ASCII characters. However, the token is an opaque value and the length specified, in bytes, must NOT include any null terminator. Because of their considerable length and format constraints, this method of authentication is only available programmatically via the `SQL_COPT_SS_ACCESS_TOKEN` connection attribute.
193+
194+
The `ACCESSTOKEN` must remain allocated for as long as the connection handle is allocated. Otherwise access violations may occur. The pointer is part of the connection pool key, so a new pointer will result in a new pool and new connections. You can renew the access token (if it expires, for example) by updating the data buffer directly with a new token, which allows you to continue using existing connections.
195+
196+
There's no corresponding DSN or connection string keyword. The connection string must not contain `UID`, `PWD`, `Authentication`, or `Trusted_Connection` keywords.
193197

194198
> [!NOTE]
195199
> The ODBC Driver version 13.1 only supports this authentication on _Windows_. Subsequent versions support this authentication on all platforms.

0 commit comments

Comments
 (0)