Skip to content

Commit 6b9ccdc

Browse files
ttorblettorble
authored
Merge pull request #191264 from VanMSFT/AADloginsSQLDB
Azure AD server logins release
2 parents 2243837 + 8b9bf05 commit 6b9ccdc

File tree

5 files changed

+389
-6
lines changed

5 files changed

+389
-6
lines changed

‎articles/azure-sql/database/authentication-azure-ad-logins-tutorial.md

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
---
2+
title: Create and utilize Azure Active Directory server logins
3+
description: This article guides you through creating and utilizing Azure Active Directory logins in the virtual master database of Azure SQL
4+
ms.service: sql-db-mi
5+
ms.subservice: security
6+
ms.topic: tutorial
7+
author: GithubMirek
8+
ms.author: mireks
9+
ms.reviewer: vanto
10+
ms.date: 03/14/2022
11+
---
12+
13+
# Tutorial: Create and utilize Azure Active Directory server logins
14+
15+
[!INCLUDE[appliesto-sqldb-sqlmi-asa-dedicated-only](../includes/appliesto-sqldb-sqlmi-asa-dedicated-only.md)]
16+
17+
> [!NOTE]
18+
> Azure Active Directory (Azure AD) server principals (logins) are currently in public preview for Azure SQL Database. Azure SQL Managed Instance can already utilize Azure AD logins.
19+
20+
This article guides you through creating and utilizing [Azure Active Directory (Azure AD) principals (logins)](authentication-azure-ad-logins.md) in the virtual master database of Azure SQL.
21+
22+
In this tutorial, you learn how to:
23+
24+
> [!div class="checklist"]
25+
> - Create an Azure AD login in the virtual master database with the new syntax extension for Azure SQL Database
26+
> - Create a user mapped to an Azure AD login in the virtual master database
27+
> - Grant server roles to an Azure AD user
28+
> - Disable an Azure AD login
29+
30+
## Prerequisites
31+
32+
- A SQL Database or SQL Managed Instance with a database. See [Quickstart: Create an Azure SQL Database single database](single-database-create-quickstart.md) if you haven't already created an Azure SQL Database, or [Quickstart: Create an Azure SQL Managed Instance](../managed-instance/instance-create-quickstart.md).
33+
- Azure AD authentication set up for SQL Database or Managed Instance. For more information, see [Configure and manage Azure AD authentication with Azure SQL](authentication-aad-configure.md).
34+
- This article instructs you on creating an Azure AD login and user within the virtual master database. Only an Azure AD admin can create a user within the virtual master database, so we recommend you use the Azure AD admin account when going through this tutorial. An Azure AD principal with the `loginmanager` role can create a login, but not a user within the virtual master database.
35+
36+
## Create Azure AD login
37+
38+
1. Create an Azure SQL Database login for an Azure AD account. In our example, we'll use `[email protected]` that exists in our Azure AD domain called `contoso`. A login can also be created from an Azure AD group or [service principal (applications)](authentication-aad-service-principal.md). For example, `mygroup` that is an Azure AD group consisting of Azure AD accounts that are a member of that group. For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).
39+
40+
> [!NOTE]
41+
> The first Azure AD login must be created by the Azure Active Directory admin. A SQL login cannot create Azure AD logins.
42+
43+
1. Using [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms), log into your SQL Database with the Azure AD admin account set up for the server.
44+
1. Run the following query:
45+
46+
```sql
47+
Use master
48+
CREATE LOGIN [bob@contoso.com] FROM EXTERNAL PROVIDER
49+
GO
50+
```
51+
52+
1. Check the created login in `sys.server_principals`. Execute the following query:
53+
54+
```sql
55+
SELECT name, type_desc, type, is_disabled
56+
FROM sys.server_principals
57+
WHERE type_desc like 'external%'
58+
```
59+
60+
You would see a similar output to the following:
61+
62+
```output
63+
Name type_desc type is_disabled
64+
[email protected] EXTERNAL_LOGIN E 0
65+
```
66+
67+
1. The login `[email protected]` has been created in the virtual master database.
68+
69+
## Create user from an Azure AD login
70+
71+
1. Now that we've created an Azure AD login, we can create a database-level Azure AD user that is mapped to the Azure AD login in the virtual master database. We'll continue to use our example, `[email protected]` to create a user in the virtual master database, as we want to demonstrate adding the user to special roles. Only an Azure AD admin or SQL server admin can create users in the virtual master database.
72+
73+
1. We're using the virtual master database, but you can switch to a database of your choice if you want to create users in other databases. Run the following query.
74+
75+
```sql
76+
Use master
77+
CREATE USER [bob@contoso.com] FROM LOGIN [bob@contoso.com]
78+
```
79+
80+
> [!TIP]
81+
> Although it is not required to use Azure AD user aliases (for example, `[email protected]`), it is a recommended best practice to use the same alias for Azure AD users and Azure AD logins.
82+
83+
1. Check the created user in `sys.database_principals`. Execute the following query:
84+
85+
```sql
86+
SELECT name, type_desc, type
87+
FROM sys.database_principals
88+
WHERE type_desc like 'external%'
89+
```
90+
91+
You would see a similar output to the following:
92+
93+
```output
94+
Name type_desc type
95+
[email protected] EXTERNAL_USER E
96+
```
97+
98+
> [!NOTE]
99+
> The existing syntax to create an Azure AD user without an Azure AD login is still supported, and requires the creation of a contained user inside SQL Database (without login).
100+
>
101+
> For example, `CREATE USER [[email protected]] FROM EXTERNAL PROVIDER`.
102+
103+
## Grant server-level roles to Azure AD logins
104+
105+
You can add logins to the [built-in server-level roles](security-server-roles.md#built-in-server-level-roles), such as the **##MS_DefinitionReader##**, **##MS_ServerStateReader##**, or **##MS_ServerStateManager##** role.
106+
107+
> [!NOTE]
108+
> The server-level roles mentioned here are not supported for Azure AD groups.
109+
110+
```sql
111+
ALTER SERVER ROLE ##MS_DefinitionReader## ADD MEMBER [AzureAD_object];
112+
```
113+
114+
```sql
115+
ALTER SERVER ROLE ##MS_ServerStateReader## ADD MEMBER [AzureAD_object];
116+
```
117+
118+
```sql
119+
ALTER SERVER ROLE ##MS_ServerStateManager## ADD MEMBER [AzureAD_object];
120+
```
121+
122+
Permissions aren't effective until the user reconnects. Flush the DBCC cache as well:
123+
124+
```sql
125+
DBCC FLUSHAUTHCACHE
126+
DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS
127+
```
128+
129+
To check which Azure AD logins are part of server-level roles, run the following query:
130+
131+
```sql
132+
SELECT roles.principal_id AS RolePID,roles.name AS RolePName,
133+
server_role_members.member_principal_id AS MemberPID, members.name AS MemberPName
134+
FROM sys.server_role_members AS server_role_members
135+
INNER JOIN sys.server_principals AS roles
136+
ON server_role_members.role_principal_id = roles.principal_id
137+
INNER JOIN sys.server_principals AS members
138+
ON server_role_members.member_principal_id = members.principal_id;
139+
```
140+
141+
## Grant special roles for Azure AD users
142+
143+
[Special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse) can be assigned to users in the virtual master database.
144+
145+
In order to grant one of the special database roles to a user, the user must exist in the virtual master database.
146+
147+
To add a user to a role, you can run the following query:
148+
149+
```sql
150+
ALTER ROLE [dbamanger] ADD MEMBER [AzureAD_object]
151+
```
152+
153+
To remove a user from a role, run the following query:
154+
155+
```sql
156+
ALTER ROLE [dbamanger] DROP MEMBER [AzureAD_object]
157+
```
158+
159+
`AzureAD_object` can be an Azure AD user, group, or service principal in Azure AD.
160+
161+
In our example, we created the user `[email protected]`. Let's give the user the **dbmanager** and **loginmanager** roles.
162+
163+
1. Run the following query:
164+
165+
```sql
166+
ALTER ROLE [dbamanger] ADD MEMBER [bob@contoso.com]
167+
ALTER ROLE [loginmanager] ADD MEMBER [bob@contoso.com]
168+
```
169+
170+
1. Check the database role assignment by running the following query:
171+
172+
```sql
173+
SELECT DP1.name AS DatabaseRoleName,
174+
isnull (DP2.name, 'No members') AS DatabaseUserName
175+
FROM sys.database_role_members AS DRM
176+
RIGHT OUTER JOIN sys.database_principals AS DP1
177+
ON DRM.role_principal_id = DP1.principal_id
178+
LEFT OUTER JOIN sys.database_principals AS DP2
179+
ON DRM.member_principal_id = DP2.principal_id
180+
WHERE DP1.type = 'R'and DP2.name like 'bob%'
181+
```
182+
183+
You would see a similar output to the following:
184+
185+
```output
186+
DatabaseRoleName DatabaseUserName
187+
dbmanager [email protected]
188+
loginmanager [email protected]
189+
```
190+
191+
## Optional - Disable a login
192+
193+
The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?view=azuresqldb-current&preserve-view=true) DDL syntax can be used to enable or disable an Azure AD login in Azure SQL Database.
194+
195+
```sql
196+
ALTER LOGIN [bob@contoso.com] DISABLE
197+
```
198+
199+
For the `DISABLE` or `ENABLE` changes to take immediate effect, the authentication cache and the **TokenAndPermUserStore** cache must be cleared using the following T-SQL commands:
200+
201+
```sql
202+
DBCC FLUSHAUTHCACHE
203+
DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS
204+
```
205+
206+
Check that the login has been disabled by executing the following query:
207+
208+
```sql
209+
SELECT name, type_desc, type
210+
FROM sys.server_principals
211+
WHERE is_disabled = 1
212+
```
213+
214+
A use case for this would be to allow read-only on [geo-replicas](active-geo-replication-overview.md), but deny connection on a primary server.
215+
216+
## See also
217+
218+
For more information and examples, see:
219+
220+
- [Azure Active Directory server principals](authentication-azure-ad-logins.md)
221+
- [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true)
222+
- [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql)

‎articles/azure-sql/database/authentication-azure-ad-logins.md

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: Azure Active Directory server principals
3+
description: Using Azure Active Directory server principals (logins) in Azure SQL
4+
ms.service: sql-db-mi
5+
ms.subservice: security
6+
ms.topic: conceptual
7+
author: GithubMirek
8+
ms.author: mireks
9+
ms.reviewer: vanto
10+
ms.date: 03/14/2022
11+
---
12+
13+
# Azure Active Directory server principals
14+
15+
[!INCLUDE[appliesto-sqldb-sqlmi-asa-dedicated-only](../includes/appliesto-sqldb-sqlmi-asa-dedicated-only.md)]
16+
17+
> [!NOTE]
18+
> Azure Active Directory (Azure AD) server principals (logins) are currently in public preview for Azure SQL Database. Azure SQL Managed Instance can already utilize Azure AD logins.
19+
20+
You can now create and utilize Azure AD server principals, which are logins in the virtual master database of a SQL Database. There are several benefits of using Azure AD server principals for SQL Database:
21+
22+
- Support [Azure SQL Database server roles for permission management](security-server-roles.md).
23+
- Support multiple Azure AD users with [special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse), such as the `loginmanager` and `dbmanager` roles.
24+
- Functional parity between SQL logins and Azure AD logins.
25+
- Increase functional improvement support, such as utilizing [Azure AD-only authentication](authentication-azure-ad-only-authentication.md). Azure AD-only authentication allows SQL authentication to be disabled, which includes the SQL server admin, SQL logins and users.
26+
- Allows Azure AD principals to support geo-replicas. Azure AD principals will be able to connect to the geo-replica of a user database, with a *read-only* permission and *deny* permission to the primary server.
27+
- Ability to use Azure AD service principal logins with special roles to execute a full automation of user and database creation, as well as maintenance provided by Azure AD applications.
28+
- Closer functionality between Managed Instance and SQL Database, as Managed Instance already supports Azure AD logins in the master database.
29+
30+
For more information on Azure AD authentication in Azure SQL, see [Use Azure Active Directory authentication](authentication-aad-overview.md)
31+
32+
## Permissions
33+
34+
The following permissions are required to utilize or create Azure AD logins in the virtual master database.
35+
36+
- Azure AD admin permission or membership in the `loginmanager` server role. The first Azure AD login can only be created by the Azure AD admin.
37+
- Must be a member of Azure AD within the same directory used for Azure SQL Database
38+
39+
By default, the standard permission granted to newly created Azure AD login in the `master` database is **VIEW ANY DATABASE**.
40+
41+
## Azure AD logins syntax
42+
43+
New syntax for Azure SQL Database to use Azure AD server principals has been introduced with this feature release.
44+
45+
### Create login syntax
46+
47+
```syntaxsql
48+
CREATE LOGIN login_name { FROM EXTERNAL PROVIDER | WITH <option_list> [,..] }  
49+
50+
<option_list> ::=     
51+
    PASSWORD = {'password'}  
52+
    | , SID = sid, ]
53+
```
54+
55+
The *login_name* specifies the Azure AD principal, which is an Azure AD user, group, or application.
56+
57+
For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).
58+
59+
### Create user syntax
60+
61+
The below T-SQL syntax is already available in SQL Database, and can be used for creating database-level Azure AD principals mapped to Azure AD logins in the virtual master database.
62+
63+
To create an Azure AD user from an Azure AD login, use the following syntax. Only the Azure AD admin can execute this command in the virtual master database.
64+
65+
```syntaxsql
66+
CREATE USER user_name FROM LOGIN login_name
67+
```
68+
69+
For more information, see [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql).
70+
71+
### Disable or enable a login using ALTER LOGIN syntax
72+
73+
The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?view=azuresqldb-current&preserve-view=true) DDL syntax can be used to enable or disable an Azure AD login in Azure SQL Database.
74+
75+
```syntaxsql
76+
ALTER LOGIN login_name DISABLE
77+
```
78+
79+
The Azure AD principal `login_name` won't be able to log into any user database in the SQL Database logical server where an Azure AD user principal, `user_name` mapped to login `login_name` was created.
80+
81+
> [!NOTE]
82+
> - `ALTER LOGIN login_name DISABLE` is not supported for contained users.
83+
> - `ALTER LOGIN login_name DISABLE` is not supported for Azure AD groups.
84+
> - An individual disabled login cannot belong to a user who is part of a login group created in the master database (for example, an Azure AD admin group).
85+
> - For the `DISABLE` or `ENABLE` changes to take immediate effect, the authentication cache and the **TokenAndPermUserStore** cache must be cleared using the T-SQL commands.
86+
>
87+
> ```sql
88+
> DBCC FLUSHAUTHCACHE
89+
> DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS
90+
> ```
91+
92+
## Roles for Azure AD principals
93+
94+
[Special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse) can be assigned to *users* in the virtual master database for Azure AD principals, including **dbmanager** and **loginmanager**.
95+
96+
[Azure SQL Database server roles](security-server-roles.md) can be assigned to *logins* in the virtual master database.
97+
98+
For a tutorial on how to grant these roles, see [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md).
99+
100+
101+
## Limitations and remarks
102+
103+
- The SQL server admin can’t create Azure AD logins or users in any databases.
104+
- Changing a database ownership to an Azure AD group as database owner isn't supported.
105+
- `ALTER AUTHORIZATION ON database::<mydb> TO [my_aad_group]` fails with an error message:
106+
```output
107+
Msg 33181, Level 16, State 1, Line 4
108+
The new owner cannot be Azure Active Directory group.
109+
```
110+
- Changing a database ownership to an individual user is supported.
111+
- A SQL admin or SQL user can’t execute the following Azure AD operations:
112+
- `CREATE LOGIN [[email protected]] FROM EXTERNAL PROVIDER`
113+
- `CREATE USER [[email protected]] FROM EXTERNAL PROVIDER`
114+
- `EXECUTE AS USER [[email protected]]`
115+
- `ALTER AUTHORIZATION ON securable::name TO [[email protected]]`
116+
- Impersonation of Azure AD server-level principals (logins) isn't supported:
117+
- [EXECUTE AS Clause (Transact-SQL)](/sql/t-sql/statements/execute-as-clause-transact-sql)
118+
- [EXECUTE AS (Transact-SQL)](/sql/t-sql/statements/execute-as-transact-sql)
119+
- Impersonation of Azure AD database-level principals (users) at a user database-level is still supported.
120+
- Azure AD logins overlapping with Azure AD administrator aren't supported. Azure AD admin takes precedence over any login. If an Azure AD account already has access to the server as an Azure AD admin, either directly or as a member of the admin group, the login created for this user won't have any effect. The login creation isn't blocked through T-SQL. After the account authenticates to the server, the login will have the effective permissions of an Azure AD admin, and not of a newly created login.
121+
- Changing permissions on specific Azure AD login object isn't supported:
122+
- `GRANT <PERMISSION> ON LOGIN :: <Azure AD account> TO <Any other login> `
123+
- When permissions are altered for an Azure AD login with existing open connections to an Azure SQL Database, permissions aren't effective until the user reconnects. Also [flush the authentication cache and the TokenAndPermUserStore cache](#disable-or-enable-a-login-using-alter-login-syntax). This applies to server role membership change using the [ALTER SERVER ROLE](/sql/t-sql/statements/alter-server-role-transact-sql) statement.
124+
- Setting an Azure AD login mapped to an Azure AD group as the database owner isn't supported.
125+
- [Azure SQL Database server roles](security-server-roles.md) aren't supported for Azure AD groups.
126+
127+
## Next steps
128+
129+
> [!div class="nextstepaction"]
130+
> [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md)

0 commit comments

Comments
 (0)