Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Applies to:
Azure SQL Database
Azure SQL Managed Instance
This how-to guide outlines the steps to create a logical server for Azure SQL Database or an Azure SQL Managed Instance with Microsoft Entra-only authentication enabled during provisioning. The Microsoft Entra-only authentication feature prevents users from connecting to the server or managed instance using SQL authentication, and only allows connections authenticated with Microsoft Entra ID (formerly Azure Active Directory).
Note
Microsoft Entra ID was previously known as Azure Active Directory (Azure AD).
- Version 2.26.1 or later is needed when using The Azure CLI. For more information on the installation and the latest version, see Install the Azure CLI.
- Az 6.1.0 module or higher is needed when using PowerShell.
- If you're provisioning a managed instance using the Azure CLI, PowerShell, or REST API, a virtual network and subnet needs to be created before you begin. For more information, see Create a virtual network for Azure SQL Managed Instance.
To provision a logical server or managed instance, you'll need to have the appropriate permissions to create these resources. Azure users with higher permissions, such as subscription Owners, Contributors, Service Administrators, and Co-Administrators have the privilege to create a SQL server or managed instance. To create these resources with the least privileged Azure RBAC role, use the SQL Server Contributor role for SQL Database and SQL Managed Instance Contributor role for SQL Managed Instance.
The SQL Security Manager Azure RBAC role doesn't have enough permissions to create a server or instance with Microsoft Entra-only authentication enabled. The SQL Security Manager role will be required to manage the Microsoft Entra-only authentication feature after server or instance creation.
The following section provides you with examples and scripts on how to create a logical server or managed instance with a Microsoft Entra admin set for the server or instance, and have Microsoft Entra-only authentication enabled during server creation. For more information on the feature, see Microsoft Entra-only authentication with Azure SQL.
In our examples, we're enabling Microsoft Entra-only authentication during server or managed instance creation, with a system assigned server admin and password. This will prevent server admin access when Microsoft Entra-only authentication is enabled, and only allows the Microsoft Entra admin to access the resource. It's optional to add parameters to the APIs to include your own server admin and password during server creation. However, the password can't be reset until you disable Microsoft Entra-only authentication. An example of how to use these optional parameters to specify the server admin login name is presented in the PowerShell tab on this page.
Note
To change the Microsoft Entra-only authentication property after server or managed instance creation, other existing APIs should be used. For more information, see Managing Microsoft Entra-only authentication using APIs.
If Microsoft Entra-only authentication is set to false, which it is by default, a server admin and password will need to be included in all APIs during server or managed instance creation.
The PowerShell command New-AzSqlServer
is used to provision a new logical server. The below command will provision a new server with Microsoft Entra-only authentication enabled.
The server SQL administrator will be automatically created and the password will be set to a random password. Since SQL authentication connectivity is disabled with this server creation, the SQL administrator login won't be used.
The server Microsoft Entra admin will be the account you set for <MSEntraAccount>
, and can be used to manage the server.
Replace the following values in the example:
<ResourceGroupName>
: Name of the resource group for your logical server<Location>
: Location of the server, such asChina East 2
, orChina North 2
<ServerName>
: Use a unique logical server name<MSEntraAccount>
: Can be a Microsoft Entra user or group. For example,DummyLogin
$server = @{
ResourceGroupName = "<ResourceGroupName>"
Location = "<Location>"
ServerName = "<ServerName>"
ServerVersion = "12.0"
ExternalAdminName = "<MSEntraAccount>"
EnableActiveDirectoryOnlyAuthentication = $true
}
New-AzSqlServer @server
Here's an example of specifying the server admin name (instead of letting the server admin name being automatically created) at the time of logical server creation. As mentioned earlier, this login isn't usable when Microsoft Entra-only authentication is enabled.
$cred = Get-Credential
New-AzSqlServer -ResourceGroupName "<ResourceGroupName>" -Location "<Location>" -ServerName "<ServerName>" -ServerVersion "12.0" -ExternalAdminName "<MSEntraAccount>" -EnableActiveDirectoryOnlyAuthentication -SqlAdministratorCredentials $cred
For more information, see New-AzSqlServer.
The PowerShell command New-AzSqlInstance
is used to provision a new Azure SQL Managed Instance. The below command will provision a new managed instance with Microsoft Entra-only authentication enabled.
Note
The script requires a virtual network and subnet be created as a prerequisite.
The managed instance SQL administrator will be automatically created and the password will be set to a random password. Since SQL authentication connectivity is disabled with this provision, the SQL administrator login won't be used.
The Microsoft Entra admin will be the account you set for <MSEntraAccount>
, and can be used to manage the instance when the provisioning is complete.
Replace the following values in the example:
<managedinstancename>
: Name the managed instance you want to create<ResourceGroupName>
: Name of the resource group for your managed instance. The resource group should also include the virtual network and subnet created<MSEntraAccount>
: Can be a Microsoft Entra user or group. For example,DummyLogin
<Location>
: Location of the server, such aschinaeast2
, orchinanorth2
- The
SubnetId
parameter needs to be updated with the<Subscription ID>
,<ResourceGroupName>
,<VNetName>
, and<SubnetName>
. Your subscription ID can be found in the Azure portal
$instanceName = @{
Name = "<managedinstancename>"
ResourceGroupName = "<ResourceGroupName>"
ExternalAdminName = "<MSEntraAccount>"
EnableActiveDirectoryOnlyAuthentication = $true
Location = "<Location>"
SubnetId = "/subscriptions/<SubscriptionID>/resourceGroups/<ResourceGroupName>/providers/Microsoft.Network/virtualNetworks/<VNetName>/subnets/<SubnetName>"
LicenseType = "LicenseIncluded"
StorageSizeInGB = 128
VCore = 4
Edition = "GeneralPurpose"
ComputeGeneration = "Gen5"
}
New-AzSqlInstance $instanceName
For more information, see New-AzSqlInstance.
Once the deployment is complete for your managed instance, you might notice that the SQL Managed Instance needs Read permissions to access Microsoft Entra ID. Read permissions can be granted by selecting on the displayed message in the Azure portal by a person with enough privileges. For more information, see Directory Readers role in Microsoft Entra ID for Azure SQL.
- To reset the server administrator password, Microsoft Entra-only authentication must be disabled.
- If Microsoft Entra-only authentication is disabled, you must create a server with a server admin and password when using all APIs.
- If you already have a logical server or SQL managed instance, and just want to enable Microsoft Entra-only authentication, see Tutorial: Enable Microsoft Entra-only authentication with Azure SQL.
- For more information on the Microsoft Entra-only authentication feature, see Microsoft Entra-only authentication with Azure SQL.
- If you're looking to enforce server creation with Microsoft Entra-only authentication enabled, see Azure Policy for Microsoft Entra-only authentication with Azure SQL