Authentication
SQL logins, Windows and Kerberos, and every Microsoft Entra ID flow, including MFA.
authentication | Signs in with | Settings | Notes |
|---|---|---|---|
password | SQL login | user, password | |
integrated | Windows SSPI, or Kerberos on macOS/Linux | Run kinit user@REALM first on macOS/Linux | |
entraInteractive | Browser sign-in | tenantId, loginHint, clientId | MFA and Conditional Access. Token cached between runs |
entraDeviceCode | Code in the terminal, sign in on any device | tenantId | MFA. Works over SSH; cached between runs |
entraDefault | DefaultAzureCredential chain | tenantId, clientId (managed identity) | Environment, workload identity, managed identity, Visual Studio, Azure CLI, PowerShell, azd |
entraAzureCli | The az login account | tenantId | MFA happens in the CLI |
entraAzurePowerShell | The Connect-AzAccount account | tenantId | |
entraAzureDeveloperCli | The azd auth login account | tenantId | |
entraManagedIdentity | Managed identity | user-assigned: clientId, managedIdentityObjectId or managedIdentityResourceId | VMs, App Service, Functions, Container Apps, AKS |
entraServicePrincipal | App registration secret | tenantId, clientId, clientSecret | |
entraServicePrincipalCertificate | App registration certificate | tenantId, clientId, certificatePath (+ certificatePassword) or certificateThumbprint | PFX or PEM; thumbprint = Windows certificate store; sendCertificateChain for SN+I |
entraWorkloadIdentity | Federated workload identity | tenantId, clientId | AKS and other OIDC issuers (AZURE_FEDERATED_TOKEN_FILE) |
entraAzurePipelines | Azure DevOps service connection | tenantId, clientId, serviceConnectionId, systemAccessToken | Workload identity federation, no secret |
entraEnvironment | Environment variables | AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH | |
entraAccessToken | A token you already have | accessToken | e.g. ${env:SQL_TOKEN} from az account get-access-token |
entraIntegrated | Entra Integrated (federated domain) | user (optional) | Native SqlClient |
entraPassword | Entra user name and password | user, password | No MFA; deprecated by Microsoft; prints a warning |
Settings marked in the table go under entra: (except user and password).
MFA without signing in every time
bsm.yamlenvironments:
dev:
host: myapp-dev.database.windows.net
database: App
authentication: entraInteractive
entra:
tenantId: 7f3c1e2a-0000-0000-0000-000000000000
loginHint: you@contoso.com
The first run opens a browser for sign-in, MFA included. The token is kept in the operating system's encrypted store (Keychain on macOS, DPAPI on Windows, libsecret on Linux) and a small sign-in record (account and tenant ids, no tokens) is saved in ~/.bsm/auth/, so later runs are silent until the refresh token expires. bsm auth clear forgets saved sign-ins. Set entra.tokenCache: memory to sign in on every run. Without a browser (SSH sessions), use entraDeviceCode.
More entra settings
| Key | Meaning |
|---|---|
authorityHost | azurePublicCloud (default), azureGovernment, azureChina, or an authority URL |
additionallyAllowedTenants | Other tenants the credential may get tokens for |
tokenCache | persistent (default) or memory |
allowUnencryptedTokenCache | Linux without libsecret: allow an unencrypted cache file (off by default) |
scope | Override the token audience (default: what the server asks for, normally https://database.windows.net/.default) |
timeoutSeconds | Limit for interactive sign-in and CLI credential processes |
Examples
ci:
authentication: entraServicePrincipalCertificate
entra:
tenantId: 7f3c1e2a-0000-0000-0000-000000000000
clientId: 0a1b2c3d-0000-0000-0000-000000000000
certificatePath: ${env:DEPLOY_CERT_PATH}
certificatePassword: ${env:DEPLOY_CERT_PASSWORD}
appservice:
authentication: entraManagedIdentity
entra: { clientId: 9d8c7b6a-0000-0000-0000-000000000000 } # user-assigned; omit for system-assigned
gov:
host: myapp.database.usgovcloudapi.net
authentication: entraDefault
entra: { authorityHost: azureGovernment }
corp:
host: sql01.corp.contoso.com
authentication: integrated
Raw connection strings
A connectionString with Authentication=Active Directory Interactive (or any other SqlClient Entra mode) also works; bsm registers SqlClient's own Entra provider. Setting authentication: takes precedence and removes conflicting keywords from the string.
Checking sign-in
bsm doctor gets a token before connecting, so you can tell an identity problem from a network or permission problem:
provider SQL Server / Azure SQL
environment prod (protected)
auth EntraInteractive
entra token ok, expires 2026-11-03 19:22Z
server Azure SQL Database 12.0.2000.8 (SQL Azure)
login you@contoso.com
database App
encrypted TRUE
recorded env prod
journal 14 change(s) deployed
connection ok.
The Entra identity needs a database user (CREATE USER [you@contoso.com] FROM EXTERNAL PROVIDER) with rights to run your changes and to create the bsm schema on first deploy.