CREATE CREDENTIAL (Transact-SQL)

Aplica-se a:SQL ServerInstância Gerenciada de SQL do Azure

Cria uma credencial no nível do servidor. Uma credencial é um registro que contém as informações de autenticação necessárias para se conectar a um recurso fora do SQL Server. A maioria das credenciais inclui um usuário e uma senha do Windows. Por exemplo, salvar um backup de banco de dados em um local pode exigir que o SQL Server forneça credenciais especiais para acessar esse local. Para obter mais informações, consulte Credenciais (Mecanismo de Banco de Dados).

Observação

Para criar a credencial no nível do banco de dados, use CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL). Crie uma credencial no nível do servidor com CREATE CREDENTIAL quando você precisar usar a mesma credencial para vários bancos de dados no servidor.

  • Crie uma credencial com escopo de banco de dados para CREATE DATABASE SCOPED CREDENTIAL tornar o banco de dados mais portátil. Quando um banco de dados for movido para um novo servidor, a credencial no escopo do banco de dados será movida com ele.
  • Use as credenciais no escopo do Banco de Dados SQL.
  • Use credenciais com escopo de banco de dados com recursos de virtualização de dados do PolyBase e da Instância Gerenciada SQL do Azure.

Convenções de sintaxe de Transact-SQL

Sintaxe

CREATE CREDENTIAL credential_name
WITH IDENTITY = 'identity_name'
    [ , SECRET = 'secret' ]
        [ FOR CRYPTOGRAPHIC PROVIDER cryptographic_provider_name ]

Observação

Para exibir a sintaxe do Transact-SQL para o SQL Server 2014 (12.x) e versões anteriores, confira a Documentação das versões anteriores.

Argumentos

credential_name

Especifica o nome da credencial que está sendo criada. credential_name não pode começar com a tecla jogo da velha (#). As credenciais de sistema começam com ##.

Importante

Ao usar uma SAS (assinatura de acesso compartilhado), esse nome deve corresponder ao caminho do contêiner, começar com https e não deve conter uma barra "/". Confira o exemplo D.

Quando usada para backup/restauração usando plataformas de dados externas, como o Armazenamento de Blobs do Azure ou plataformas compatíveis com o S3, a tabela a seguir fornece caminhos comuns:

Fonte de dados externa Caminho de local Exemplo
Armazenamento de Blobs do Azure (V2) https://<mystorageaccountname>.blob.core.windows.net/<mystorageaccountcontainername> Exemplo D.
Armazenamento de objetos compatível com o S3 - Armazenamento compatível com S3: s3://<server_name>:<port>/
- AWS S3: s3://<bucket_name>.S3.<region>.amazonaws.com[:port]/<folder>
ou s3://s3.<region>.amazonaws.com[:port]/<bucket_name>/<folder>
Exemplo F.

IDENTITY ='identity_name'

Especifica o nome da conta a ser usada ao conectar o servidor externamente. Quando a credencial é usada para acessar o Azure Key Vault, o IDENTITY é o nome do cofre de chaves. Veja o exemplo C a seguir. Quando a credencial usa uma SAS (assinatura de acesso compartilhado), a IDENTITY é SHARED ACCESS SIGNATURE. Veja o exemplo D abaixo.

Importante

O Banco de dados SQL do Azure é compatível apenas as identidades do Azure Key Vault e com Assinatura de Acesso Compartilhado. Não há suporte para identidades de usuário do Windows.

SECRET ='secret'

Especifica o segredo necessário para a autenticação de saída.

Quando a credencial é usada para acessar o Cofre de Chaves do Azure, o argumento SECRET deve ser formatado como ID> do cliente de uma entidade de< serviço (sem hífens) e< secreto>, passado junto sem um espaço entre eles. Veja o exemplo C a seguir. Quando a credencial usa uma assinatura de acesso compartilhado, o SECRET é o token de assinatura de acesso compartilhado. Veja o exemplo D abaixo. Confira informações sobre como criar uma política de acesso armazenado e uma assinatura de acesso compartilhado em um contêiner do Azure na Lição 1: Criar uma política de acesso armazenado e uma Assinatura de Acesso Compartilhado em um contêiner do Azure.

FOR CRYPTOGRAPHIC PROVIDER cryptographic_provider_name

Especifica o nome de um Provedor de EKM (Gerenciamento Extensível de Chaves). Para obter mais informações sobre o Gerenciamento de Chaves, confira EKM (Gerenciamento Extensível de Chaves).

Comentários

Quando IDENTITY for um usuário do Windows, o segredo poderá ser a senha. O segredo é criptografado com a chave mestre de serviço. Se a chave mestre de serviço for gerada novamente, o segredo será criptografado novamente com a nova chave mestre de serviço.

Depois de criar uma credencial, mapeie-a para um logon do SQL Server usando CREATE LOGIN ouALTER LOGIN. Um logon do SQL Server pode ser mapeado somente para uma credencial, mas uma única credencial pode ser mapeada para vários logons do SQL Server. Para obter mais informações, consulte Credenciais (Mecanismo de Banco de Dados). Uma credencial no nível do servidor pode ser mapeada apenas para um logon, não para um usuário de banco de dados.

As informações sobre as credenciais são visíveis na exibição do catálogo sys.credentials.

Se não houver nenhuma credencial mapeada de logon para o provedor, a credencial mapeada para a conta de serviço do SQL Server será usada.

Um logon pode ter várias credenciais mapeadas, contanto que elas sejam usadas com provedores diferentes. Deve haver só uma credencial mapeada por provedor por logon. A mesma credencial pode ser mapeada para outros logons.

Permissões

Exige a permissão ALTER ANY CREDENTIAL.

Exemplos

a. Como criar uma credencial para a identidade do Windows

O exemplo a seguir cria a credencial chamada AlterEgo. A credencial contém o usuário do Windows Mary5 e uma senha.

CREATE CREDENTIAL AlterEgo WITH IDENTITY = 'Mary5',
    SECRET = '<EnterStrongPasswordHere>';
GO

B. Criando uma credencial para o EKM

O exemplo a seguir usa uma conta já criada chamada User1OnEKM em um módulo de EKM por meio das ferramentas de gerenciamento de EKM, com um tipo de conta e uma senha básicos. A conta sysadmin no servidor cria uma credencial usada para se conectar à conta da EKM e atribui essa credencial à conta User1SQL Server:

CREATE CREDENTIAL CredentialForEKM
    WITH IDENTITY='User1OnEKM', SECRET='<EnterStrongPasswordHere>'
    FOR CRYPTOGRAPHIC PROVIDER MyEKMProvider;
GO

/* Modify the login to assign the cryptographic provider credential */
ALTER LOGIN User1
ADD CREDENTIAL CredentialForEKM;

C. Criando uma credencial de EKM usando a Chave do Cofre do Azure

O exemplo a seguir cria uma credencial SQL Server para o Mecanismo de Banco de Dados usar ao acessar o Azure Key Vault com o Conector do SQL Server para Microsoft Azure Key Vault. Para obter um exemplo completo de como usar o Conector SQL Server, confira Gerenciamento Extensível de Chaves Usando o Key Vault do Azure (SQL Server).

Importante

O argumento IDENTITY de CREATE CREDENTIAL requer o nome da chave de cofre. O argumento SECRET de CREATE CREDENTIAL exige que a <Client ID>> (sem hifens) e o <Secret> sejam passados juntos sem um espaço entre eles.

No exemplo a seguir, a ID do cliente (EF5C8E09-4D2A-4A76-9998-D93440D8115D) não tem hifens e foi inserida como a cadeia de caracteres EF5C8E094D2A4A769998D93440D8115D , e Secret é representado pela cadeia de caracteres SECRET_DBEngine.

USE master;
CREATE CREDENTIAL Azure_EKM_TDE_cred
    WITH IDENTITY = 'ContosoKeyVault',
    SECRET = 'EF5C8E094D2A4A769998D93440D8115DSECRET_DBEngine'
    FOR CRYPTOGRAPHIC PROVIDER AzureKeyVault_EKM_Prov ;

O exemplo a seguir cria a mesma credencial usando variáveis para as cadeias de caracteres Client ID e Secret, que, em seguida, são concatenadas para formar o argumento SECRET. A função REPLACE é usada para remover os hifens da ID do Cliente.

DECLARE @AuthClientId uniqueidentifier = 'EF5C8E09-4D2A-4A76-9998-D93440D8115D';
DECLARE @AuthClientSecret varchar(200) = 'SECRET_DBEngine';
DECLARE @pwd varchar(max) = REPLACE(CONVERT(varchar(36), @AuthClientId) , '-', '') + @AuthClientSecret;

EXEC ('CREATE CREDENTIAL Azure_EKM_TDE_cred
    WITH IDENTITY = ''ContosoKeyVault'', SECRET = ''' + @PWD + '''
    FOR CRYPTOGRAPHIC PROVIDER AzureKeyVault_EKM_Prov ;');

D. Criando uma credencial usando um token SAS

Aplica-se a: SQL Server 2014 (12.x) até aversão atual e à Instância Gerenciada do Azure SQL.

O exemplo a seguir cria uma credencial de assinatura de acesso compartilhado usando um token SAS. Para obter um tutorial sobre como criar uma política de acesso armazenado e uma assinatura de acesso compartilhado em um contêiner do Azure e, em seguida, criar uma credencial usando a assinatura de acesso compartilhado, confira Tutorial: Usar o Armazenamento de Blobs do Microsoft Azure com bancos de dados SQL Server.

Importante

O argumento CREDENTIAL NAME exige que o nome corresponda ao caminho do contêiner, comece com https e não contenha uma barra "/" à direita. O argumento IDENTITY exige o nome, SHARED ACCESS SIGNATURE. O argumento SECRET exige o token de assinatura de acesso compartilhado.

O segredo de SHARED ACCESS SIGNATURE não deve ter ? à esquerda.

USE master
CREATE CREDENTIAL [https://<mystorageaccountname>.blob.core.windows.net/<mystorageaccountcontainername>] -- this name must match the container path, start with https and must not contain a trailing forward slash.
    WITH IDENTITY='SHARED ACCESS SIGNATURE' -- this is a mandatory string and do not change it.
    , SECRET = 'sharedaccesssignature' -- this is the shared access signature token
GO

E. Criando uma credencial para identidade gerenciada

O exemplo a seguir cria a credencial que representa a identidade gerenciada do SQL do Azure ou do serviço Azure Synapse. A senha e o segredo não são aplicáveis nesse caso.

CREATE CREDENTIAL ServiceIdentity WITH IDENTITY = 'Managed Identity';
GO

F. Criar uma credencial para backup/restauração para armazenamento compatível com o S3

Aplica-se a: SQL Server 2022 (16.x) e versões posteriores

O padrão aberto compatível com o S3 fornece caminhos de armazenamento e detalhes que podem diferir com base na plataforma de armazenamento. Para obter mais informações, confira Backup em URL do SQL Server para armazenamento de objetos compatível com o S3.

Para a maioria dos armazenamentos compatíveis com o S3, este exemplo cria uma credencial no nível do servidor e executa um BACKUP TO URLarquivo .

USE [master];
CREATE CREDENTIAL [s3://<endpoint>:<port>/<bucket>]
WITH
        IDENTITY    = 'S3 Access Key',
        SECRET      = '<AccessKeyID>:<SecretKeyID>';
GO

BACKUP DATABASE [SQLTestDB]
TO      URL = 's3://<endpoint>:<port>/<bucket>/SQLTestDB.bak'
WITH    FORMAT /* overwrite any existing backup sets */
,       STATS = 10
,       COMPRESSION;

No entanto, o AWS S3 oferece suporte a dois padrões diferentes de URL.

  • S3://<BUCKET_NAME>.S3.<REGION>.AMAZONAWS.COM/<FOLDER> (padrão)
  • S3://S3.<REGION>.AMAZONAWS.COM/<BUCKET_NAME>/<FOLDER>

Há várias abordagens para criar com êxito uma credencial para o AWS S3:

  • Forneça o nome do bucket, o caminho e a região no nome da credencial.

    -- S3 bucket name: datavirtualizationsample
    -- S3 bucket region: us-west-2
    -- S3 bucket folder: backup
    
    CREATE CREDENTIAL [s3://datavirtualizationsample.s3.us-west-2.amazonaws.com/backup]
    WITH    
            IDENTITY    = 'S3 Access Key'
    ,       SECRET      = 'accesskey:secretkey';
    GO
    
    BACKUP DATABASE [AdventureWorks2022]
    TO URL  = 's3://datavirtualizationsample.s3.us-west-2.amazonaws.com/backup/AdventureWorks2022.bak'
    WITH COMPRESSION, FORMAT, MAXTRANSFERSIZE = 20971520;
    GO
    

    Ou,

    CREATE CREDENTIAL [s3://s3.us-west-2.amazonaws.com/datavirtualizationsample/backup]
    WITH    
            IDENTITY    = 'S3 Access Key'
    ,       SECRET      = 'accesskey:secretkey';
    GO
    
    BACKUP DATABASE [AdventureWorks2022]
    TO URL  = 's3://s3.us-west-2.amazonaws.com/datavirtualizationsample/backup/AdventureWorks2022.bak'
    WITH COMPRESSION, FORMAT, MAXTRANSFERSIZE = 20971520;
    GO
    
  • Ou, forneça o nome e o caminho do bucket no nome da credencial, mas parametrize a região dentro de cada BACKUP/RESTORE comando. Use a cadeia de caracteres de região específica do BACKUP_OPTIONS S3 no e RESTORE_OPTIONS, por exemplo, '{"s3": {"region":"us-west-2"}}'.

    -- S3 bucket name: datavirtualizationsample
    -- S3 bucket region: us-west-2
    -- S3 bucket folder: backup
    
    CREATE CREDENTIAL   [s3://datavirtualizationsample.s3.amazonaws.com/backup]
    WITH    
            IDENTITY    = 'S3 Access Key'
    ,       SECRET      = 'accesskey:secretkey';
    GO
    
    BACKUP DATABASE [AdventureWorks2022]
    TO URL  = 's3://datavirtualizationsample.s3.amazonaws.com/backup/AdventureWorks2022.bak'
    WITH
      BACKUP_OPTIONS = '{"s3": {"region":"us-west-2"}}' -- REGION AS PARAMETER)
    , COMPRESSION, FORMAT, MAXTRANSFERSIZE = 20971520;
    GO
    
    RESTORE DATABASE AdventureWorks2022_1 
    FROM URL = 's3://datavirtualizationsample.s3.amazonaws.com/backup/AdventureWorks2022.bak'
    WITH 
      MOVE 'AdventureWorks2022' 
      TO 'C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\DATA\AdventureWorks2022_1.mdf'
    , MOVE 'AdventureWorks2022_log' 
      TO 'C:\Program Files\Microsoft SQL Server\MSSQL16.MSSQLSERVER\MSSQL\DATA\AdventureWorks2022_1.ldf'
    , STATS = 10, RECOVERY
    , REPLACE, RESTORE_OPTIONS = '{"s3": {"region":"us-west-2"}}'; -- REGION AS PARAMETER)
    GO