• Article

Service Principal Names (SPNs) in Client Connections (ODBC)

This topic describes ODBC attributes and functions that support service principal names (SPNs) in client applications. For more information about SPNs in client applications, see Service Principal Name (SPN) Support in Client Connections.

Connection String Keywords

The following connection string keywords enable client applications to specify an SPN.

Keyword

Value

ServerSPN

The SPN for the server. The default value is an empty string, which causes SQL Server Native Client to use the default, driver-generated SPN.

FailoverPartnerSPN

The SPN for the failover partner. The default value is an empty string, which causes SQL Server Native Client to use the default, driver-generated SPN.

Connection Attributes

The following connection attributes enable client applications to specify an SPN and query for the authentication method.

Name

Type

Usage

SQL_COPT_SS_SERVER_SPN

SQL_COPT_SS_FAILOVER_PARTNER_SPN

SQLTCHAR, read/write

Specifies the SPN for the server. The default value is an empty string, which causes SQL Server Native Client to use the default, driver-generated SPN.

This attribute can be queried only after it has been set programmatically, or after a connection has been opened. If an attempt is made to query this attribute on a connection that is not open and the attribute has not been set programmatically, SQL_ERROR is returned, and a diagnostic record is logged with SQLState 08003 and the message "Connection not open".

If an attempt is made to set this attribute when a connection is open, SQL_ERROR is returned, and a diagnostic record is logged with SQLState HY011 and the message "Operation invalid at this time".

SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD

SQLTCHAR, read-only

Returns the authentication method used for the connection. The value returned to the application is the value that Windows returns to SQL Server Native Client. Possible values are:

  • "NTLM", which is returned when a connection is opened using NTLM authentication.

  • "Kerberos", which is returned when a connection is opened using Kerberos authentication.

This attribute can only be read for an open connection that used Windows Authentication. If an attempt is made to read it before a connection has been opened, SQL_ERROR is returned, and an error is logged with SQLState 08003 and the message "Connection not open".

If this attribute is queried on a connection that did not use Windows Authentication, SQL_ERROR is returned, and an error is logged with SQLState HY092 and the message "Invalid attribute/option identifier (SQL_COPT_SS_INTEGRATED_AUTHENTICATION_METHOD is only available for Trusted Connections)".

If the authentication method cannot be determined, SQL_ERROR is returned, and an error is logged with SQLState HY000 and the message "General error".

SQL_COPT_SS_MUTUALLY_AUTHENTICATED

SQLSMALLINT, read-only

Returns SQL_TRUE if the server in the connection was mutually authenticated; otherwise, returns SQL_FALSE.

This attribute can only be read for an open connection. If an attempt is made to read it before a connection has been opened, SQL_ERROR is returned, and an error is logged with SQLState 08003 and the message "Connection not open".

If this attribute is queried for a connection that did not use Windows Authentication, SQL_FALSE is returned.

ODBC Function Support for Specifying SPNs

The following ODBC functions support client applications and SPNs: