CREATE DATABASE SCOPED CREDENTIAL

(Transact-SQL)
Article • 01/19/2024

Applies to: SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse
Analytics Analytics Platform System (PDW)

Creates a database credential. A database credential is not mapped to a server login or database user. The
credential is used by the database to access to the external location anytime the database is performing an
operation that requires access.

Transact-SQL syntax conventions

Syntax
syntaxsql

CREATE DATABASE SCOPED CREDENTIAL credential_name

WITH IDENTITY = 'identity_name'
[ , SECRET = 'secret' ]

７ Note

To view Transact-SQL syntax for SQL Server 2014 (12.x) and earlier versions, see Previous versions
documentation.

Arguments

credential_name
Specifies the name of the database scoped credential being created. credential_name cannot start with the number
(#) sign. System credentials start with ##.

IDENTITY ='identity_name'
Specifies the name of the account to be used when connecting outside the server.

To import a file from Azure Blob Storage or Azure Data Lake Storage using a shared key, the identity name
must be SHARED ACCESS SIGNATURE . For more information about shared access signatures, see Using Shared
Access Signatures (SAS). Only use IDENTITY = SHARED ACCESS SIGNATURE for a shared access signature.
 To import a file from Azure Blob Storage using a managed identity, the identity name must be MANAGED
IDENTITY .

When using Kerberos (Windows Active Directory or MIT KDC) do not use the domain name in the IDENTITY
argument. It should just be the account name.
In a SQL Server instance, if creating a database scoped credential with a Storage Access Key used as the
SECRET, IDENTITY is ignored.
WITH IDENTITY is not required if the container in Azure Blob storage is enabled for anonymous access. For an
example querying Azure Blob storage, see Importing into a table from a file stored on Azure Blob storage.

） Important

The only PolyBase external data source that supports Kerberos authentication is Hadoop. All other external
data sources (SQL Server, Oracle, Teradata, MongoDB, generic ODBC) only support Basic Authentication.

To load data into Azure Synapse Analytics, any valid value can be used for IDENTITY.
In an Azure Synapse Analytics serverless SQL pool, database scoped credentials can specify a workspace
managed identity, service principal name, or shared access signature (SAS) token. Access via a user identity,
enabled by Microsoft Entra pass-through authentication, is also possible with a database scoped credential,
as is anonymous access to publicly available storage. For more information, see Supported storage
authorization types.
In an Azure Synapse Analytics dedicated SQL pool, database scoped credentials can specify shared access
signature (SAS) token, custom application identity, workspace managed identity, or storage access key.

SECRET ='secret'
Specifies the secret required for outgoing authentication. SECRET is required to import a file from Azure Blob
storage. To load from Azure Blob storage into Azure Synapse Analytics or Parallel Data Warehouse, the Secret must
be the Azure Storage Key.

２ Warning

The SAS key value might begin with a '?' (question mark). When you use the SAS key, you must remove the
leading '?'. Otherwise your efforts might be blocked.

Remarks
A database scoped credential is a record that contains the authentication information that is required to connect
to a resource outside SQL Server. Most credentials include a Windows user and password.

To protect the sensitive information inside the database scoped credential, a database master key (DMK) is
required. The DMK is a symmetric key that encrypts the secret in the database scoped credential. The database
must have a master key before any database scoped credentials can be created. A DMK should be encrypted with
a strong password. Azure SQL Database will create a database master key with a strong, randomly selected
password as part of creating the database scoped credential, or as part of creating a server audit. Users can't
create the master key on a logical master database. The master key password is unknown to Microsoft and not
discoverable after creation. For this reason, creating a database master key before creating a database scoped
credential is recommended. For more information, see CREATE MASTER KEY (Transact-SQL).

When IDENTITY is a Windows user, the secret can be the password. The secret is encrypted using the service
master key. If the service master key is regenerated, the secret is re-encrypted using the new service master key.

When granting permissions for a shared access signatures (SAS) for use with a PolyBase external table, select both
Container and Object as allowed resource types. If not granted, you may receive error 16535 or 16561 when
attempting to access the external table.

Information about database scoped credentials is visible in the sys.database_scoped_credentials catalog view.

Here are some applications of database scoped credentials:

SQL Server uses a database scoped credential to access non-public Azure Blob Storage or Kerberos-secured
Hadoop clusters with PolyBase. To learn more, see CREATE EXTERNAL DATA SOURCE (Transact-SQL).

Azure Synapse Analytics uses a database scoped credential to access non-public Azure Blob Storage with
PolyBase. To learn more, see CREATE EXTERNAL DATA SOURCE (Transact-SQL). For more information about
Azure Synapse storage authentication, see Use external tables with Synapse SQL.

SQL Database uses database scoped credentials for its global query feature. This is the ability to query across
multiple database shards.

SQL Database uses database scoped credentials to write extended event files to Azure Blob Storage.

SQL Database uses database scoped credentials for elastic pools. For more information, see Tame explosive
growth with elastic databases

BULK INSERT and OPENROWSET use database scoped credentials to access data from Azure Blob Storage.
For more information, see Examples of Bulk Access to Data in Azure Blob Storage.

Use database scoped credentials with PolyBase and Azure SQL Managed Instance data virtualization features.

For BACKUP TO URL and RESTORE FROM URL, use a server-level credential via CREATE CREDENTIAL
(Transact-SQL) instead.

Permissions
Requires CONTROL permission on the database.

SQL Server 2022

Starting in SQL Server 2022 (16.x) a new type of connector was introduced, using REST-API calls replacing
HADOOP. For Azure Blob Storage and Azure Data Lake Gen 2 the only supported authentication method is SHARED
ACCESS SIGNATURE .

Please refer to create external data source for more information.

Examples

A. Creating a database scoped credential for your application

The following example creates the database scoped credential called AppCred . The database scoped credential
contains the Windows user Mary5 and a password.

SQL

-- Create a db master key if one does not already exist, using your own password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD='<EnterStrongPasswordHere>';

-- Create a database scoped credential.

CREATE DATABASE SCOPED CREDENTIAL AppCred WITH IDENTITY = 'Mary5',
SECRET = '<EnterStrongPasswordHere>';

B. Creating a database scoped credential for a shared access

signature
The following example creates a database scoped credential that can be used to create an external data source,
which can do bulk operations, such as BULK INSERT and OPENROWSET. Shared Access Signatures cannot be used
with PolyBase in SQL Server, APS or Azure Synapse Analytics.

SQL

-- Create a db master key if one does not already exist, using your own password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD='<EnterStrongPasswordHere>';

-- Create a database scoped credential.

CREATE DATABASE SCOPED CREDENTIAL MyCredentials
WITH IDENTITY = 'SHARED ACCESS SIGNATURE',
SECRET = 'QLYMgmSXMklt%2FI1U6DcVrQixnlU5Sgbtk1qDRakUBGs%3D';

C. Creating a database scoped credential for PolyBase Connectivity

to Azure Data Lake Store
The following example creates a database scoped credential that can be used to create an external data source,
which can be used by PolyBase in Azure Synapse Analytics.
Azure Data Lake Store uses a Microsoft Entra application for service to service authentication.

Please create a Microsoft Entra application and document your client_id, OAuth_2.0_Token_EndPoint, and Key
before you try to create a database scoped credential.

SQL

-- Create a db master key if one does not already exist, using your own password.
CREATE MASTER KEY ENCRYPTION BY PASSWORD='<EnterStrongPasswordHere>';

-- Create a database scoped credential.

CREATE DATABASE SCOPED CREDENTIAL ADL_User
WITH
IDENTITY = '<client_id>@<OAuth_2.0_Token_EndPoint>',
SECRET = '<key>'
;

Related content
Credentials (Database Engine)
ALTER DATABASE SCOPED CREDENTIAL (Transact-SQL)
DROP DATABASE SCOPED CREDENTIAL (Transact-SQL)
sys.database_scoped_credentials
CREATE CREDENTIAL (Transact-SQL)
sys.credentials (Transact-SQL)

Feedback
Was this page helpful?  Yes  No

Provide product feedback | Get help at Microsoft Q&A