Skip to content

Commit 8eed82c

Browse files
VanMSFTVanMSFT
committed
Azure AD server logins release
1 parent a2a77e4 commit 8eed82c

File tree

3 files changed

+352
-3
lines changed

3 files changed

+352
-3
lines changed

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

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
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/11/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 a 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+
- The user creating the login must have Azure Active Directory admin permissions, or have membership in the `loginmanager` server role.
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.
72+
73+
1. We're using the virtual master database, but you can switch to a database of your choice. 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 roles to the Azure AD user
104+
105+
[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, including **dbmanager** and **loginmanager**. For more server roles, see [Azure SQL Database server roles for permission management](security-server-roles.md).
106+
107+
In order to grant one of the server roles, an Azure AD user with a login must be created in the virtual master database.
108+
109+
To add a user to a role, you can run the following query:
110+
111+
```sql
112+
ALTER SERVER ROLE [dbamanger] ADD MEMBER [AzureAD_object]
113+
```
114+
115+
To remove a user from a role, run the following query:
116+
117+
```sql
118+
ALTER SERVER ROLE [dbamanger] DROP MEMBER [AzureAD_object]
119+
```
120+
121+
`AzureAD_object` can be an Azure AD user, group, or service principal create in Azure SQL.
122+
123+
In our example, we created the user `[email protected]`. Let's give the user the **dbmanager** and **loginmanager** roles.
124+
125+
1. Run the following query:
126+
127+
```sql
128+
ALTER SERVER ROLE [dbamanger] ADD MEMBER [AAD_object]
129+
ALTER SERVER ROLE [loginmanager] ADD MEMBER [AAD_object]
130+
```
131+
132+
1. Check the server role assignment by running the following query:
133+
134+
```sql
135+
SELECT DP1.name AS DatabaseRoleName,
136+
isnull (DP2.name, 'No members') AS DatabaseUserName
137+
FROM sys.database_role_members AS DRM
138+
RIGHT OUTER JOIN sys.database_principals AS DP1
139+
ON DRM.role_principal_id = DP1.principal_id
140+
LEFT OUTER JOIN sys.database_principals AS DP2
141+
ON DRM.member_principal_id = DP2.principal_id
142+
WHERE DP1.type = 'R'and DP2.name like 'bob%'
143+
```
144+
145+
You would see a similar output to the following:
146+
147+
```output
148+
DatabaseRoleName DatabaseUserName
149+
dbmanager [email protected]
150+
loginmanager [email protected]
151+
```
152+
153+
## Optional - Disable a login
154+
155+
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.
156+
157+
```sql
158+
ALTER LOGIN [bob@contoso.com] DISABLE
159+
```
160+
161+
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.
162+
163+
## See also
164+
165+
For more information and examples, see:
166+
167+
- [Azure Active Directory server principals](authentication-azure-ad-logins.md)
168+
- [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true)
169+
- [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sq)

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

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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/11/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 master database of a SQL Database. There are several benefits of using Azure AD server principals for SQL Database:
21+
22+
- Support multiple Azure AD login accounts with high privileged server roles for SQL Database, such as the `loginmanager` and `dbmanager` roles.
23+
- 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.
24+
- 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.
25+
- Ability to use Azure AD service principal logins with high privilege server roles to execute a full automation of user and database creation, as well as maintenance provided by Azure AD applications.
26+
- Closer functionality between Managed Instance and SQL Database, as Managed Instance already supports Azure AD logins in the master database.
27+
28+
For more information on Azure AD authentication in Azure SQL, see [Use Azure Active Directory authentication](authentication-aad-overview.md)
29+
30+
## Permissions
31+
32+
The following permissions are required to utilize or create Azure AD logins in the master database.
33+
34+
- Azure AD admin permission or membership in the `loginmanager` server role. 
35+
- Must be a member of Azure AD within the same directory used for Azure SQL Database
36+
37+
By default, the standard permission granted to newly created Azure AD login in the `master` database is **VIEW ANY DATABASE**.
38+
39+
## Azure AD logins syntax
40+
41+
New syntax for Azure SQL Database to use Azure AD server principals has been introduced with this feature release.
42+
43+
### Create login syntax
44+
45+
```syntaxsql
46+
CREATE LOGIN login_name { FROM EXTERNAL PROVIDER [WITH OBJECT_ID = 'objectid'] | WITH <option_list> [,..] }  
47+
48+
<option_list> ::=     
49+
    PASSWORD = {'password'}  
50+
    | , SID = sid, ]
51+
```
52+
53+
For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).
54+
55+
### Create user syntax
56+
57+
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 master database.
58+
59+
To create an Azure AD user from an Azure AD login, use the following syntax:
60+
61+
```syntaxsql
62+
CREATE USER user_name FROM LOGIN login_name
63+
```
64+
65+
For more information, see [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql).
66+
67+
### Disable or enable a login using ALTER LOGIN syntax
68+
69+
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.
70+
71+
```syntaxsql
72+
ALTER LOGIN login_name DISABLE
73+
```
74+
75+
The Azure AD principal `login_name` won't be able to log into any user database in the SQL Database server where an Azure AD user principal, `user_name` mapped to login `login_name` was created.
76+
77+
> [!NOTE]
78+
> - `ALTER LOGIN login_name DISABLE` is not supported for contained users.
79+
> - `ALTER LOGIN login_name DISABLE` is not supported for Azure AD groups.
80+
> - 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).
81+
> - 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.
82+
>
83+
> ```sql
84+
> DBCC FLUSHAUTHCACHE
85+
> DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS
86+
> ```
87+
88+
## Azure AD logins and users with non-unique display names
89+
90+
It's possible to create Azure AD resources with the same display names. For example, creating an [Azure AD application (service principal)](authentication-aad-service-principal.md) with the same name. In this release, we're also introducing the ability to create logins and users using the **Object ID**.
91+
92+
```sql
93+
CREATE LOGIN login_name FROM EXTERNAL PROVIDER WITH OBJECT_ID = 'objectid'
94+
```
95+
96+
- To execute the above query, the specified Object ID must exist in Azure AD where the Azure SQL resides.
97+
- Most non-unique display names in Azure AD are related to service principals. Group names can also be non-unique as well. All Azure AD user display names are unique.
98+
99+
Using the display name of a service principal that isn't unique in Azure AD could lead to errors when creating the login or user in Azure SQL. For example, if `myapp` isn't unique, you may run into the following error when executing the following query:
100+
101+
```sql
102+
CREATE USER [myapp] FROM EXTERNAL PROVIDER
103+
```
104+
105+
```output
106+
Msg 33131, Level 16, State 1, Line 4
107+
Principal 'myapp' has a duplicate display name. Make the display name unique in Azure Active Directory and execute this statement again.
108+
```
109+
110+
With the T-SQL DDL extension to create logins or users with the Object ID, you can avoid this error and also specify an alias for the login or user created with the Object ID. For example, the following will create a user `myapp4466e` using the application Object ID `4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx`.
111+
112+
```sql
113+
CREATE USER [myapp4466e] FROM EXTERNAL PROVIDER
114+
WITH OBJECT_ID='4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx'
115+
```
116+
117+
For more information on obtaining the Object ID of a service principal, see [Service principal object](/azure/active-directory/develop/app-objects-and-service-principals#service-principal-object.)
118+
119+
To get the Object ID of the application, you can execute the following query:
120+
121+
```sql
122+
SELECT CAST(sid as uniqueidentifier) ApplicationID from sys.database_principals WHERE NAME = 'myapp4466e'
123+
```
124+
125+
## Limitations and remarks
126+
127+
- The SQL server admin can’t create Azure AD logins in the master database
128+
- Changing a database ownership to an Azure AD group as database owner isn't supported.
129+
- `ALTER AUTHORIZATION ON database::<mydb> TO [my_aad_group]` fails with an error message:
130+
```output
131+
Msg 33181, Level 16, State 1, Line 4
132+
The new owner cannot be Azure Active Directory group.
133+
```
134+
- Changing a database ownership to an individual user is supported.
135+
- A SQL admin or SQL user can’t execute the following Azure AD operations:
136+
- `CREATE LOGIN [[email protected]] FROM EXTERNAL PROVIDER`
137+
- `CREATE USER [[email protected]] FROM EXTERNAL PROVIDER`
138+
- `EXECUTE AS USER [[email protected]]`
139+
- `ALTER AUTHORIZATION ON securable::name TO [[email protected]]`
140+
- Impersonation of Azure AD server-level principals (logins) isn't supported:
141+
- [EXECUTE AS Clause (Transact-SQL)](/sql/t-sql/statements/execute-as-clause-transact-sql)
142+
- [EXECUTE AS (Transact-SQL)](/sql/t-sql/statements/execute-as-transact-sql)
143+
- Impersonation of Azure AD database-level principals (users) at a user database-level is still supported.
144+
- 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.
145+
- Changing permissions on specific Azure AD login object isn't supported:
146+
- `GRANT <PERMISSION> ON LOGIN :: <Azure AD account> TO <Any other login> `
147+
- 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. This applies to server role membership change using the [ALTER SERVER ROLE](/sql/t-sql/statements/alter-server-role-transact-sql) statement.
148+
- [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms) doesn't display the login names in **Object Explorer**.
149+
150+
## Next steps
151+
152+
> [!div class="nextstepaction"]
153+
> [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md)

‎articles/azure-sql/database/security-server-roles.md

Lines changed: 30 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.subservice: security
77
author: AndreasWolter
88
ms.author: anwolter
99
ms.topic: conceptual
10-
ms.date: 09/02/2021
10+
ms.date: 03/11/2022
1111
ms.reviewer: kendralittle, vanto, mathoma
1212
---
1313

@@ -29,7 +29,7 @@ For example, the server-level role **##MS_ServerStateReader##** holds the permis
2929
> [!NOTE]
3030
> Any permission can be denied within user databases, in effect, overriding the server-wide grant via role membership. However, in the system database *master*, permissions cannot be granted or denied.
3131
32-
Azure SQL Database currently provides three fixed server roles. The permissions that are granted to the fixed server roles cannot be changed and these roles can't have other fixed roles as members. You can add server-level SQL logins as members to server-level roles.
32+
Azure SQL Database currently provides three fixed server roles. The permissions that are granted to the fixed server roles cannot be changed and these roles can't have other fixed roles as members. You can add server-level logins as members to server-level roles.
3333

3434
> [!IMPORTANT]
3535
> Each member of a fixed server role can add other logins to that same role.
@@ -100,7 +100,8 @@ INNER JOIN sys.sql_logins AS sql_logins
100100
ON server_role_members.member_principal_id = sql_logins.principal_id
101101
;
102102
GO
103-
```
103+
```
104+
104105
### C. Complete example: Adding a login to a server-level role, retrieving metadata for role membership and permissions, and running a test query
105106

106107
#### Part 1: Preparing role membership and user account
@@ -174,6 +175,32 @@ SELECT * FROM sys.dm_exec_query_stats
174175

175176
```
176177

178+
### D. Check server-level roles for Azure AD logins
179+
180+
Run this command in the virtual master database to see all Azure AD logins that are part of server-level roles in SQL Database. For more information on Azure AD server logins, see [Azure Active Directory server principals](authentication-azure-ad-logins.md).
181+
182+
```sql
183+
SELECT roles.principal_id AS RolePID,roles.name AS RolePName,
184+
server_role_members.member_principal_id AS MemberPID, members.name AS MemberPName
185+
FROM sys.server_role_members AS server_role_members
186+
INNER JOIN sys.server_principals AS roles
187+
ON server_role_members.role_principal_id = roles.principal_id
188+
INNER JOIN sys.server_principals AS members
189+
ON server_role_members.member_principal_id = members.principal_id;
190+
```
191+
192+
### E. Check the virtual master database roles for specific user
193+
194+
Run this command in the virtual master database to check with roles `bob` has, or change the value to match your principal.
195+
196+
```sql
197+
SELECT DR1.name AS DbRoleName, isnull (DR2.name, 'No members') AS DbUserName
198+
FROM sys.database_role_members AS DbRMem RIGHT OUTER JOIN sys.database_principals AS DR1
199+
ON DbRMem.role_principal_id = DR1.principal_id LEFT OUTER JOIN sys.database_principals AS DR2
200+
ON DbRMem.member_principal_id = DR2.principal_id
201+
WHERE DR1.type = 'R' and DR2.name like 'bob%'
202+
```
203+
177204
## Limitations of server-level roles
178205

179206
- Role assignments may take up to 5 minutes to become effective. Also for existing sessions, changes to server role assignments don't take effect until the connection is closed and reopened. This is due to the distributed architecture between the *master* database and other databases on the same logical server.

0 commit comments

Comments
 (0)