Merge pull request #188392 from markwahl-msft/mwahl-prov-pg1

Azure AD: provisioning to SQL clarify where SQL Server is being used

Author: PRMerger20

includes/active-directory-app-provisioning-sql.md

@@ -9,11 +9,11 @@ For important details on what this service does, how it works, and frequently as
 
 ### On-premises prerequisites
 
- - A target system, such as a SQL database, in which users can be created, updated, and deleted.
- - A Windows Server 2016 or later computer with an internet-accessible TCP/IP address, connectivity to the target system, and with outbound connectivity to login.microsoftonline.com. An example is a Windows Server 2016 virtual machine hosted in Azure IaaS or behind a proxy. The server should have at least 3 GB of RAM.
- - A computer with .NET Framework 4.7.1.
+ - The application relies upon a SQL database, in which records for users can be created, updated, and deleted.
+ - An ODBC driver for that SQL database.
+ - A Windows Server 2016 or later computer with an internet-accessible TCP/IP address, connectivity to the target system, and with outbound connectivity to login.microsoftonline.com. An example is a Windows Server 2016 virtual machine hosted in Azure IaaS or behind a proxy. The server should have at least 3 GB of RAM and .NET Framework 4.7.1.
 
-Depending on the options you select, some of the wizard screens might not be available and the information might be slightly different. For purposes of this configuration, the user object type is used. Use the following information to guide you in your configuration. 
+Configuration of the connection to the application's database is done via a wizard. Depending on the options you select, some of the wizard screens might not be available and the information might be slightly different. Use the following information to guide you in your configuration.
 
 #### Supported systems
 * Microsoft SQL Server and Azure SQL
@@ -23,7 +23,7 @@ Depending on the options you select, some of the wizard screens might not be ava
 * Oracle 12c and 18c
 * MySQL 5.x
 
-Note: The generic SQL connector requires that column names are case-insensitive. MySQL is case-sensitive on Linux and Postgres is case-sensitive across platforms. As a result, they are not currently supported. 
+Note: The table-based strategy of the generic SQL connector requires that column names are case-insensitive. MySQL is case-sensitive on Linux and Postgres is case-sensitive across platforms. As a result, they are not currently supported with table-based strategy and configuring provisioning users into those databases is outside the scope of this article.
 
 ### Cloud requirements
 
@@ -33,27 +33,41 @@ Note: The generic SQL connector requires that column names are case-insensitive.
  - The Hybrid identity administrator role for configuring the provisioning agent and the Application Administrator or Cloud Administrator roles for configuring provisioning in the Azure portal.
 
 ## Prepare the sample database
-On a server running SQL Server, run the SQL script found in [Appendix A](#appendix-a). This script creates a sample database with the name CONTOSO. This is the database that you'll be provisioning users into.
 
+Typically, applications manage access with a table in the a SQL database, with one row per user. (More complex configurations could have multiple tables or rely upon stored procedures.) For demonstration purposes, if you do not already have a database with a suitable table, then you should create one which Azure AD can be permitted to use.  If you're using  SQL Server, then run the SQL script found in [Appendix A](#appendix-a). This script creates a sample database with the name CONTOSO, containing a single table `Employees`. This is the database table that you'll be provisioning users into.
+
+ |Table Column|Source|
+ |-----|-----|
+ |ContosoLogin|Azure AD user principal name|
+ |FirstName|Azure AD given name|
+ |LastName|Azure AD surname|
+ |Email|Exchange Online email address|
+ |InternalGUID|Generated by the database itself|
+ |AzureID|Azure AD object ID|
+ |textID|Azure AD mail nickname|
+
+## Install the ODBC driver
+
+The Windows Server where you'll be installing the provisioning agent requires an ODBC driver for your target database.  If you're planning to connect to SQL Server or Azure SQL database, then you should download the [ODBC driver for SQL Server (x64)](/sql/connect/odbc/download-odbc-driver-for-sql-server) and install that on the Windows Server.
 
 ## Create the DSN connection file
-The generic SQL connector is a DSN file to connect to the SQL server. First, you need to create a file with the ODBC connection information.
+The generic SQL connector requires a Data Source Name (DSN) file to connect to the SQL endpoint. First, you need to create a file with the ODBC connection information.
 
  1. Start the ODBC management utility on your server.  Use the 64-bit version.
      ![Screenshot that shows ODBC management.](./media/active-directory-app-provisioning-sql/odbc.png)</br>
  2. Select the **File DSN** tab, and select **Add**. 
      ![Screenshot that shows the File DSN tab.](./media/active-directory-app-provisioning-sql/dsn-2.png)</br>
- 3. Select **SQL Server Native Client 11.0** and select **Next**. 
+ 3. If you're using SQL Server or Azure SQL, select **SQL Server Native Client 11.0** and select **Next**. If you're using another database, select its ODBC driver.
      ![Screenshot that shows choosing a native client.](./media/active-directory-app-provisioning-sql/dsn-3.png)</br>
  4. Give the file a name, such as **GenericSQL**, and select **Next**. 
      ![Screenshot that shows naming the connector.](./media/active-directory-app-provisioning-sql/dsn-4.png)</br>
  5. Select **Finish**. 
      ![Screenshot that shows Finish.](./media/active-directory-app-provisioning-sql/dsn-5.png)</br>
- 6. Now configure the connection. Enter **APP1** for the name of the server and select **Next**.
+ 6. Now configure the connection. Enter **APP1** for the name of the server and select **Next**.  Note that the following steps will differ depending upon which ODBC driver you're using.  These assume you're using the driver to connect to SQL Server.
      ![Screenshot that shows entering a server name.](./media/active-directory-app-provisioning-sql/dsn-6.png)</br>
  7. Keep Windows authentication and select **Next**.
      ![Screenshot that shows Windows authentication.](./media/active-directory-app-provisioning-sql/dsn-7.png)</br>
- 8. Enter the name of the sample database, which is **CONTOSO**.
+ 8. Enter the name of the database, which in this sample is **CONTOSO**.
      ![Screenshot that shows entering a database name.](./media/active-directory-app-provisioning-sql/dsn-8.png)
  9. Keep everything default on this screen, and select **Finish**.
      ![Screenshot that shows selecting Finish.](./media/active-directory-app-provisioning-sql/dsn-9.png)</br>
@@ -67,7 +81,7 @@ The generic SQL connector is a DSN file to connect to the SQL server. First, you
 
 ## Download, install and configure the Azure AD Connect Provisioning Agent Package
 
- 1. [Download](https://aka.ms/OnPremProvisioningAgent) the provisioning agent and copy it onto the virtual machine or server that has connectivity to your SQL server.
+ 1. [Download](https://aka.ms/OnPremProvisioningAgent) the provisioning agent and copy it onto the Windows Server that has connectivity to your SQL server.
      >[!NOTE]
      >Please use different provisioning agents for on-premises application provisioning and Azure AD Connect Cloud Sync / HR-driven provisioning. All three scenarios should not be managed on the same agent. 
  1. Open the provisioning agent installer, agree to the terms of service, and select **next**.
@@ -102,14 +116,14 @@ The generic SQL connector is a DSN file to connect to the SQL server. First, you
      |Name|SQL|
      |Autosync timer (minutes)|120|
      |Secret Token|Enter your own key here. It should be 12 characters minimum.|
-     |Extension DLL|For a generic SQL connector, select **Microsoft.IAM.Connector.GenericSql.dll**.|
+     |Extension DLL|For the generic SQL connector, select **Microsoft.IAM.Connector.GenericSql.dll**.|
 4. On the **Connectivity** page, fill in the boxes with the values specified in the table that follows the image and select **Next**.
      ![Screenshot that shows the Connectivity page.](.\media\active-directory-app-provisioning-sql\conn-2.png)</br>
 
      |Property|Description|
      |-----|-----|
-     |DSN File|The Data Source Name file used to connect to the SQL Server instance.|
-     |User Name|The username of an individual with rights to the SQL Server instance. It must be in the form of hostname\sqladminaccount for standalone servers or domain\sqladminaccount for domain member servers.|
+     |DSN File|The Data Source Name file you created in the previous step, which is used to connect to the SQL instance.|
+     |User Name|The username of an account with rights to make updates to the table in the SQL instance. If the target database is SQL Server, the user name must be in the form of hostname\sqladminaccount for standalone servers or domain\sqladminaccount for domain member servers.|
      |Password|The password of the username just provided.|
      |DN is Anchor|Unless your environment is known to require these settings, don't select the **DN is Anchor** and **Export Type:Object Replace** checkboxes.|
  5. On the **Schema 1** page, fill in the boxes with the values specified in the table that follows the image and select **Next**.
@@ -119,7 +133,7 @@ The generic SQL connector is a DSN file to connect to the SQL server. First, you
      |-----|-----|
      |Object type detection method|Fixed Value|
      |Fixed value list/Table/View/SP|User|
- 6. On the **Schema 2** page, fill in the boxes with the values specified in the table that follows the image and select **Next**.
+ 6. On the **Schema 2** page, you'll indicate how users are represented in your database. In this sample, it's a table named `Employees`. Fill in the boxes with the values specified in the table that follows the image and select **Next**.
      ![Screenshot that shows the Schema 2 page.](.\media\active-directory-app-provisioning-sql\conn-4.png)</br>
 
      |Property|Value|
@@ -230,7 +244,7 @@ Now that you have the Azure AD ECMA Connector Host talking with Azure AD, you ca
      ![Screenshot that shows Assign users.](.\media\active-directory-app-provisioning-sql\app-5.png)
 
 ## Configure attribute mappings
-Now you need to map attributes between the on-premises application and your SQL server.
+Now you need to map attributes between the representation of the user in Azure AD and the representation of a user in the on-premises application's SQL database.
 
 #### Configure attribute mapping
  1. In the Azure AD portal, under **Enterprise applications**, select the **Provisioning** page.
@@ -275,7 +289,7 @@ After waiting, check the SQL database to ensure users are being provisioned.
  ![Screenshot checking that users are provisioned.](.\media\active-directory-app-provisioning-sql\configure-15.png)
 
 ## Appendix A
-Use the following SQL script to create the sample database.
+If you're using SQL Server, you can use the following SQL script to create the sample database.
 
 ```SQL
 ---Creating the Database---------