Nomes de entidade de serviço (SPNs) em conexões de cliente (OLE DB) no SQL Server Native Client

Artigo
01/15/2025

Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada SQL do Azure do Azure Synapse AnalyticsAnalytics Platform System (PDW)

Baixar driver OLE DB

Este artigo descreve propriedades OLE DB e funções de membro que oferecem suporte a nomes de entidade de serviço (SPNs) em aplicativos cliente. Para obter mais informações sobre SPNs em aplicativos cliente, consulte Service Principal Name (SPN) Support in Client Connections. Para obter um exemplo, consulte autenticação Kerberos integrada (OLE DB).

Palavras-chave da cadeia de caracteres de inicialização do provedor

As seguintes palavras-chave de cadeia de caracteres de inicialização do provedor suportam SPNs em aplicativos OLE DB. Na tabela a seguir, os valores na coluna de palavra-chave são usados para a cadeia de caracteres do provedor de IDBInitialize::Initialize. Os valores na coluna de descrição são usados em cadeias de caracteres de inicialização ao se conectar usando ADO ou IDataInitialize::GetDataSource.

Palavra-chave	Descrição	Valor
ServidorSPN	SPN do servidor	O SPN para o servidor. O valor padrão é uma cadeia de caracteres vazia, que faz com que o driver OLE DB para SQL Server use o SPN padrão gerado pelo provedor.
FailoverPartnerSPN	SPN de parceiro de failover	O SPN para o parceiro de failover. O valor padrão é uma cadeia de caracteres vazia, que faz com que o driver OLE DB para SQL Server use o SPN padrão gerado pelo provedor.

Propriedades de inicialização da fonte de dados

As propriedades a seguir no conjunto de propriedades DBPROPSET_SQLSERVERDBINIT permitem que os aplicativos especifiquem ou leiam SPNs.

Designação	Tipo	Utilização
SSPROP_INIT_SERVERSPN	VT_BSTR, leitura/escrita	Especifica o SPN para o servidor. O valor padrão é uma cadeia de caracteres vazia, que faz com que o driver OLE DB para SQL Server use o SPN padrão gerado pelo provedor.
SSPROP_INIT_FAILOVERPARTNERSPN	VT_BSTR, leitura/escrita	Especifica o SPN para o parceiro de failover. O valor padrão é uma cadeia de caracteres vazia, que faz com que o driver OLE DB para SQL Server use o SPN padrão gerado pelo provedor.
SSPROP_INIT_DISCOVEREDSERVERSPN	VT_BSTR, somente leitura	Usado para consultar o SPN do servidor de uma conexão. (Versão 18.6.3 ou posterior)

Propriedades da fonte de dados

As propriedades a seguir no conjunto de propriedades DBPROPSET_SQLSERVERDATASOURCEINFO permitem que os aplicativos descubram o método de autenticação.

Designação	Tipo	Utilização
SSPROP_INTEGRATEDAUTHENTICATIONMETHOD	VT_BSTR, somente leitura	Retorna o método de autenticação usado para a conexão. O valor retornado ao aplicativo é o valor que o Windows retorna ao Driver OLE DB para SQL Server. Os valores possíveis são os seguintes: "NTLM", que é retornado quando uma conexão é aberta usando a autenticação NTLM. "Kerberos", que é retornado quando uma conexão é aberta usando a autenticação Kerberos. Se uma conexão tiver sido aberta e o método de autenticação não puder ser determinado, VT_EMPTY será retornado. Essa propriedade só pode ser lida quando uma fonte de dados tiver sido inicializada. Se você tentar ler a propriedade antes de uma fonte de dados ter sido inicializada, IDBProperties::GetProperties retornará DB_S_ERRORSOCCURRED ou DB_E_ERRORSOCCURRED, conforme apropriado, e DBPROPSTATUS_NOTSUPPORTED será definido em DBPROPSET_PROPERTIESINERROR para essa propriedade. Esse comportamento está de acordo com a especificação principal do OLE DB.
SSPROP_MUTUALLYAUTHENTICATED	VT_BOOL, somente leitura	Retorna VARIANT_TRUE se os servidores na conexão foram mutuamente autenticados; caso contrário, retorna VARIANT_FALSE. Essa propriedade só pode ser lida quando uma fonte de dados tiver sido inicializada. Se houver uma tentativa de ler a propriedade antes de uma fonte de dados ter sido inicializada, IDBProperties::GetProperties retornará DB_S_ERRORSOCCURRED ou DB_E_ERRORSOCCURRED, conforme apropriado, e DBPROPSTATUS_NOTSUPPORTED será definido em DBPROPSET_PROPERTIESINERROR para essa propriedade. Esse comportamento está de acordo com a especificação principal do OLE DB Se esse atributo for consultado para uma conexão que não usou a Autenticação do Windows, VARIANT_FALSE será retornado.

Suporte de API OLE DB para SPNs

A tabela a seguir descreve as funções de membro do OLE DB que oferecem suporte a SPNs em conexões de cliente:

Função de membro	Descrição
IDataInitialize::GetDataSource	pwszInitializationString pode conter as novas palavras-chave ServerSPN e FailoverPartnerSPN.
IDataInitialize::GetInitializationString	Se SSPROP_INIT_SERVERSPN e SSPROP_INIT_FAILOVERPARTNERSPN tiverem valores não padrão, eles serão incluídos na cadeia de caracteres de inicialização por meio ppwszInitString como valores de palavra-chave para ServerSPN e FailoverPartnerSPN. Caso contrário, essas palavras-chave não serão incluídas na cadeia de caracteres de inicialização.
IDBInitialize::Inicializar	Se a solicitação estiver habilitada definindo DBPROP_INIT_PROMPT nas propriedades de inicialização da fonte de dados, a caixa de diálogo Login do OLE DB será exibida. Isso permite que SPNs sejam inseridos para o servidor principal e seu parceiro de failover. A cadeia de caracteres do provedor em DBPROP_INIT_PROVIDERSTRING, se definida, reconhecerá as novas palavras-chave ServerSPN e FailoverPartnerSPN e usará seus valores, se presentes, para inicializar SSPROP_INIT_SERVER_SPN e SSPROP_INIT_FAILOVER_PARTNER_SPN. IDBProperties::SetProperties pode ser chamado para definir as propriedades SSPROP_INIT_SERVER_SPN e SSPROP_INIT_FAILOVER_PARTNER_SPN antes de IDBInitialize::Initialize ser chamado. Esta é uma alternativa ao uso de uma cadeia de caracteres de provedor. Se uma propriedade for definida em mais de um lugar, um valor definido programaticamente terá precedência sobre um valor definido na cadeia de caracteres do provedor. Um valor definido em uma cadeia de caracteres de inicialização tem precedência sobre um valor definido em uma caixa de diálogo de login. Se a mesma palavra-chave aparecer mais de uma vez na cadeia de caracteres do provedor, o valor da primeira ocorrência terá precedência.
IDBProperties::GetProperties	IDBProperties::GetProperties pode ser chamado para obter os valores das novas propriedades de inicialização da fonte de dados SSPROP_INIT_SERVERSPN e SSPROP_INIT_FAILOVERPARTNERSPN e das novas propriedades da fonte de dados SSPROP_AUTHENTICATIONMETHOD e SSPROP_MUTUALLYAUTHENTICATED.
IDBProperties::GetPropertyInfo	IdbProperties::GetPropertyInfo incluirá as novas propriedades de inicialização da fonte de dados SSPROP_INIT_SERVERSPN e SSPROP_INIT_FAILOVERPARTNERSPN ou as novas propriedades da fonte de dados SSPROP_AUTHENTICATION_METHOD e SSPROP_MUTUALLYAUTHENTICATED.
IDBProperties::SetProperties	IDBProperties::SetProperties pode ser chamado para definir os valores das novas propriedades de inicialização da fonte de dados SSPROP_INITSERVERSPN e SSPROP_INIT_FAILOVERPARTNERSPN. Essas propriedades podem ser definidas a qualquer momento, mas se a fonte de dados já estiver aberta, o seguinte erro será retornado: DB_E_ERRORSOCCURRED, "Operação OLE DB de várias etapas gerou erros. Verifique cada valor de status do OLE DB, se disponível. Nenhuma obra foi feita."

Ver também

Driver OLE DB para programação do SQL Server

Partilhar via