Lokasi ngalangkungan proxy:   [ UP ]  
[Ngawartoskeun bug]   [Panyetelan cookie]                
Skip to content

Commit a057e39

Browse files
VanMSFTVanMSFT
committed
Linux container AD tutorial
1 parent 8fc7ebd commit a057e39

3 files changed

Lines changed: 358 additions & 0 deletions

File tree

‎docs/linux/media/sql-server-linux-containers-ad-auth-tutorial/host-a-record.png‎

257 KB
Loading

‎docs/linux/sql-server-linux-containers-ad-auth-tutorial.md‎

Lines changed: 356 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,356 @@
1+
---
2+
title: Configure Active Directory authentication with SQL Server on Linux based containers using adutil
3+
description: Step by step on how to configure Active Directory authentication with SQL Server on Linux containers using adutil
4+
author: VanMSFT
5+
ms.author: vanto
6+
ms.reviewer: vanto
7+
ms.date: 12/07/2020
8+
ms.topic: tutorial
9+
ms.prod: sql
10+
ms.technology: linux
11+
moniker: ">= sql-server-linux-2017 || >= sql-server-2017 || =sqlallproducts-allversions"
12+
---
13+
14+
# Tutorial: Configure Active Directory authentication with SQL Server on Linux containers
15+
16+
This tutorial explains how to configure SQL Server on Linux containers to support Active Directory (AD) authentication, also known as integrated authentication. For an overview, see [Active Directory authentication for SQL Server on Linux](sql-server-linux-active-directory-auth-overview.md).
17+
18+
This tutorial consists of the following tasks:
19+
20+
> [!div class="checklist"]
21+
> - Install adutil-preview
22+
> - Join Linux host to AD domain
23+
> - Create an AD user for SQL Server and set the ServicePrincipalName (SPN) using the adutil tool
24+
> - Create the SQL Server service keytab file
25+
> - Create the mssql.conf and krb5.conf files to be used by the SQL Server container
26+
> - Mount the config files and deploy the SQL Server container
27+
> - Create AD-based SQL Server logins using Transact-SQL
28+
> - Connect to SQL Server using AD authentication
29+
30+
## Prerequisites
31+
32+
The following are required before configuring AD authentication:
33+
34+
- Have an AD Domain Controller (Windows) in your network.
35+
- Install the adutil-preview tool on a SQL Server container host machine. Follow the section below based on the Linux distribution that you are running to install adutil-preview.
36+
37+
## Container deployment and preparation
38+
39+
To setup your container, you'll need to know in advance what ports the container will be using on the host. The default port, 1433, might be mapped differently on your container host. For this tutorial, port 5433 on the host will be mapped to port 1433 of the container. For more information, see our quickstart, [Run SQL Server container images with Docker](quickstart-install-connect-docker.md)
40+
41+
When registering Service Principal Names (SPN), you can use the hostname of the machine or the name of the container, but you should set it up according to what you'd like to see when you connect to the container externally.
42+
43+
Ensure there is forwarding host (A) entry added in Active Directory for the Linux host IP address, mapping to the name of the SQL container. In this tutorial, the IP address of `myubuntu` host machine is `10.0.0.10`, and my container name is `sql1`. We add the forwarding host entry in the Active Directory as shown below. The entry ensure that when users connect to sql1.contoso.com, it reaches the right host.
44+
45+
:::image type="content" source="media/sql-server-linux-containers-ad-auth-tutorial/host-a-record.png" alt-text="add host record":::
46+
47+
For this tutorial, we're using an environment in Azure with three VMs. One VM acting as the windows domain controller (DC), with the domain name `contoso.com`. The Domain Controller name of `adVM.contoso.com`. The second machine is a Windows machine called `winbox`, running Windows 10 desktop, which is used as a client box and has SQL Server Management Studio (SSMS) installed. The third machine is an Ubuntu 18.04 LTS machine named `myubuntu`, which hosts the SQL Server containers. All machines have been joined to the `contoso.com` domain. For more information, see [Join SQL Server on a Linux host to an Active Directory domain](sql-server-linux-active-directory-join-domain.md).
48+
49+
> [!NOTE]
50+
> Joining the host container machine to the domain is not mandatory, as you can see later in this article.
51+
52+
## Install adutil-preview
53+
54+
On the Linux host machine, use the following commands to install adutil-preview.
55+
56+
### RHEL
57+
58+
1. Download the Microsoft Red Hat repository configuration file.
59+
60+
```bash
61+
sudo curl -o /etc/yum.repos.d/msprod.repo https://packages.microsofcom/config/rhel/8/prod.repo
62+
```
63+
64+
1. If you had a previous version of adutil installed, remove any older adutil packages.
65+
66+
```bash
67+
sudo yum remove adutil
68+
```
69+
70+
1. Run the following commands to install adutil-preview. `ACCEPT_EULA=Y` accepts the preview EULA for adutil, which is placed in the path `/usr/share/adutil/`.
71+
72+
```bash
73+
sudo ACCEPT_EULA=Y yum install -y adutil-preview
74+
```
75+
76+
### Ubuntu
77+
78+
1. Register the Microsoft Ubuntu repository.
79+
80+
```bash
81+
sudo curl https://packages.microsoft.com/config/ubuntu/18.04/prolist | sudo tee /etc/apt/sources.list.d/msprod.list
82+
```
83+
84+
1. If you had a previous version of adutil installed, please remove any older adutil packages using the below commands
85+
86+
```bash
87+
sudo apt-get remove adutil-preview
88+
```
89+
90+
1. Run the following command to install adutil-preview. `ACCEPT_EULA=Y` accepts the preview EULA for adutil, which is placed in the path `/usr/share/adutil/`.
91+
92+
```bash
93+
sudo ACCEPT_EULA=Y apt-get install -y adutil-preview
94+
```
95+
96+
### SLES
97+
98+
1. Add the Microsoft SQL Server repository to Zypper.
99+
100+
```bash
101+
sudo zypper addrepo -fc <https://packages.microsoft.com/config/sle12/prod.repo>
102+
```
103+
104+
1. If you had a previous version of adutil installed, remove any older adutil packages.
105+
106+
```bash
107+
sudo zypper remove adutil
108+
```
109+
110+
1. Run the following command to install adutil-preview. `ACCEPT_EULA=Y` accepts the preview EULA for adutil, which is placed in the path `/usr/share/adutil/`.
111+
112+
```bash
113+
sudo ACCEPT_EULA=Y zypper install -y adutil-preview
114+
```
115+
116+
## Creating the AD user, SPNs, and SQL Server service keytab
117+
118+
If you do not want the SQL Server on Linux container host to be part of the domain, and have not followed the steps to join the machine to the domain, then on another Linux machine which is already part of the AD domain, follow the below steps:
119+
120+
1. Create an AD user for SQL Server and set the SPN using the adutil tool.
121+
122+
2. Create and configure the SQL Server service keytab file.
123+
124+
Copy the mssql.keytab file created to the SQL container Linux host machine and configure the container to use the mssql.keytab. Optionally, you can also join your Linux host that will run the SQL container to the AD domain and follow the below steps on the same machine.
125+
126+
### Create an AD user for SQL Server and set the ServicePrincipalName using the adutil tool
127+
128+
Enabling AD authentication on SQL Server on Linux containers requires steps 1-3 mentioned below to be run on a Linux machine which is part of the AD domain.
129+
130+
1. Obtain or renew the Kerberos TGT (ticket-granting ticket) using the `kinit` command. Please use a privileged account for the `kinit` command. The account needs to have permission to connect to the domain, and also should be able to create accounts and SPNs in the domain.
131+
132+
> [!IMPORTANT]
133+
> Before you run this command, the host should already be part of the domain as shown in the previous step.
134+
135+
```bash
136+
kinit privilegeduser@DOMAIN.COM
137+
```
138+
139+
Example: For the environment described above, my privileged account is `amvin@CONTOSO.COM`
140+
141+
```bash
142+
kinit amvin@CONTOSO.COM
143+
```
144+
145+
2. Using the adutil tool, create the new user that will be used as the privileged AD Account by SQL Server.
146+
147+
```bash
148+
adutil user create --name sqluser -distname CN=sqluser,CN=Users,DC=CONTOSO,DC=COM --password 'P@ssw0rd'
149+
```
150+
151+
> [!NOTE]
152+
> Passwords may be specified in any of the three ways:
153+
>
154+
> - Password flag: --password \<password\>
155+
> - Environment variables - `ADUTIL_ACCOUNT_PWD`
156+
> - Interactive input
157+
>
158+
> The precedence of password entry methods follows the order of options listed above. The recommended options are to provide the password using Environment variables or interactive input, as they more secure compared to the password flag.
159+
160+
You can specify the name of the account using the distinguished name (`-distname`) as shown above, or you can also use the Organizational Unit (OU) name as well. The OU name (`--ou`) takes precedence over distinguished name in case you specify both. You can run the below command for more details:
161+
162+
```bash
163+
adutil user create --help
164+
```
165+
166+
3. Register SPNs to the user created above. You can use the host machine name instead of the container name if desired, depending on how you'd like the connection to look externally. In this tutorial, port 5433 is used instead of 1433. This is the port mapping for the container. Your port number could be different.
167+
168+
```bash
169+
adutil spn addauto -n sqluser -s MSSQLSvc -H sql1.contoso.com -p 5433
170+
```
171+
172+
> [!NOTE]
173+
>
174+
> - `addauto` will create the SPNs automatically, provided sufficient privileges are present for the kinit account.
175+
> - `-n`: name of the user account created in previous step, for which the SQL SPNs will be registered.
176+
> - `-s`: The service name to use for generating SPNs. In this case, it is for SQL Server service, and hence the service name is MSSQLSvc.
177+
> - `-H`: The hostname to use for generating SPNs. If not specified, the local host's FQDN will be used. Please provide the FQDN for the container name as well. In this case, the container name is `sql1` and the FQDN is `sql1.contoso.com`.
178+
> - `-p`: The port to use for generating SPNs. If not specified, SPNs will be generated without a port. SQL connections will only work in this case when the SQL Server is listening to the default port, 1433.
179+
180+
### Create the SQL Server service keytab file
181+
182+
Create the keytab file which contains entries for each of the 4 SPNs created previously, and one for the user. The keytab file will be mounted in the container, so it doesn't need to be created in the host machines `/var/opt/mssql/secrets/mssql.keytab` file. You can safely change this path, as long as the resulting keytab is mounted correctly when using docker/podman to run the container.
183+
184+
To create the keytab for all the SPNs, we can use the `createauto` option:
185+
186+
```bash
187+
adutil keytab createauto -k /container/sql1/secrets/mssql.keytab -p 5433 -H sql1.contoso.com --password 'P@ssw0rd' -s MSSQLSvc
188+
```
189+
190+
> [!NOTE]
191+
>
192+
> - `-k`: Path where you would like the `mssql.keytab` file to be created. In the above example the directory "/container/sql1/secrets” should already exist on the host.
193+
> - `-p`: The port to use for generating SPNs. If not specified, SPNs will be generated without a port.
194+
> - `-H`: The hostname to use for generating SPNs. If not specified, the local host's FQDN will be used. Please provide the FQDN for the container name as well. In this case, the container name is `sql1` and the FQDN is `sql1.contoso.com`.
195+
> - `-s`: The service name to use for generating SPNs. In this case, it is for SQL Server service, and hence the service name is MSSQLSvc.
196+
> `--password`: This is the password of the privileged AD user account that was created earlier.
197+
> `-e` or `--enctype`: Encryption types for the keytab entry. Use a comma-separated list of values. If not specified, an interactive prompt will be presented.
198+
199+
When given a choice to choose the encryption types (enc types), you can choose more than one. For this example, we chose `aes256-cts-hmac-sha1-96` and `arcfour-hmac`. Ensure you choose the enc type that is supported by the host and domain.
200+
201+
If you’d like to non-interactively choose the encryption type, you can specify your choice of encryption type with the -e argument in the above command. For additional help on the adutil commands, run the command below.
202+
203+
```bash
204+
adutil keytab createauto --help
205+
```
206+
207+
> [!NOTE]
208+
> `arcfour-hmac` is a weak encryption and not a recommended encryption type to be used in production environment. For example, on RHEL 8 machines, `arcfour-hmac` is a deprecated algorithm, and it is recommended that you enable AES encryption on the domain if you want to avoid using the `arcfour-hmac` encryption type. If you still want to enable `arcfour-hmac`, you can change the crypto policy by modifying it using the command:
209+
>
210+
> `update-crypto-policies --show`
211+
>
212+
> If the results shows `default`, then `arcfour-hmac` is disabled. You will need to change this to `legacy` to enable the `arcfour-hmac` encryption type. Doing this is NOT RECOMMENDED for production environment as this setting is less secure. You can change the crypto policy to legacy by running the following command:
213+
>
214+
>`update-crypto-policies --set LEGACY`
215+
>
216+
> For more information about the crypto policies, see [here](https://www.redhat.com/en/blog/consistent-security-crypto-policies-red-hat-enterprise-linux-8).
217+
218+
To create the keytab for the user, the command is:
219+
220+
```bash
221+
adutil keytab create -k /container/sql1/secrets/mssql.keytab -p sqluser --password 'P@ssw0rd!'
222+
```
223+
224+
> [!NOTE]
225+
>
226+
> - `-k`: Path where you would like the `mssql.keytab` file to be created. In the above example the directory "/container/sql1/secrets” should already exist on the host.
227+
> - `-p`: Is the user name that was created in previous steps.
228+
229+
The adutil keytab create/autocreate does not overwrite the previous files, it just appends to the file if already present.
230+
231+
Ensure the keytab created has the read permissions for the containers.
232+
233+
```bash
234+
chmod 440 /container/sqlco/secrets /mssql.keytab
235+
```
236+
237+
> [!NOTE]
238+
> At this point, you can copy the mssql.keytab from the current Linux host to the Linux host where you would deploy the SQL Server container, and follow the rest of the steps on the Linux host which will run the SQL Server Container. If the above steps were performed on the same Linux host where the SQL Containers will be deployed, then follow the next steps as well on the same host.
239+
240+
## Create the config files to be used by the SQL Server container
241+
242+
1. Create an `mssql.conf` file with the settings for AD. This file can be created anywhere on the host and needs to be mounted correctly during the docker run command. In this example, we placed this file `mssql.conf` under `/container/sql1 `, which is our container directory. The content of the `mssql.conf` is as shown below:
243+
244+
```output
245+
[network]
246+
privilegedadaccount = sqluser
247+
kerberoskeytabfile = /var/opt/mssql/secrets/mssql.keytab
248+
```
249+
250+
> [!NOTE]
251+
>
252+
> - `privilagedadaccount`: The account name for the user that was created in earlier steps.
253+
> - `kerberoskeytabfile`: The path on the container where the mssql.keytab file will be located.
254+
255+
1. Create a krb5.conf file. Your file should look like the following. The casing matters on these files.
256+
257+
```output
258+
[libdefaults]
259+
default_realm = DOMAIN.COM
260+
261+
[realms]
262+
DOMAIN.COM = {
263+
kdc = dc.domain.com
264+
admin_server = dc.domain.com
265+
default_domain = DOMAIN.COM
266+
}
267+
268+
[domain_realm]
269+
domain.com = DOMAIN.COM
270+
.domain.com = DOMAIN.COM
271+
```
272+
273+
Here is an example. Our sample domain name is `contoso.com` and the DC name is `adVM.contoso.com`.
274+
275+
```output
276+
[libdefaults]
277+
default_realm = CONTOSO.COM
278+
279+
[realms]
280+
CONTOSO.COM = {
281+
kdc = adVM.contoso.com
282+
admin_server = adVM.contoso.com
283+
default_domain = CONTOSO.COM
284+
}
285+
286+
[domain_realm]
287+
.contoso.com = CONTOSO.COM
288+
contoso.com = CONTOSO.COM
289+
```
290+
291+
1. Copy all files, `mssql.conf`, `krb5.conf`, `mssql.keytab` to a location that will be mounted to the SQL Server container. In this example, these files are placed on the host at the following locations: `mssql.conf` and `krb5.conf` at `/container/sql1/`. `mssql.keytab` is placed at the location `/container/sql1/secrets/`.
292+
293+
1. Make sure there is enough permission on these folders for the user running the docker/podman command. When the container starts, the user needs access to the folder path created. In this example, we provided the below permissions given to the folder path:
294+
295+
```bash
296+
sudo chmod 755 /container/sql1/
297+
```
298+
299+
## Mount the config files and deploy the SQL Server container
300+
301+
Run your SQL Server container, and mount the correct AD configuration files which were previously created as shown below:
302+
303+
```bash
304+
 sudo docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=\<YourStrong@Passw0rd\>" \
305+
-p 5433:1433 --name sql1 \
306+
-v /container/sql1:/var/opt/mssql \
307+
-v /container/sql1/krb5.conf:/etc/krb5.conf \
308+
-d mcr.microsoft.com/mssql/server:2019-latest
309+
```
310+
311+
> [!NOTE]
312+
> When running container on LSM (Linux Security Module) like SELinux enabled hosts, you need to mount the volumes using the `Z` option, which tells docker to label the content with a private unshared label. For more information, see [configure the SE Linux label](https://docs.docker.com/storage/bind-mounts/#configure-the-selinux-label).
313+
314+
Our example would contain the following commands:
315+
316+
```bash
317+
sudo docker run -e "ACCEPT_EULA=Y" -e "SA_PASSWORD=P@ssw0rd" -p 5433:1433 --name sql1 \
318+
-v /container/sql1:/var/opt/mssql/ \
319+
-v /container/sql1/krb5.conf:/etc/krb5.conf \
320+
--dns-search contoso.com \
321+
--dns 10.0.0.4 \
322+
--add-host adVM.contoso.com:10.0.0.4 \
323+
--add-host contoso.com:10.0.0.4 \
324+
--add-host contoso:10.0.0.4 \
325+
-d mcr.microsoft.com/mssql/server:2019-latest
326+
```
327+
328+
> [!NOTE]
329+
>
330+
> - The files `mssql.conf` and `krb5.conf` are located at the host file path `/container/sql1`.
331+
> - The `mssql.keytab` that was created is located on the host file path `/container/sql1/secrets`.
332+
> - Because our host machine is on Azure, the AD details in the same order needs to be appended to the docker run command. In our example, the domain controller `adVM` is in the domain `contoso.com`, with an IP address of `10.0.0.4`. The domain controller runs DNS and KDC.
333+
334+
## Create AD-based SQL Server logins in Transact-SQL
335+
336+
Connect to SQL container and run the following commands to create the login, and confirm that it's listed. You can run this command from a client machine (Windows or Linux) running SSMS, Azure Data Studio (ADS), or any other command-line interface (CLI) tool.
337+
338+
```sql
339+
create login [contoso\amvin] From Windows
340+
SELECT name FROM sys.server_principals;
341+
```
342+
343+
## Connect to SQL Server using AD authentication.
344+
345+
To connect using SSMS or ADS, log in to the SQL Server with windows credentials using the SQL Server name and port number (name could be the container name or the host name). For our example, the server name would be `sql1.contoso.com, 5433`.
346+
347+
You can also use a tool like [sqlcmd](../tools/sqlcmd-utility.md) to connect to the SQL Server in your container.
348+
349+
```bash
350+
sqlcmd -E -S 'sql1.contoso.com, 5433'
351+
```
352+
353+
## Next Steps
354+
355+
- [Quickstart: Run SQL Server container images with Docker](quickstart-install-connect-docker.md)
356+
- [Join SQL Server on a Linux host to an Active Directory domain](sql-server-linux-active-directory-auth-overview.md)

‎docs/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10025,6 +10025,8 @@
1002510025
href: linux/sql-server-linux-configure-msdtc-docker.md
1002610026
- name: Troubleshoot Docker containers
1002710027
href: linux/sql-server-linux-docker-container-troubleshooting.md
10028+
- name: Setup AD Authentication using adutil
10029+
href: linux/sql-server-linux-containers-ad-auth-tutorial.md
1002810030
- name: Develop
1002910031
href: linux/sql-server-linux-develop-overview.md
1003010032
items:

0 commit comments

Comments
 (0)