Nomes de entidade de serviço (SPNs) em conexões de cliente (OLE DB)
Importante
O SQL Server Native Client (geralmente abreviado SNAC) foi removido do SQL Server 2022 (16.x) e do SQL Server Management Studio 19 (SSMS). O provedor OLE DB do SQL Server Native Client (SQLNCLI ou SQLNCLI11) e o provedor Microsoft OLE DB herdado para SQL Server (SQLOLEDB) não são recomendados para novos desenvolvimentos. Alterne para o novo Microsoft OLE DB Driver (MSOLEDBSQL) para SQL Server no futuro.
Este tópico descreve as propriedades do OLE DB e as funções de membro que oferecem suporte a SPNs (nomes principais de serviço) 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 SQL Server Native Client 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 SQL Server Native Client 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 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 SQL Server Native Client 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 SQL Server Native Client use o SPN padrão gerado pelo provedor. |
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 SQL Server Native Client. 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." |