Merge pull request #92760 from VanMSFT/aadmigrationtut2

Adding AAD Login tutorial alone

Author: ktoliver

articles/sql-database/toc.yml

@@ -759,6 +759,8 @@
         href: sql-database-managed-instance-aad-security-tutorial.md
       - name: Add managed instance to a failover group
         href: sql-database-managed-instance-failover-group-tutorial.md
+      - name: Migrate on-premises users and groups
+        href: tutorial-managed-instance-azure-active-directory-migration.md
 
   - name: Concepts
     items:

articles/sql-database/tutorial-managed-instance-azure-active-directory-migration.md

@@ -0,0 +1,339 @@
+---
+title: Migrate SQL Server on-premises Windows users and groups to Azure SQL Database managed instance using T-SQL DDL syntax | Microsoft Docs
+description: Learn about how to migrate SQL Server on-premises Windows users and groups to managed instance
+services: sql-database
+ms.service: sql-database
+ms.subservice: security
+ms.topic: tutorial
+author: GitHubMirek
+ms.author: mireks
+ms.reviewer: vanto
+ms.date: 10/22/2019
+---
+
+# Tutorial: Migrate SQL Server on-premises Windows users and groups to Azure SQL Database managed instance using T-SQL DDL syntax
+
+> [!NOTE]
+> The syntax used to migrate users and groups to managed instance in this article is in **public preview**.
+
+This article takes you through the process of migrating your on-premises Windows users and groups in your SQL Server to an existing Azure SQL Database managed instance using T-SQL syntax.
+
+In this tutorial, you learn how to:
+
+> [!div class="checklist"]
+> - Create logins for SQL Server
+> - Create a test database for migration
+> - Create logins, users, and roles
+> - Backup and restore your database to managed instance (MI)
+> - Manually migrate users to MI using ALTER USER syntax
+> - Testing authentication with the new mapped users
+
+## Prerequisites
+
+To complete this tutorial, the following prerequisites apply:
+
+- The Windows domain is federated with Azure Active Directory (Azure AD).
+- Access to Active Directory to create users/groups.
+- An existing SQL Server in your on-premises environment.
+- An existing managed instance. See [Quickstart: Create an Azure SQL Database managed instance](sql-database-managed-instance-get-started.md).
+- You can connect to your managed instance within your network. See the following articles for additional information: 
+    - [Connect your application to Azure SQL Database managed instance](sql-database-managed-instance-connect-app.md)
+    - [Quickstart: Configure a point-to-site connection to an Azure SQL Database Managed Instance from on-premises](sql-database-managed-instance-configure-p2s.md)
+    - [Configure public endpoint in Azure SQL Database managed instance](sql-database-managed-instance-public-endpoint-configure.md)
+
+## T-SQL DDL syntax
+
+Below are the T-SQL DDL syntax used to support SQL Server on-premises Windows users and groups migration to managed instance with Azure AD authentication.
+
+```sql
+-- For individual Windows users with logins 
+ALTER USER [domainName\userName] WITH LOGIN = [loginName@domainName.com]; 
+
+--For individual groups with logins 
+ALTER USER [domainName\groupName] WITH LOGIN=[groupName] 
+```
+
+## Arguments
+
+_domainName_</br>
+Specifies the domain name of the user.
+
+_userName_</br>
+Specifies the name of the user identified inside the database.
+
+_= loginName\@domainName.com_</br>
+Remaps a user to the Azure AD login
+
+_groupName_</br>
+Specifies the name of the group identified inside the database.
+
+## Part 1: Create logins for SQL Server on-premises users and groups
+
+> [!IMPORTANT]
+> The following syntax creates a user and a group login in your SQL Server. You'll need to make sure that the user and group exist inside your Active Directory (AD) before executing the below syntax. </br> </br>
+> Users: testUser1, testGroupUser </br>
+> Group: migration - testGroupUser needs to belong to the migration group in AD
+
+The example below creates a login in SQL Server for an account named _testUser1_ under the domain _aadsqlmi_. 
+
+```sql
+-- Sign into SQL Server as a sysadmin or a user that can create logins and databases
+ 
+use master;  
+go
+
+-- Create Windows login
+create login [aadsqlmi\testUser1] from windows;   
+go; 
+
+/** Create a Windows group login which contains one user [aadsqlmi\testGroupUser]. 
+testGroupUser will need to be added to the migration group in Active Directory
+**/
+create login [aadsqlmi\migration] from windows;    
+go; 
+
+
+-- Check logins were created
+select * from sys.server_principals; 
+go; 
+```
+
+Create a database for this test.
+
+```sql
+-- Create a database called [migration]
+create database migration 
+go
+```
+
+## Part 2: Create Windows users and groups, then add roles and permissions
+
+Use the following syntax to create the test user.
+
+```sql
+use migration;  
+go 
+ 
+-- Create Windows user [aadsqlmi\testUser1] with login 
+create user [aadsqlmi\testUser1] from login [aadsqlmi\testUser1]; 
+go 
+```
+
+Check the user permissions:
+
+```sql
+-- Check the user in the Metadata 
+select * from sys.database_principals; 
+go 
+ 
+-- Display the permissions – should only have CONNECT permissions
+select user_name(grantee_principal_id), * from sys.database_permissions; 
+go
+```
+
+Create a role and assign your test user to this role:
+
+```sql 
+-- Create a role with some permissions and assign the user to the role
+create role UserMigrationRole; 
+go
+
+grant CONNECT, SELECT, View DATABASE STATE, VIEW DEFINITION to UserMigrationRole; 
+go 
+
+alter role UserMigrationRole add member [aadsqlmi\testUser1]; 
+go 
+``` 
+
+Use the following query to display user names assigned to a specific role:
+
+```sql
+-- Display user name assigned to a specific role 
+SELECT DP1.name AS DatabaseRoleName,    
+   isnull (DP2.name, 'No members') AS DatabaseUserName    
+ FROM sys.database_role_members AS DRM   
+ RIGHT OUTER JOIN sys.database_principals AS DP1   
+   ON DRM.role_principal_id = DP1.principal_id   
+ LEFT OUTER JOIN sys.database_principals AS DP2   
+   ON DRM.member_principal_id = DP2.principal_id   
+WHERE DP1.type = 'R' 
+ORDER BY DP1.name; 
+```
+
+Use the following syntax to create a group. Then add the group to the role `db_owner`.
+
+```sql
+-- Create Windows group
+create user [aadsqlmi\migration] from login [aadsqlmi\migration]; 
+go
+
+-- ADD 'db_owner' role to this group
+sp_addrolemember 'db_owner', 'aadsqlmi\migration'; 
+go 
+
+--Check the db_owner role for 'aadsqlmi\migration' group 
+select is_rolemember('db_owner', 'aadsqlmi\migration')   
+go 
+-- Output  ( 1 means YES) 
+```
+
+Create a test table and add some data using the following syntax:
+
+```sql
+-- Create a table and add data 
+create table test ( a int, b int); 
+go 
+
+insert into test values (1,10) 
+go 
+
+-- Check the table values
+select * from test; 
+go
+```
+
+## Part 3: Backup and restore the individual user database to managed instance
+
+Create a backup of the migration database using the article [Copy Databases with Backup and Restore](/sql/relational-databases/databases/copy-databases-with-backup-and-restore), or use the following syntax:
+
+```sql
+use master; 
+go 
+backup database migration to disk = 'C:\Migration\migration.bak'; 
+go
+```
+
+Follow our [Quickstart: Restore a database to a managed instance](sql-database-managed-instance-get-started-restore.md).
+
+## Part 4: Migrate users to managed instance
+
+Execute the ALTER USER command to complete the migration process on managed instance.
+
+1. Sign into your managed instance using the SQL Admin account for managed instance. Then create your Azure AD login in the managed instance using the following syntax:
+
+    ```sql
+    use master 
+    go 
+    
+    -- Create login for AAD user [[email protected]] 
+    create login [testUser1@aadsqlmi.net] from external provider 
+    go
+    
+    -- Create login for the Azure AD group [migration]. This group contains one user [[email protected]] 
+    create login [migration] from external provider 
+    go 
+     
+    --Check the two new logins 
+    select * from sys.server_principals 
+    go
+    ```
+
+1. Check your migration for the correct database, table, and principals.
+
+    ```sql
+    -- Switch to the database migration that is already restored for MI 
+    use migration;  
+    go 
+     
+    --Check if the restored table test exist and contain a row 
+    select * from test; 
+    go 
+     
+    -- Check that the SQL on-premise Windows user/group exists  
+    select * from sys.database_principals; 
+    go 
+    -- the old user aadsqlmi\testUser1 should be there 
+    -- the old group aadsqlmi\migration should be there
+    ```
+
+1. Use the ALTER USER syntax to map the on-premises user to the Azure AD login.
+
+    ```sql
+    /** Execute the ALTER USER command to alter the Windows user [aadsqlmi\testUser1]
+    to map to the Azure AD user [email protected]
+    **/
+    alter user [aadsqlmi\testUser1] with login = [[email protected]]; 
+    go
+
+    -- Check the principal
+    select * from sys.database_principals; 
+    go 
+    -- New user [email protected] should be there instead 
+     
+    --Check new user permissions  - should only have CONNECT permissions
+    select user_name(grantee_principal_id), * from sys.database_permissions; 
+    go
+
+    -- Check a specific role   
+    -- Display Db user name assigned to a specific role 
+    SELECT DP1.name AS DatabaseRoleName,    
+    isnull (DP2.name, 'No members') AS DatabaseUserName    
+    FROM sys.database_role_members AS DRM   
+    RIGHT OUTER JOIN sys.database_principals AS DP1   
+    ON DRM.role_principal_id = DP1.principal_id   
+    LEFT OUTER JOIN sys.database_principals AS DP2   
+    ON DRM.member_principal_id = DP2.principal_id   
+    WHERE DP1.type = 'R' 
+    ORDER BY DP1.name;
+    ```
+
+1. Use the ALTER USER syntax to map the on-premises group to the Azure AD login.
+
+    ```sql
+    /** Execute ALTER USER command to alter the Windows group [aadsqlmi\migration]
+    to the Azure AD group login [migration]
+    **/
+    alter user [aadsqlmi\migration] with login = [migration]; 
+    -- old group migration is changed to Azure AD migration group
+    go
+
+    -- Check the principal
+    select * from sys.database_principals; 
+    go 
+     
+    --Check the group permission - should only have CONNECT permissions
+    select user_name(grantee_principal_id), * from sys.database_permissions; 
+    go 
+     
+    --Check the db_owner role for 'aadsqlmi\migration' user 
+    select is_rolemember('db_owner', 'migration')   
+    go 
+    -- Output 1 means 'YES'
+    ```
+
+## Part 5: Testing Azure AD user or group authentication
+
+Test authenticating to managed instance using the user previously mapped to the Azure AD login using the ALTER USER syntax.
+ 
+1. Log into the federated VM using your MI subscription as  `aadsqlmi\testUser1`
+1. Using SQL Server Management Studio (SSMS), sign into your managed instance using **Active Directory Integrated** authentication, connecting
+to the database `migration`.
+    1. You can also sign in using the testUser1@aadsqlmi.net credentials with the SSMS option **Active Directory – Universal with MFA support**. However, in this case, you can't use the Single Sign On mechanism and you must type a password. You won't need to use a federated VM to log in to your managed instance.
+1. As part of the role member **SELECT**, you can select from the `test` table
+
+    ```sql
+    Select * from test  --  and see one row (1,10)
+    ```
+
+
+Test authenticating to a managed instance using a member of a Windows group `migration`. The user `aadsqlmi\testGroupUser` should have been added to the group `migration` before the migration.
+
+1. Log into the federated VM using your MI subscription as  `aadsqlmi\testGroupUser` 
+1. Using SSMS with **Active Directory Integrated** authentication, connect to the MI server and the database `migration`
+    1. You can also sign in using the testGroupUser@aadsqlmi.net credentials with the SSMS option **Active Directory – Universal with MFA support**. However, in this case, you can't use the Single Sign On mechanism and you must type a password. You won't need to use a federated VM to log into your managed instance. 
+1. As part of the `db_owner` role, you can create a new table.
+
+    ```sql
+    -- Create table named 'new' with a default schema
+    Create table dbo.new ( a int, b int)
+    ```
+                             
+> [!NOTE] 
+> Due to a known design issue for Azure SQL DB, a create a table statement executed as a member of a group will fail with the following error: </br> </br>
+> `Msg 2760, Level 16, State 1, Line 4 
+The specified schema name "[email protected]" either does not exist or you do not have permission to use it.` </br> </br>
+> The current workaround is to create a table with an existing schema in the case above <dbo.new>
+
+## Next steps
+
+- [Tutorial: Migrate SQL Server to an Azure SQL Database managed instance offline using DMS](../dms/tutorial-sql-server-to-managed-instance.md?toc=/azure/sql-database/toc.json)