mssqllibR2DBC for SQL Server

Authentication

Implemented logins are SQL username and password, a static access token inside LOGIN7, and a callback that runs after the server sends FEDAUTHINFO. The driver does not read AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, a certificate path, or any other environment variable.

SQL password

This is the default. LOGIN7 carries the username and password. PRELOGIN does not advertise federated authentication.

URL
r2dbc:mssql://user:password@localhost:1433/database?trustServerCertificate=true
Explicit mode
.option(TdsLibOptions.AUTHENTICATION, Authentication.SQL_PASSWORD)
.option(ConnectionFactoryOptions.USER, "user")
.option(ConnectionFactoryOptions.PASSWORD, "password")

Authentication is org.mssqllib.r2dbc.mssql.Authentication. Names match Microsoft JDBC, ignoring case and - or _.

Names the parser accepts

ValueWhat the driver does
SqlPassword, omitted, blank, NotSpecified SQL user and password. Both are required when no token source is set.
ActiveDirectoryServicePrincipal The JDBC name for a confidential client. The name alone does not acquire a token. With entraClientId and entraClientSecret, or with any callback below, user and password are not required.
AccessToken Requires accessToken, accessTokenCallback, accessTokenCallbackClass, or tokenProvider. User and password are not required.
ActiveDirectoryPassword Parsed. It does not start an Azure AD password grant. With no token source it still sends the SQL user and password in LOGIN7, and both are required.
ActiveDirectoryIntegrated, ActiveDirectoryInteractive Parsed. Kerberos and browser login are not implemented. Do not use these names.

Managed identity is not supported. There is no metadata client and no ActiveDirectoryManagedIdentity name.

Entra client id and secret

When no callback object, callback class, or tokenProvider is set, entraClientId and entraClientSecret must both be set or both be absent. The driver builds ConfidentialClientAccessTokenCallback and posts a client-credentials grant with java.net.http.HttpClient.

The POST runs after FEDAUTHINFO, on a worker thread, not on the socket thread and not before TCP. The authority is the server STS URL. The scope is the server SPN plus /.default, with one slash. For Azure SQL that scope is https://database.windows.net/.default. A missing SPN falls back to https://database.windows.net/. A missing STS URL falls back to https://login.microsoftonline.com/common. Server values win. There is no tenant connection option.

Builder
ConnectionFactoryOptions.builder()
    .option(ConnectionFactoryOptions.DRIVER, "mssql")
    .option(ConnectionFactoryOptions.HOST, "host.database.windows.net")
    .option(ConnectionFactoryOptions.PORT, 1433)
    .option(ConnectionFactoryOptions.DATABASE, "database")
    .option(TdsLibOptions.AUTHENTICATION, "ActiveDirectoryServicePrincipal")
    .option(TdsLibOptions.ENTRA_CLIENT_ID, clientId)
    .option(TdsLibOptions.ENTRA_CLIENT_SECRET, clientSecret)
    .build()

https://database.windows.net/ is the Entra audience, not a host to connect to. The same audience is used for Azure SQL and for SQL Server 2022 or later with Entra authentication. The database user is created with CREATE USER [application-display-name] FROM EXTERNAL PROVIDER. Error 18456 for that principal, without the words "Token is expired", means the TDS exchange was accepted and that identity is not a user in the database.

Callback, class, and token provider

Precedence is accessTokenCallback, then accessTokenCallbackClass, then tokenProvider, then entraClientId with entraClientSecret. A configured callback ignores a static accessToken.

AccessTokenCallback.getAccessToken(spn, stsUrl) returns a SqlAuthenticationToken. The arguments are SPN, then STS URL. TokenProvider.getAccessToken(stsUrl, spn) returns a Publisher of one token string, and the argument order is the other way around. Prefer AccessTokenCallback.

Callback object
.option(TdsLibOptions.ACCESS_TOKEN_CALLBACK, (spn, stsUrl) ->
    new SqlAuthenticationToken(tokenFor(spn, stsUrl), expiresOn))

A URL cannot carry the callback object or a JWT. It can carry accessTokenCallbackClass, the binary name of a public no-arg AccessTokenCallback. The class must be loadable, and the no-arg constructor must succeed.

Class name in a URL
r2dbc:mssql://host:1433/database?authentication=AccessToken&accessTokenCallbackClass=com.example.TokenCallback

tokenProvider is not a connection-string keyword. Set TdsLibOptions.TOKEN_PROVIDER from code. In Spring that is a ConnectionFactoryOptionsBuilderCustomizer, not spring.r2dbc.url.

Each ConnectionFactory.create() repeats the exchange. An open session is not refreshed and is not closed because the token aged. Query errors do not call the callback. A pool checkout does not call it. The driver does not set the TDS reset-connection bit, so it does not trigger SQL Server's credential recheck on pooled reactivation. A pooled connection can outlive the access token until the pool discards it.

Static access token

With no callback configured, accessToken is embedded in LOGIN7 and reused for every create() from that factory. Do not put the JWT in an R2DBC URL. The option is sensitive. A known exp inside five minutes is rejected before a socket is opened. The driver decodes that claim and does not check the signature.

Static token from application code
.option(TdsLibOptions.AUTHENTICATION, Authentication.ACCESS_TOKEN)
.option(TdsLibOptions.ACCESS_TOKEN, jwt)

Error 18456 whose message contains "Token is expired" is not a retry of that same JWT. A callback may open one new login after that rejection. Other 18456 values are not retried.

Certificate assertion

The driver does not read a certificate file. A caller that already has a signed client assertion implements ClientAssertionProvider in org.mssqllib.r2dbc.mssql.security. ConfidentialClientAccessTokenCallback(clientId, assertion) posts that assertion instead of the secret. Those types are public on the classpath and are not exported from the JPMS module. A modular application can implement AccessTokenCallback itself and set accessTokenCallback.

When both a secret and an assertion callback are configured, the assertion is what gets posted. An explicit callback wins over entraClientSecret.

Token lifetime and pools

Access tokens are commonly valid for about 60 to 90 minutes. SQL Server checks the token at login, not per statement. After exp, the next login fails and a session that is already open keeps working. Give the pool an accessTokenCallback, or the client-id options, so each new physical connection can fetch a current token. A static JWT cannot do that.

FedAuth uses the same login retry as SQL password. A new attempt is a new socket, so the callback runs again. Details are under login retry.

Azure SQL routing

An Azure SQL gateway login can end with a routing redirect and no FEDAUTHINFO on that socket. The driver closes the gateway connection and opens one new TCP connection to the worker host and port. LOGIN7 on the gateway uses the first DNS label of the URL host as ServerName. On the worker, ServerName is the connect host. A blank server name is rejected by Azure SQL.

One create() may reuse a still-valid callback token on the redirect hop and send it inside LOGIN7, without calling the callback again. If the gateway redirected before FEDAUTHINFO, the callback runs once on the worker. A second redirect fails. A routing token that includes a database name uses that database on the next LOGIN7. After a routed login failure, the next retry returns to the original gateway host and the original database.

Do not log the access token, the client secret, or the certificate. The driver logs token acquisition without the token. A line that includes exp is an expiry instant, not the JWT.