Worked with Mirek on changes

Author: VanMSFT

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

@@ -7,7 +7,7 @@ ms.topic: tutorial
 author: GithubMirek
 ms.author: mireks
 ms.reviewer: vanto
-ms.date: 03/11/2022
+ms.date: 03/14/2022
 ---
 
 # Tutorial: Create and utilize Azure Active Directory server logins
@@ -25,13 +25,13 @@ In this tutorial, you learn how to:
 > - Create an Azure AD login in the virtual master database with the new syntax extension for Azure SQL Database
 > - Create a user mapped to an Azure AD login in the virtual master database
 > - Grant server roles to an Azure AD user
-> - Disable a login
+> - Disable an Azure AD login
 
 ## Prerequisites
 
 - 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).
 - 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).
-- The user creating the login must have Azure Active Directory admin permissions, or have membership in the `loginmanager` server role.
+- 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.
 
 ## Create Azure AD login
 
@@ -70,7 +70,7 @@ In this tutorial, you learn how to:
 
 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.
 
-1. We're using the virtual master database, but you can switch to a database of your choice. Run the following query.
+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.
 
    ```sql
    Use master
@@ -100,36 +100,36 @@ In this tutorial, you learn how to:
 >
 > For example, `CREATE USER [[email protected]] FROM EXTERNAL PROVIDER`.
 
-## Grant server roles to the Azure AD user
+## Grant roles to the Azure AD login
 
-[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.
+[Special roles for SQL Database](/sql/relational-databases/security/authentication-access/database-level-roles#special-roles-for--and-azure-synapse) can be assigned to logins in the virtual master database.
 
-In order to grant one of the server roles, an Azure AD user with a login must be created in the virtual master database. 
+In order to grant one of the special database roles, an Azure AD user with a login must be created in the virtual master database. 
 
 To add a user to a role, you can run the following query:
 
 ```sql
-ALTER SERVER ROLE [dbamanger] ADD MEMBER [AzureAD_object] 
+ALTER ROLE [dbamanger] ADD MEMBER [AzureAD_object] 
 ```
 
 To remove a user from a role, run the following query:
 
 ```sql
-ALTER SERVER ROLE [dbamanger] DROP MEMBER [AzureAD_object] 
+ALTER ROLE [dbamanger] DROP MEMBER [AzureAD_object] 
 ```
 
-`AzureAD_object` can be an Azure AD user, group, or service principal create in Azure SQL.
+`AzureAD_object` can be an Azure AD user, group, or service principal in Azure AD.
 
 In our example, we created the user `[email protected]`. Let's give the user the **dbmanager** and **loginmanager** roles.
 
 1. Run the following query:
 
    ```sql
-   ALTER SERVER ROLE [dbamanger] ADD MEMBER [bob@contoso.com] 
-   ALTER SERVER ROLE [loginmanager] ADD MEMBER [bob@contoso.com] 
+   ALTER ROLE [dbamanger] ADD MEMBER [bob@contoso.com] 
+   ALTER ROLE [loginmanager] ADD MEMBER [bob@contoso.com] 
    ```
 
-1. Check the server role assignment by running the following query:
+1. Check the database role assignment by running the following query:
 
    ```sql
    SELECT DP1.name AS DatabaseRoleName,    
@@ -150,20 +150,42 @@ In our example, we created the user `[email protected]`. Let's give the user the *
    loginmanager	       [email protected]
    ```
 
-### Additional server-level roles
+### Server-level roles
 
 You can also choose to give the user additional [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.
 
+> [!NOTE]
+> The server-level roles mentioned here are not supported for Azure AD groups.
+
+```sql
+ALTER SERVER ROLE ##MS_DefinitionReader## ADD MEMBER [AzureAD_object];
+```
+
+```sql
+ALTER SERVER ROLE ##MS_ServerStateReader## ADD MEMBER [AzureAD_object];
+```
+
 ```sql
-ALTER SERVER ROLE ##MS_DefinitionReader## ADD MEMBER [AAD_object];
+ALTER SERVER ROLE ##MS_ServerStateManager## ADD MEMBER [AzureAD_object];
 ```
 
+Permissions aren't effective until the user reconnects. Flush the DBCC cache as well:
+
 ```sql
-ALTER SERVER ROLE ##MS_ServerStateReader## ADD MEMBER [AAD_object];
+DBCC FLUSHAUTHCACHE
+DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS 
 ```
 
+To check which Azure AD logins are part of server-level roles, run the following query:
+
 ```sql
-ALTER SERVER ROLE ##MS_ServerStateManager## ADD MEMBER [AAD_object];
+SELECT roles.principal_id AS RolePID,roles.name AS RolePName,
+       server_role_members.member_principal_id AS MemberPID, members.name AS MemberPName
+       FROM sys.server_role_members AS server_role_members
+       INNER JOIN sys.server_principals AS roles
+       ON server_role_members.role_principal_id = roles.principal_id
+       INNER JOIN sys.server_principals AS members 
+       ON server_role_members.member_principal_id = members.principal_id;
 ```
 
 ## Optional - Disable a login
@@ -174,6 +196,14 @@ The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?
 ALTER LOGIN [bob@contoso.com] DISABLE
 ```
 
+Check that the login has been disabled by executing the following query:
+
+```sql
+SELECT name, type_desc, type 
+FROM sys.server_principals 
+WHERE is_disabled = 1
+```
+
 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.
 
 ## See also

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

@@ -7,7 +7,7 @@ ms.topic: conceptual
 author: GithubMirek
 ms.author: mireks
 ms.reviewer: vanto
-ms.date: 03/11/2022
+ms.date: 03/14/2022
 ---
 
 # Azure Active Directory server principals
@@ -17,21 +17,23 @@ ms.date: 03/11/2022
 > [!NOTE]
 > 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.
 
-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:
+You can now create and utilize Azure AD server principals, which are logins in the virutal master database of a SQL Database. There are several benefits of using Azure AD server principals for SQL Database:
 
-- Support multiple Azure AD login accounts with high privileged server roles for SQL Database, such as the `loginmanager` and `dbmanager` roles.
-- 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.
+- Support multiple Azure AD login accounts 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.
+- Support [Azure SQL Database server roles for permission management](security-server-roles.md).
+- Functional parity between SQL logins and Azure AD logins.
+- 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.
 - 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.
-- 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.
+- 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.
 - Closer functionality between Managed Instance and SQL Database, as Managed Instance already supports Azure AD logins in the master database.
 
 For more information on Azure AD authentication in Azure SQL, see [Use Azure Active Directory authentication](authentication-aad-overview.md)
 
 ## Permissions
 
-The following permissions are required to utilize or create Azure AD logins in the master database.
+The following permissions are required to utilize or create Azure AD logins in the virtual master database.
 
-- Azure AD admin permission or membership in the `loginmanager` server role.  
+- 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.
 - Must be a member of Azure AD within the same directory used for Azure SQL Database 
 
 By default, the standard permission granted to newly created Azure AD login in the `master` database is **VIEW ANY DATABASE**. 
@@ -50,19 +52,21 @@ CREATE LOGIN login_name { FROM EXTERNAL PROVIDER [WITH OBJECT_ID = 'objectid'] |
     | , SID = sid, ] 
 ```
 
-For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true).
+The *login_name* specifies the Azure AD principal, which is an Azure AD user, group, or application.
+
+For more information, see [CREATE LOGIN (Transact-SQL)](/sql/t-sql/statements/create-login-transact-sql?view=azuresqldb-current&preserve-view=true). More information about the `WITH OBJECT_ID` clause is explained in [the section below](#azure-ad-logins-and-users-with-non-unique-display-names).
 
 ### Create user syntax
 
-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. 
+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.
 
 To create an Azure AD user from an Azure AD login, use the following syntax:
 
 ```syntaxsql
 CREATE USER user_name FROM LOGIN login_name
 ```
 
-For more information, see [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql).
+For more information, see [CREATE USER (Transact-SQL)](/sql/t-sql/statements/create-user-transact-sql). More information about the `WITH OBJECT_ID` clause is explained in [the section below](#azure-ad-logins-and-users-with-non-unique-display-names).
 
 ### Disable or enable a login using ALTER LOGIN syntax
 
@@ -72,7 +76,7 @@ The [ALTER LOGIN (Transact-SQL)](/sql/t-sql/statements/alter-login-transact-sql?
 ALTER LOGIN login_name DISABLE 
 ```
 
-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.
+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.
 
 > [!NOTE]
 > - `ALTER LOGIN login_name DISABLE` is not supported for contained users.
@@ -85,24 +89,17 @@ The Azure AD principal `login_name` won't be able to log into any user database
 >   DBCC FREESYSTEMCACHE('TokenAndPermUserStore') WITH NO_INFOMSGS 
 >   ```
 
-## Server-level roles for Azure AD principals
-
-[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**. For more server roles, see [Azure SQL Database server roles for permission management](security-server-roles.md).
+## Roles for Azure AD principals
 
-For a tutorial on how to grant these roles to a user, see [Tutorial: Create and utilize Azure Active Directory server logins](authentication-azure-ad-logins-tutorial.md).
-
-## Azure AD logins and users with non-unique display names
+[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**. 
 
-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**. 
+[Azure SQL Database server roles](security-server-roles.md) can be assigned to *logins* in the virtual master database..
 
-```sql
-CREATE LOGIN login_name FROM EXTERNAL PROVIDER WITH OBJECT_ID = 'objectid'
-```
+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).
 
-- To execute the above query, the specified Object ID must exist in Azure AD where the Azure SQL resides.
-- 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. 
+## Azure AD logins and users with non-unique display names
 
-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:
+Using the display name of a service principal that isn't unique in Azure AD leads 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:
 
 ```sql
 CREATE LOGIN [myapp] FROM EXTERNAL PROVIDER 
@@ -113,24 +110,55 @@ Msg 33131, Level 16, State 1, Line 4
 Principal 'myapp' has a duplicate display name. Make the display name unique in Azure Active Directory and execute this statement again. 
 ```
 
-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 login `myapp4466e` using the application Object ID `4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx`.
+> [!NOTE]
+> The same error would happen with `CREATE USER` with a non-unique name.
+
+This happens because it is 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) or Azure AD group with the same name. In this release, we're also introducing the ability to create logins and users using the **Object ID** of the Azure resource. 
+
+```sql
+CREATE LOGIN login_name FROM EXTERNAL PROVIDER WITH OBJECT_ID = 'objectid'
+```
+
+- To execute the above query, the specified Object ID must exist in Azure AD where the Azure SQL resource resides. Otherwise, the `CREATE` command will fail.
+- 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. 
+
+With the T-SQL DDL extension to create logins or users with the Object ID, you can avoid error *33131* and also specify an alias for the login or user created with the Object ID. For example, the following will create a login `myapp4466e` using the application Object ID `4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx`.
 
 ```sql
 CREATE LOGIN [myapp4466e] FROM EXTERNAL PROVIDER 
   WITH OBJECT_ID='4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx' 
 ```
 
+> [!TIP]
+> If you're looking to create a contained database user using the OBJECT ID, the command would be:
+>
+> ```sql
+> CREATE USER [myapp4466e] FROM EXTERNAL PROVIDER
+>   WITH OBJECT_ID='4466e2f8-0fea-4c61-a470-xxxxxxxxxxxx'
+> ```
+
 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.)
 
-To get the Object ID of the application, you can execute the following query:
+### Identify the user created for the application
 
-```sql
-SELECT CAST(sid as uniqueidentifier) ApplicationID from sys.server_principals WHERE NAME = 'myapp4466e'
-```
+It's important to verify the Azure AD alias is tied to the correct application or group. To check that the user was created for the correct service principal (application) or Azure AD group:
+
+1. Get the **Application ID** of the application, or **Object ID** of the Azure AD group from the user created in SQL Database by executing the following query:
+
+   ```sql
+   SELECT CAST(sid as uniqueidentifier) AzureID from sys.server_principals WHERE NAME = 'myapp4466e'
+   ```
+
+   `AzureID` corresponds to the *Applicaiton ID* for the service principal or *Object ID* for the Azure AD group.
+
+1. Go to the [Azure portal](https://portal.azure.com), and in your **Enterprise Application** or Azure AD group resource, check the **Application ID** or **Object ID** respectively. See if it matches the one obtained from the above query.
+
+> [!NOTE]
+> When creating a user from a service principal, the **Object ID** is required when using the `WITH OBJECT_ID` clause with the `CREATE` T-SQL statement. This is different from the **Application ID** that is returned when you are trying to verify the alias in Azure SQL. Using this verification process, you can identify the main owner of the SQL alias in Azure AD, and prevent possible mistakes when creating logins or users with an Object ID.
 
 ## Limitations and remarks
 
-- The SQL server admin can’t create Azure AD logins in the master database
+- The SQL server admin can’t create Azure AD logins or users in any databases.
 - Changing a database ownership to an Azure AD group as database owner isn't supported.
   - `ALTER AUTHORIZATION ON database::<mydb> TO [my_aad_group]` fails with an error message:
     ```output
@@ -152,6 +180,8 @@ SELECT CAST(sid as uniqueidentifier) ApplicationID from sys.server_principals WH
   - `GRANT <PERMISSION> ON LOGIN :: <Azure AD account> TO <Any other login> `
 - 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. 
 - [SQL Server Management Studio (SSMS)](/sql/ssms/download-sql-server-management-studio-ssms) doesn't display the login names in **Object Explorer**.
+- Setting an Azure AD login mapped to an Azure AD group as the database owner is not supported.
+- [Azure SQL Database server roles](security-server-roles.md) are not supported for Azure AD groups.
 
 ## Next steps