Compartilhar via


CREATE CREDENTIAL (Transact-SQL)

Aplica-se a: SQL Server Instâ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 quando CREATE CREDENTIAL precisar usar a mesma credencial para vários bancos de dados no servidor.

  • Crie uma credencial no escopo do 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 no escopo do banco de dados com os recursos de virtualização de dados do PolyBase e da Instância Gerenciada de 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 ]

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 usado para backup/restauração usando plataformas de dados externas, como Armazenamento de Blobs do Azure ou plataformas compatíveis com 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 Azure Key Vault, o argumento SECRET deve ser formatado como a ID> do cliente de uma entidade de serviço (sem hífens) e <secret>, passados <juntos 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 (11111111-2222-3333-4444-555555555555) é despojada dos hífens e inserida como a cadeia de caracteres 11111111222233334444555555555555 e o Segredo é representado pela cadeia de caracteres SECRET_DBEngine.

USE master;
CREATE CREDENTIAL Azure_EKM_TDE_cred
    WITH IDENTITY = 'ContosoKeyVault',
    SECRET = '11111111222233334444555555555555SECRET_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 = '11111111-AAAA-BBBB-2222-CCCCCCCCCCCC';
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 o Managed Identity

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 S3

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

O padrão aberto compatível com 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 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 em cada BACKUP/RESTORE comando. Use a string 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