Merge pull request #13141 from MikeRayMSFT/20191206-bdc-security

Stage azdata security updates

Author: MikeRayMSFT

docs/big-data-cluster/change-azdata-password.md

@@ -0,0 +1,87 @@
+---
+title: Update AZDATA_PASSWORD
+description: Update the `AZDATA_PASSWORD` manually
+author: NelGson
+ms.author: negust
+ms.reviewer: mikeray
+ms.date: 12/19/2019
+ms.topic: conceptual
+ms.prod: sql
+ms.technology: big-data-cluster
+---
+
+# Manually update `AZDATA_PASSWORD`
+
+[!INCLUDE[tsql-appliesto-ssver15-xxxx-xxxx-xxx](../includes/tsql-appliesto-ssver15-xxxx-xxxx-xxx.md)]
+
+No matter if the cluster is operating with Active Directory (AD) integration or not, the `AZDATA_PASSWORD` is set during deployment. It provides a basic authentication to the cluster controller and master instance. This document describes how to manually update the `AZDATA_PASSWORD`.
+
+## Change `AZDATA_PASSWORD` for controller
+
+The following steps are also updating the Gateway (Knox) password in case the cluster is operating in non-AD mode.
+
+1. Obtain controller SQL server credentials
+
+   Run the following command as a Kubernetes administrator:
+
+   ```bash
+   kubectl get secret controller-sa-secret -n <cluster name> -o yaml | grep password
+   ```
+
+   Base64 decode the secret:
+   
+   ```bash
+   echo <password from kubectl command>  | base64 --decode && echo
+   ```
+
+2. In a separate command window, expose controller database server's port
+
+   ```bash
+   kubectl port-forward controldb-0 1433:1433 --address 0.0.0.0 -n <cluster name>
+   ```
+ 
+3. Use the SA password obtained above to connect to controller database server from a SQL client tool
+
+4. Generate a new complex password for `AZDATA_USERNAME` to replace existing `AZDATA_PASSWORD`
+
+   To simplify the example, the next steps use "newPassword" as the generated password is "newPassword". 
+
+5. Get the `hexsalt` from users table
+
+   ```sql
+   SELECT hexsalt FROM [auth].[users] WHERE username = '<username>'
+   ```
+
+`hexsalt` returns a random hex string, for example: `64FC59DF31244FFEE02F457BC0750226`.
+
+
+6. Install the platform appropriate dotnetcore app
+
+   Install the platform appropriate dotnetcore app for [`pbkdf2`](https://helsinki.redmond.corp.microsoft.com/dist/software/pbkdf2/).
+
+   The app is self-contained and does not require any prerequisite such as dotnet runtimes.
+
+7. Encrypt the new complex password using the `hexsalt`
+
+   ```bash
+   pbkdf2 <password> <hexsalt>
+   J2y4E4dhlgwHOaRr3HKiiVAKBfjuGDyYmzn88VXmrzM=
+   ```
+
+8. Update the password in the users table
+
+   ```bash
+   UPDATE [auth].[users] SET password = 'J2y4E4dhlgwHOaRr3HKiiVAKBfjuGDyYmzn88VXmrzM=' WHERE username = '<username>'
+   ```
+
+## Change `AZDATA_PASSWORD` in SQL Server master instance
+
+1. Connect to master SQL endpoint with any administrator user
+
+2. Run the following TSQL:
+
+   Change the password for the login you defined upon deployment in the parameter `AZDATA_USERNAME`.
+
+   ```sql
+   ALTER LOGIN <AZDATA_USERNAME> WITH PASSWORD = 'newPassword'
+   ```

docs/big-data-cluster/manage-user-access.md

@@ -0,0 +1,99 @@
+---
+title: Manage cluster access in Active Directory mode
+description: Manage access to the big data cluster
+author: NelGson
+ms.author: negust
+ms.reviewer: mikeray
+ms.date: 12/06/2019
+ms.topic: conceptual
+ms.prod: sql
+ms.technology: big-data-cluster
+---
+
+# Manage cluster access in Active Directory mode
+
+[!INCLUDE[tsql-appliesto-ssver15-xxxx-xxxx-xxx](../includes/tsql-appliesto-ssver15-xxxx-xxxx-xxx.md)]
+
+This document describes how to update the Active Directory (AD) groups provided upon deployment for clusterAdmins and clusterUsers.
+
+## Two overarching roles in the cluster
+
+AD groups can be provided in the security section of the deployment profile as part of two overarching roles for authorization within the cluster:
+
+* `clusterAdmins` - This parameter takes one AD group. Members of this group will get administrator permissions in the entire cluster. They have `sysadmin` permissions in SQL Server, `superuser` permissions in HDFS and Spark, and administrator rights in controller.
+
+* `clusterUsers` - List of the AD groups that are regular users without administrator permissions in the big data cluster. These users have permissions to login to SQL Server Master Instance, but will have no permissions to objects or data by default.
+
+To grant additional AD groups permissions to the cluster after the deployment, one option is to add any additional users and groups to the already nominated groups upon deployment. 
+
+However, it might not always be feasible for the administrators to alter the group memberships inside AD. To grant additional AD groups permissions without altering group memberships inside AD, complete the following steps.s
+
+## Grant additional AD groups administrator permissions
+
+>[!IMPORTANT]
+>This procedure does not grant additional AD groups administrator access to the hadoop components such as Spark and HDFS in the big data cluster. Those components only allow one single AD group as the superuser group, which means that the group specified in `clusterAdmins` upon deployment remain the superuser group even after this step.
+
+The following steps allow granting administrator access to controller as well as SQL Server master instance.
+
+### Create a login for the AD user or group in master SQL server. 
+
+1. Connect to master SQL endpoint using your favorite SQL client. Use any admin login. For example, `AZDATA_USERNAME`, which was provided during the deployment. Alternatively, it could be any AD account that belongs to the AD group provided as `clusterAdmins` in the security configuration.
+
+2. Run the following TSQL to create a login for the AD user/group.
+
+   ```sql
+   CREATE LOGIN [<domain>\<principal>] FROM WINDOWS;
+   ```
+
+   If you are granting admin privileges in SQL Server, then also grant the following permission:
+
+   ```sql
+   ALTER SERVER ROLE sysadmin ADD MEMBER [<domain>\<principal>];
+   GO
+   ```
+
+### Add the AD user or group to the roles table in the controller database 
+
+1. Obtain controller SQL server credentials:
+
+   Run the following command as a Kubernetes administrator:
+
+   ```bash
+   kubectl get secret controller-sa-secret -n <cluster name> -o yaml | grep password
+   ```
+
+   Base64 decode the secret:
+
+   ```bash
+   echo <password from kubectl command>  | base64 --decode && echo
+   ```
+
+2. In a separate command window, expose controller database server's port:
+
+   ```bash
+   kubectl port-forward controldb-0 1433:1433 --address 0.0.0.0 -n <cluster name>
+   ```
+
+3. Use the above connection to insert a row in the roles table. Type the realm value in uppercase.
+
+   If you are granting admin privileges, use `bdcAdmin` role in the `<role name>` below. For non-admin user, use the `bdcUser` role.
+
+   ```sql
+   USE controller;
+   GO
+
+   INSERT INTO [controller].[auth].[roles] VALUES (N'<user or group name>@<REALM>', N'<role name>')
+   GO
+   ```
+
+4. Verify that the members of the group you added has cluster administrator permissions by logging in to controller endpoint and running:
+
+   ```bash
+   azdata bdc config show
+   ```
+
+5. For non-administrator users, you can verify access by authenticating to SQL Master Instance or to controller using `azdata login`.
+
+## Next steps
+
+- [Security concepts for SQL Server Big Data Clusters](concept-security.md)

docs/toc.yml

@@ -189,6 +189,12 @@
         href: big-data-cluster/manage-notebooks.md
       - name: Manage with controller dashboard
         href: big-data-cluster/manage-with-controller-dashboard.md
+      - name: Security
+        items:
+        - name: Update AZDATA_PASSWORD
+          href: big-data-cluster/change-azdata-password.md
+        - name: Manage user access
+          href: big-data-cluster/manage-user-access.md
     - name: Notebooks
       items:
       - name: Notebooks overview