create-database-scoped-credential-transact-sql.md

title	CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
description	CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)
author	VanMSFT
ms.author	vanto
ms.reviewer	randolphwest, wiassaf
ms.date	05/14/2025
ms.service	sql
ms.subservice	t-sql
ms.topic	reference
ms.custom	sfi-ropc-blocked ignite-2025
f1_keywords	DATABASE SCOPED CREDENTIAL DATABASE_SCOPED_CREDENTIAL_TSQL SCOPED_TSQL CREATE_DATABASE_SCOPED_CREDENTIAL CREATE_DATABASE_SCOPED_CREDENTIAL_TSQL SCOPED_CREDENTIAL_TSQL SCOPED_CREDENTIAL
helpviewer_keywords	DATABASE SCOPED CREDENTIAL statement credentials [SQL Server], DATABASE SCOPED CREDENTIAL statement
dev_langs	TSQL
monikerRange	=azuresqldb-current || =azure-sqldw-latest || >=sql-server-2016 || >=aps-pdw-2016 || >=sql-server-linux-2017 || =azuresqldb-mi-current || =fabric-sqldb

CREATE DATABASE SCOPED CREDENTIAL (Transact-SQL)

[!INCLUDE SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics PDW FabricSQLDB]

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.

:::image type="icon" source="../../includes/media/topic-link-icon.svg" border="false"::: Transact-SQL syntax conventions

Syntax

CREATE DATABASE SCOPED CREDENTIAL credential_name
WITH IDENTITY = 'identity_name'
    [ , SECRET = 'secret' ]
[ ; ]

Arguments

credential_name

Specifies the name of the database scoped credential being created. credential_name can't start with the number (#) sign. System credentials start with ##. The maximum length of credential_name is 128 characters.

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 with OPENROWSET BULK, see Import into a table from a file stored on Azure Blob storage.
• In [!INCLUDE sssql22-md] and later versions, the REST-API connector replaces HADOOP. For Azure Blob Storage and Azure Data Lake Gen 2, the only supported authentication method is shared access signature. For more information, see CREATE EXTERNAL DATA SOURCE (Transact-SQL).
• In [!INCLUDE sssql19-md], 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.
• SQL pools in Azure Synapse Analytics include the following notes:
  • 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.

Authentication	T-SQL	Supported	Notes
Shared Access Signature (SAS)	CREATE DATABASE SCOPED CREDENTIAL <credential_name> WITH IDENTITY = 'SHARED ACCESS SIGNATURE', SECRET = 'secret';	SQL Server 2022 and later, Azure SQL Managed Instance, Azure Synapse Analytics, Azure SQL Database
Managed Identity	CREATE DATABASE SCOPED CREDENTIAL <credential_name> WITH IDENTITY = 'MANAGED IDENTITY';	Azure SQL Database, Azure SQL Managed Instance, SQL Server 2025 with Azure Arc	To enable Azure Arc, see Managed identity for SQL Server enabled by Azure Arc
Microsoft Entra pass-through authentication via User Identity	CREATE DATABASE SCOPED CREDENTIAL <credential_name> WITH IDENTITY = 'USER IDENTITY';	[!INCLUDE Azure SQL Database], [!INCLUDE fabric-sqldb] *	In Azure Synapse, see Microsoft Entra Connect: Pass-through Authentication
S3 Access Key Basic authentication	CREATE DATABASE SCOPED CREDENTIAL <credential_name> WITH IDENTITY = 'S3 ACCESS KEY', SECRET = '<accesskey>:<secretkey>';	SQL Server 2022 and later versions
ODBC Data sources or Kerberos (MIT KDC)	CREATE DATABASE SCOPED CREDENTIAL <credential_name> WITH IDENTITY = '<identity_name>', SECRET = '<secret>';	SQL Server 2019 and later versions

* In [!INCLUDE fabric-sqldb], if no database-scoped credential is specified, authentication method defaults to 'USER IDENTITY' and uses the Entra ID user login as context.

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, remove the leading ?.

Remarks

A database scoped credential is a record that contains the authentication information that is required to connect to a resource outside [!INCLUDEssNoVersion]. 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 DMK before any database scoped credentials can be created. A DMK should be encrypted with a strong password. Azure SQL Database will create a DMK 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 DMK on a logical master database. The master key password is unknown to Microsoft and not discoverable after creation. For this reason, creating a DMK 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 (SMK). If the SMK is regenerated, the secret is re-encrypted using the new SMK.

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 might 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:

• [!INCLUDEssNoVersion_md] 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).

• [!INCLUDEssazuresynapse-md] 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.

• [!INCLUDEssSDS] uses database scoped credentials for its elastic query feature. This is the ability to query across multiple database shards.

• [!INCLUDEssSDS] uses database scoped credentials to write extended event files to Azure Blob Storage.

• [!INCLUDEssSDS] uses database scoped credentials for elastic pools. For more information, see Tame explosive growth with elastic databases

• BULK INSERT (Transact-SQL) and OPENROWSET (Transact-SQL) 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.

Examples

A. Create 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.

-- 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. Create 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 (Transact-SQL) and OPENROWSET (Transact-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. Create 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 [!INCLUDEssazuresynapse-md].

Azure Data Lake Store uses a Microsoft Entra application for service to service authentication.

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.

-- 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>';

D. Create a database scoped credential using Managed Identity

Applies to: [!INCLUDE sssql25-md]

[!INCLUDE sssql25-md] introduces support for Microsoft Entra managed identities. For information on how to use a managed identity with SQL Server enabled by Azure Arc, see Managed Identity.

SP_CONFIGURE 'allow server scoped db credentials',1; 
RECONFIGURE;  

CREATE DATABASE SCOPED CREDENTIAL [managed_id] 
WITH IDENTITY = 'Managed Identity'; 

#. Create a database scoped credential using Microsoft Entra ID

Applies to: [!INCLUDE Azure SQL Database], [!INCLUDE fabric-sqldb]

In [!INCLUDE Azure SQL Database] and [!INCLUDE fabric-sqldb], it is possible to use your own Entra ID login to authenticate an external data source.

In [!INCLUDE fabric-sqldb], if no database-scoped credential is specified, authentication method defaults to USER IDENTITY and uses the Entra ID user login as context.

CREATE DATABASE SCOPED CREDENTIAL MyCredential
WITH IDENTITY = 'User Identity';   

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)