Install solaris onbld package to get ctf tools.
[openafs-wiki.git] / WindowsK5AfsServicePrincipal.mdwn
1 Here are the instructions I used for creating a working afs/cell.name service principal on Windows 2003 SP2 Active Directory Kerberos 5 server.
2
3 These instructions require the Windows "ktpass.exe" command that comes with Windows Server 2003 support tools. There is a problem with the ktpass command that comes with SP1 support tools, see the following:
4
5 <http://support.microsoft.com/kb/919557>
6
7 The instructions below were tested with the ktpass command that comes with SP2. Production environments should be running SP2. I originally configured with SP1 and the ktpass fix mentioned above. Microsoft may not be giving out the ktpass fix anymore and tell you to upgrade to SP2. A few options have changed in the SP2 ktpass command and I would recommend using this one.
8
9 I originally got a working afs cell in Windows 2003 SP1 using the SP1 patch for ktpass. We since upgraded to SP2. Things continued to run fine, that is the SP2 patch did not break anything. I then configured again using the ktpass command that comes with SP2 as shown below.
10
11 Windows does not have service principals like MIT Kerberos. You create a regular Windows domain account, (User Principal Name or UPN), and turn the account into an afs/your.cell service principal using the ktpass utility. Once the service principal is created it then acts like a regular kerberos 5 service principal.
12
13 You use the windows "ktpass" command to create the serivce principal and generate a Kerberos style keytab. You then import the keytab into the afs [[KeyFile]] on the afs servers located in the /usr/afs/etc/KeyFile file using the [[OpenAFS]] supplied asetkey utility command.
14
15 #### <a name="Step 1) Create a Windows account"></a> Step 1) Create a Windows account
16
17 First create a new UPN account name using Active Directory Users and Computers. You can use any valid Windows UPN name. The commands below use the account name "afscs". Note the afs cell name is csw.unc.edu and the Windows AD REALM "CSW.UNC.EDU" in this example.
18
19 Once the account is created edit the properties for the user.
20
21     In the Account tab:
22
23     X = checked
24     _ = not checked
25
26     _   User must change password at next logon
27     _   User cannot change password
28     X   Password never expires
29     _   Store password using reversible encryption
30     _   Acount is disabled
31     _   Smart card is required for interactive logon
32     _   Account is trusted for delegation
33     _   Account is sensitive and cnnot be delegated
34     X   Use DES encryption types for this account
35     _   Do not require Kerberos preauthentication
36
37 After creating the "afscs" account you can use the Active Directory ADSI, (Active Directory Service Interface tool) Edit snapin tool from the mmc editor to look at the values for the account name if you are interested in watching what happens:
38
39     sAMAccountName = afscs
40     userPrincipalName = afscs@csw.unc.edu
41     servicePrincipalName = <Not Set>
42
43 Note the userPrincipalName value has a lower case realm/AD domain. This is standard for Windows. The sAMAccountName is used for pre-windows 2000 clients that do not use Kerberos. Note the servicePrincipalName is not set yet. This is done below with the Windows ktpass command.
44
45 There are 2 commands for dealing with service principals in Windows 2003. They are not documented very well.
46
47 setspn - set service principal for a user account. This command will add service/hostname type service principals to the "servicePrincipalName" directory entry.
48
49 ktpass - Key tab password. This command has many options, use "ktpass /?" to see them. Its primary purpose is to export a Kerberos complient keytab file for service principals to use. Like the afs/cell.name service principal.
50
51 This procedure does not use the setspn command. I could not find any good info on how to use this command and it was not necessary to get the afs/cell.name service principal to work.
52
53 #### <a name="Step 2) Run the Windows ktpass c"></a> Step 2) Run the Windows ktpass command utility
54
55 Run the ktpass command to map the UPN name to the afs/cell.name service principal.
56
57 ktpass -princ afs/csw.unc.edu@CSW.UNC.EDU -mapuser <afscs@CSW.UNC.EDU> -mapOp add -out keytab.afs +rndPass -crypto DES-CBC-CRC +DesOnly -ptype KRB5\_NT\_PRINCIPAL +DumpSalt
58
59 The ktpass command maps the -mapuser UPN you created in step 1 to the afs principal name, -princ afs/your.cell@REALM. A random password is assigned to the account using DES encryption. The +DesOnly option sets the "Use DES encryption types for this account" if it was not done so in the Account tab in step 1. The -out options specifies the file to place the kerberos principal keytab information in that you will use to import into the [[OpenAFS]] [[KeyFile]] on your afs servers. I do not know what the -ptype is for but the one that is shown will not produce and error and is the recommended type. The -mapOp add option is the default if not specified but I could not find any info on what option is for. The +DumpSalt option is for informational purposes and shows the salt that is appended to the password.
60
61 Here is the output from the ktpass command:
62
63     ktpass -princ afs/csw.unc.edu@CSW.UNC.EDU -mapuser afscs@CSW.UNC.EDU -mapOp
64     add -out keytab.afs +rndPass -crypto DES-CBC-CRC +DesOnly -ptype
65     KRB5_NT_SRV_INST +DumpSalt
66
67     C:\Documents and Settings\Administrator>ktpass -princ
68     afs/csw.unc.edu@CSW.UNC.ED
69     U -mapuser afscs@CSW.UNC.EDU -mapOp add -out keytab.afs +rndPass -crypto
70     DES
71     -CBC-CRC +DesOnly -ptype KRB5_NT_PRINCIPAL +DumpSalt
72     Targeting domain controller: eleanor.csw.unc.edu
73     Using legacy password setting method
74     Successfully mapped afs/csw.unc.edu to afscs.
75     Building salt with principalname afs/csw.unc.edu and domain CSW.UNC.EDU...
76     Hashing password with salt "CSW.UNC.EDUafscsw.unc.edu".
77     Key created.
78     Output keytab to keytab.afs:
79     Keytab version: 0x502
80     keysize 54 afs/csw.unc.edu@CSW.UNC.EDU ptype 1 (KRB5_NT_PRINCIPAL) vno 3 etype
81     0
82     x1 (DES-CBC-CRC) keylength 8 (0xcdecc7381adf6407)
83     Account afscs has been set for DES-only encryption.
84
85 Using ADSI edit shows the servicePrincipalName got updated:
86
87     sAMAccountName = afscs
88     userPrincipalName = afscs@csw.unc.edu
89     servicePrincipalName = afs/csw.unc.edu
90
91 #### <a name="Step 3) Copy and import the Wind"></a> Step 3) Copy and import the Windows generated keytab
92
93 The next step is to copy the keytab.afs file that was generated and import into the afs [[KeyFile]]. Note the "vno 3 etype" output. This is the kerberos key version number. You can verify the key number using the kerberos kvno command to your windows AD REALM. Use the linux/unix kvno command or the kvno command on Windows that comes with KFW (Kerberos For Windows). You will need the kvno when importing the keytab.afs to your afs [[KeyFile]]. This is an optional step for verifying the kvno set in Windows Active Directory:
94
95 First you need to get a regular ticket granting ticket from your Windows REALM:
96
97     % kinit
98     Password for sopko@CSW.UNC.EDU:
99
100 Then query for the afs service principal:
101
102     % kvno afs/csw.unc.edu@CSW.UNC.EDU
103     afs/csw.unc.edu@CSW.UNC.EDU: kvno = 3
104
105 Next you import the keytab.afs to your /usr/afs/etc/KeyFile. You should securely copy the keytab.afs file that was created on your Windows server using the ktpass command over to your afs server that runs the afs upsever for distributing files. If you do not have an upserver then you will have to generate one [[KeyFile]] and copy as you normally would.
106
107 If this is NOT a new installation make sure the existing key numbers in your [[KeyFile]] is different from the one that was generated with ktpass. If you have one or more keys in your [[KeyFile]] make sure they are different! Each time you run the Windows ktpass command it will increment the key. Do NOT use the ktpass -kvno option for configuring a key version number. It only seems to set the key number in the output keytab file not Active Directory, this will break things! It is simple to use the dos window and re-run the ktpass command until you get a key number you are happy with.
108
109 You can use the "asetkey list" command to list the keys that are currently in the [[KeyFile]]. Or you can run the "bos listkeys" command to get this information. You can run the ktpass command until the key number that is generated is different then the one currently in the [[KeyFile]].
110
111 You use the "asetkey" utility command that comes with [[OpenAFS]] to read the ketyab.afs file and import into the [[KeyFile]]. You specify the key version number when doing this:
112
113 /usr/sbin/asetkey add 3 keytab.afs afs/csw.unc.edu@CSW.UNC.EDU
114
115 You must specify the proper key number! You can use the kerberos ktutil command to read the keytab.afs file to verify the kvno. You can also use the keytab.afs keytab to obtain a K5 tgt as the user who is acting as the service principal. This can help you debug any issues. For example:
116
117     # ktutil
118     ktutil:  read_kt keytab.afs
119     ktutil:  list
120     slot KVNO Principal
121     ---- ----
122     ---------------------------------------------------------------------
123        1   3              afs/csw.unc.edu@CSW.UNC.EDU
124
125     # kinit -kt keytab.afs afs/csw.unc.edu
126     afsk5/root [/usr/afs/etc] # klist
127     Ticket cache: FILE:/tmp/krb5cc_3903_GAwMFc
128     Default principal: afs/csw.unc.edu@CSW.UNC.EDU
129
130     Valid starting     Expires            Service principal
131     07/23/07 13:46:34  07/23/07 23:46:34  krbtgt/CSW.UNC.EDU@CSW.UNC.EDU
132             renew until 07/30/07 13:46:34
133
134 If the kinit command fails then the keytab does not work with the service principal user you created with ktpass and you will have to try again.
135
136 You can use the "bos listkey" command to read the key you just imported into the [[KeyFile]] with asetkey. The ktutil takes a kerberos style keytab and the bos listkey takes an afs style [[KeyFile]]:
137
138     # bos listkeys afsk5.csw.unc.edu -localauth
139     key 3 has cksum 999999999
140     Keys last changed on Mon Jul 23 15:13:04 2007.
141     All done.
142
143 #### <a name="Step 4) Configure REALM name and"></a> Step 4) Configure REALM name and restart AFS db servers
144
145 After you import the key into the [[KeyFile]] you need to restart the AFS db servers which will read the new key. You should put the name of the Windows AD Kerberos REALM you are using in the /usr/afs/etc/krb.conf file. I believe the realm will default to your DNS domain if you do not do this. So if your REALM name is different then your DNS domain you must put the REALM name in the krb.conf file. I would enter the REALM to be safe.
146
147 Also be aware that you can specify a K5 REALM name option to the afs fileserver daemon as an option in your /usr/afs/local/Bosconfig file! I believe if you specify a "-realm REALM" option to your afs fileserver command it will override the one in the krb.conf file and the dns name. I would recommend putting the REALM in /usr/afs/etc/krb.conf file to lessen the confusion. Make sure you get the REALM settings correct!
148
149 From the [[OpenAFS]] Administrators manual section Managing Server Encryption Keys:
150
151 Issue the bos restart command to restart the database server processes on all database server machines. This forces them to start using the key in the [[KeyFile]] file that currently has the highest key version number.
152
153 Repeat this command in quick succession for each database server machine, starting with the machine that has the lowest IP address.
154
155 bos restart  buserver ptserver vlserver
156
157 The "Managing Server Encryption Keys" in the [[OpenAFS]] Administrator documentation explains how to delete your old keys if you wish. You can use the "bos removekey" or "asetkey delete" command to remove old key version numbers from the [[KeyFile]] after your maximum token lifetime for users has passed.
158
159 #### <a name="Migrating kaserver clients to us"></a> Migrating kaserver clients to use K5
160
161 I have found that I can run the kaserver and a K5 authentication server in parallel. It does not matter if it is a Windows or MIT K5 server.
162
163 If you are currently running a kaserver to do authentication then you have an afs [[KeyFile]] with your kaserver afs service principal in the [[KeyFile]]. If you add the K5 afs/cell.name service pricipal with the asetkey command to the [[KeyFile]] just make sure the key version numbers are different. Leave the kaserver afs principal key in the [[KeyFile]]!
164
165 If your pts protection server user names in afs and the users names you create in Windows or Mit kerberos are the same, you can continue to use "klog" style authentication from [[OpenAFS]] clients not yet configured to get tokens from the K5 server.
166
167 The reason one would do this is during the transition to K5. Once you have your K5 servers and your [[KeyFile]] configured to contain the old afs kaserver principal and the new K5 service principal you can continue to run the kaserver until your afs clients are configured to use K5 only and wean yourself off the kaserver. The downside of this is having 2 passwords, one in the kaserver and one in the K5 server and not confusing the users.
168
169 -- John Sopko - 24 Jul 2007