A SQL contained database user is an identity that lives inside a specific database instead of depending on a server-level login in master. The user connects directly to that database and receives permissions there. In Azure SQL, this model is useful for portability, tenant isolation, and Microsoft Entra authentication because access can be scoped to the database that actually contains the data. It does not remove the need for careful permissions. A contained user can still be overprivileged if it is added to broad database roles without review.
contained database user, database-contained user, Azure SQL contained user, CREATE USER FROM EXTERNAL PROVIDER
Difficulty
intermediate
CLI mappings
6
Last verified
2026-05-24
Microsoft Learn
Microsoft Learn describes contained database users as users that authenticate at the database level rather than through a matching login in the master database. In Azure SQL Database, they can support SQL authentication or Microsoft Entra identities, and the database name must be included in the connection string.
In Azure architecture, a contained database user is a data-plane security principal inside an Azure SQL database. It is created with T-SQL, often from a Microsoft Entra user, group, service principal, or managed identity, or as a SQL authenticated database user. Azure CLI does not create the database principal directly, but it helps validate the logical server, database, Entra administrator, firewall, private endpoint, and identity object before T-SQL runs. The concept connects identity governance, least privilege, database roles, connection strings, and tenant-by-tenant access design.
Why it matters
SQL contained database users matter because they reduce dependency on server-level logins and make database access more portable and precise. During migration, failover, or tenant onboarding, teams can grant access inside the database where the data lives instead of managing login mappings across master databases. That helps isolate customers, applications, and automation identities. It also improves connection scalability in Azure SQL when combined with database-level firewall rules because connections do not need the same master-database dependency. The risk is delegation: database owners or users with ALTER ANY USER can create access, so permission governance must be deliberate. Containment is powerful, not automatically safe.
⌁
Where you see it
Signals, screens, and Azure surfaces where this term usually becomes operational.
Signal 01
T-SQL queries against sys.database_principals show contained database users, authentication type, creation date, default schema, and whether the principal exists in the intended database.
Signal 02
Connection strings for contained users must name the target database, so failures often appear in application configuration, driver logs, or connection-pool errors. during troubleshooting sessions.
Signal 03
Azure CLI shows the surrounding server, database, Entra administrator, managed identity, service principal, firewall, and private endpoint context used before CREATE USER runs. during access reviews.
✦
When this becomes relevant
Specific situations where this term helps solve real Azure design, operations, migration, security, reliability, cost, or governance problems.
Grant an application managed identity access to one Azure SQL database without creating a server-level login.
Onboard tenant-specific database access using database-scoped users and roles rather than shared server credentials.
Move or restore a database while preserving user definitions that do not depend on master login mappings.
Use Microsoft Entra groups as contained database users so access reviews happen through group membership.
Reduce master-database dependency for connections when database-level firewall rules and contained users fit the design.
◆
Real-world case studies
Different enterprise-style examples that show the term being used to hit measurable objectives.
Case study 01
Legal SaaS isolates tenant administrators
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A legal SaaS platform stored each customer workspace in a separate Azure SQL database. Customer administrators needed read access for export audits, but the platform team refused to share server logins.
🎯Business/Technical Objectives
Grant each customer administrator access only to that customer database.
Use Microsoft Entra groups instead of individual one-off users where possible.
Reduce onboarding mistakes across hundreds of tenant databases.
Create access evidence for legal hold and data-export audits.
✅Solution Using SQL contained database user
The platform team created SQL contained database users from customer-specific Microsoft Entra groups in each tenant database. Azure CLI looked up group object details, confirmed the logical server and database, and verified Entra administrator configuration before DBAs ran CREATE USER FROM EXTERNAL PROVIDER. Each contained user was added to a custom read-only export role rather than db_owner. A provisioning script recorded the tenant database, group, approver, role membership, and expiration date. Offboarding used the same inventory to remove contained users when a customer left or changed administrators. Connection strings named the tenant database explicitly to avoid accidental master-context authentication.
📈Results & Business Impact
Tenant access setup time dropped from 45 minutes to 9 minutes per customer.
Access-review exceptions fell from 28 to 4 in the next quarterly audit.
No customer administrator received server-level login access during the rollout.
Data-export support tickets fell 35 percent because role membership was consistent.
💡Key Takeaway for Glossary Readers
Contained database users let SaaS teams grant database-specific access without turning customer administrators into server-level principals.
Case study 02
Research consortium shares one clinical dataset safely
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A university research consortium hosted a de-identified clinical study database in Azure SQL. Investigators from multiple institutions needed access, but each institution changed staff frequently.
🎯Business/Technical Objectives
Use group-based access instead of creating individual database users manually.
Keep access scoped to the approved study database only.
Verify external participants were represented in the associated directory before access was granted.
Produce access evidence for the research ethics board.
✅Solution Using SQL contained database user
The identity team imported approved external researchers into the associated Microsoft Entra tenant and managed membership through study-specific groups. DBAs created contained database users for those groups in the clinical study database and granted a custom role limited to approved views and stored procedures. Azure CLI was used to confirm group object IDs, SQL server Entra administrator state, database resource metadata, and private endpoint configuration before access testing. Quarterly review scripts compared Entra group membership with SQL database role membership. When a researcher changed institutions, removing them from the group removed practical access without touching server-level logins.
📈Results & Business Impact
Researcher onboarding dropped from five business days to one approved workflow.
Database access stayed limited to the study database, with no server-login sprawl.
Quarterly access evidence preparation fell from 18 hours to 3 hours.
Two departed researchers were removed before their next scheduled access review.
💡Key Takeaway for Glossary Readers
Contained database users pair well with Entra groups when collaboration access must be scoped tightly to one database.
Case study 03
Automation identity stops using a shared SQL password
Scenario, objectives, solution, measured impact, and takeaway.
📌Scenario
A shipping company used a shared SQL password for a nightly reconciliation job. The password was stored in multiple places and had more database permissions than the job required.
🎯Business/Technical Objectives
Replace the shared SQL password with a managed identity database user.
Limit permissions to reconciliation procedures and staging tables.
Reduce credential rotation incidents during month-end close.
Keep an auditable link between the Azure resource identity and SQL permissions.
✅Solution Using SQL contained database user
The platform team enabled a managed identity on the reconciliation compute resource, verified it with Azure CLI, and confirmed the Azure SQL server had a Microsoft Entra administrator. DBAs connected with an approved Entra admin and created a contained database user for the managed identity using CREATE USER FROM EXTERNAL PROVIDER. The user was placed in a custom database role with EXECUTE on reconciliation procedures and write access only to staging tables. Key Vault references for the old password were retired. Operators captured CLI identity output, database principal metadata, and role grants in the access-review package.
📈Results & Business Impact
Shared SQL password usage for the job was eliminated within one release cycle.
The reconciliation identity lost 87 percent of its previous effective database permissions.
Credential-rotation incidents during month-end close dropped to zero for two quarters.
Audit review could trace the Azure managed identity directly to database role membership.
💡Key Takeaway for Glossary Readers
A contained database user for a managed identity turns application access into a traceable, least-privilege database permission model.
Why use Azure CLI for this?
As an Azure engineer, I use Azure CLI around contained database users to verify everything outside the database before creating the user with T-SQL. CLI confirms the right tenant, subscription, logical server, database, Microsoft Entra administrator, managed identity, service principal, firewall, and private endpoint. That prevents a common mistake: connecting to the wrong database and granting access to the wrong principal. CLI also exports identity object IDs and resource IDs for evidence, which matters when database permissions are reviewed by auditors. The actual CREATE USER command happens in SQL tooling, but Azure CLI gives the control-plane facts that make the database change safe and repeatable.
CLI use cases
Show the SQL server and database before creating a contained user with T-SQL.
Confirm the Microsoft Entra administrator is configured for the logical server.
Look up user, group, service principal, or managed identity object details before CREATE USER FROM EXTERNAL PROVIDER.
List firewall rules or private endpoints when contained-user login tests fail.
Export database and identity metadata for access-review evidence.
Before you run CLI
Confirm tenant, subscription, logical server, database, and the identity object that should receive database access.
Remember that Azure RBAC and SQL database permissions are separate; Contributor does not equal db_datareader.
Verify a Microsoft Entra administrator exists if you plan to create external provider users.
Use controlled network access before testing logins; do not add broad firewall rules just to troubleshoot.
Plan least-privilege role membership and removal steps before creating the contained user.
What output tells you
Server and database output confirms the Azure control-plane target for the T-SQL user creation.
Entra admin output shows whether a directory identity can administer Microsoft Entra database principals.
Identity lookup output provides object IDs and display names so the wrong principal is not granted access.
Firewall and private endpoint output separates network failures from missing-user or wrong-role failures.
Role assignment output may help with automation identity governance, but SQL roles still require database inspection.
Mapped Azure CLI commands
Contained database user Azure context checks
adjacent-identity-operations
az sql server show --name <server> --resource-group <resource-group>
az sql serverdiscoverDatabases
az sql db show --name <database> --server <server> --resource-group <resource-group>
az sql dbdiscoverDatabases
az sql server ad-admin show --server <server> --resource-group <resource-group>
az sql server ad-admindiscoverDatabases
az ad user show --id <user-principal-name-or-object-id>
az ad userdiscoverIdentity
az ad group show --group <group-name-or-object-id>
az ad groupdiscoverIdentity
az identity show --name <managed-identity> --resource-group <resource-group>
az identitydiscoverDatabases
Architecture context
Architecturally, contained database users are part of a database-scoped identity design. I use them when access should follow the database rather than the logical server, such as tenant databases, application-specific databases, or portable databases moved between environments. The design starts with who connects: human users, Entra groups, application managed identities, service principals, or SQL password users. Then I map those principals to database roles with least privilege. Server administrators and Entra admins remain governance anchors, but normal access is granted at the database boundary. Connection strings must name the database. Monitoring should include user creation, role membership changes, and failed connection patterns.
Security
Security impact is direct because contained database users are authentication and authorization principals. They can improve least privilege by scoping access to one database, but they also move some access-management power into the database. Users with ALTER ANY USER or high database roles can create or modify principals, so role membership needs review. Prefer Microsoft Entra groups or managed identities over shared SQL passwords where possible. Avoid adding contained users to db_owner unless there is a strong reason. Audit CREATE USER, ALTER ROLE, permission grants, and dormant users. Also protect connection strings because the database name is part of contained-user authentication behavior.
Cost
Cost impact is indirect. Contained database users are not billed objects, but poor access design can create expensive operational work, security reviews, and incident response. Database-scoped users can reduce migration and tenant onboarding effort because permissions travel with the database more cleanly than server-login mappings. They can also prevent costly over-permissioning by avoiding broad server-level access. On the other hand, unmanaged contained users across hundreds of databases create audit labor and risk. Using Entra groups, managed identities, scripted provisioning, and periodic role reviews lowers administration cost. The FinOps angle is mostly human effort and avoided incident cost, not Azure meter charges.
Reliability
Reliability impact is indirect but important. Contained database users can reduce connection dependency on server-level logins and master-database mappings, which helps portability and can simplify failover or migration. If the contained user, role membership, or database name in the connection string is wrong, applications fail even though the database is online. Reliable operations include scripted user creation, role validation, login tests after restore or copy, and checks that managed identities still exist. For multi-tenant designs, onboarding and offboarding must be idempotent. A contained user model is reliable only when permissions and connection strings are deployed consistently across environments. Validate regularly across teams.
Performance
Runtime performance impact is usually indirect. A contained database user does not make queries faster by itself. Performance relevance appears in connection behavior and operational speed. In Azure SQL, database-level authentication and database-level firewall rules can reduce dependency on master checks for some connection paths, improving connection scalability for contained access models. The bigger performance benefit is operational: tenant onboarding, migrations, and restores complete faster when database permissions are portable and scripted. Misconfiguration can still hurt performance indirectly if applications repeatedly fail authentication, exhaust connection pools, or retry aggressively. Monitor failed logins and connection latency after changing contained users. Validate during release windows.
Operations
Operators manage contained database users through T-SQL and access-review processes, with Azure CLI supporting surrounding Azure checks. Daily tasks include verifying Entra admin configuration, confirming identity object IDs, reviewing database role membership, testing application connections, and removing users when a tenant or application is retired. Troubleshooting often involves determining whether failure is caused by network access, missing database name, absent contained user, disabled identity, or wrong role membership. Good runbooks separate Azure RBAC from SQL database permissions because assigning Contributor on the SQL server does not automatically grant data access. Evidence should include the principal, database, role, approver, and expiration when applicable.
Common mistakes
Creating the contained user in master instead of the application database that needs access.
Forgetting the database name in the connection string, causing authentication to follow the wrong context.
Assuming Azure RBAC role assignments grant SELECT, EXECUTE, or other database permissions.
Adding users to db_owner because it is faster than designing least-privilege roles.
Leaving tenant or contractor contained users active after the project or subscription ends.