Setting Up the IIS 6 Password Change Site - IISADMPWD
Since this is something we see coming up every once in a while here on the IIS Team, I through that for this article I would tell you a little bit about IISADMPWD - or the Internet Information Services Password Change site.
There are some links to this on the MSDN site like Tony DeCock article's on the Microsoft Support site, but as of now I have not been able to see an article that clearly explained three things: what the site does, how to configure it and how to use it.
What is IISADMPWD and what is it supposed to help you accomplish:
Initially IISADMPWD is a file folder that is shipped together with the IIS 6 / Windows 2003 distribution. You can find this folder in the %windir%\system32\inetsrv file folder. The content of the folder consists of some ASP files and a DLL (Dynamic Link Library) file. If you take a tool such as the Metabase Editor of the IIS Resource Kit, you will also find a few references to IISADMPWD in some of the IIS metabase keys that are setup by default.
IISADMPWD is meant to allow server administrators to setup a web-interface via which users of a given realm (can be an Active Directory domain, Novell domain or just local users from a give machine) can change the password for their account. This is especially useful if you imagine a scenario like the following:
- we setup an Active Directory which is supposed to handle our company's user population. All of our companies' employees have accounts in Active Directory and use them to logon to the company's resources. Some of these resources are online, either on the company's Intranet or even on public web-sites that we setup for the company and that require authentication to be accessed. The problem is that not everyone in our company logs on to their computers with their Active Directory credentials; some users use local accounts for business reasons that are irrelevant for this post.
- thus we setup an IIS 6 / Windows 2003 server that hosts several sites (like the company's intranet site) and a public website that our employees can access. The problem is that both these sites require authentication before allowing a user to access them: so we setup Integrated Authentication - users provide their Active Directory credentials to IIS that the web-server verifies with the domain controller.
- admitting this scenario, we have the following problem: how will a user, who does not logon to his computer with Active Directory credentials, know that his account password is about to expire or is already expired, and then how can he change his password. The low tech way would be for the user to call his system administrator (which might happen to be on vacation) and ask that his password be changed to something else over the phone - not very practical and not very secure.
The other solution to the problem is to setup the IISADMPWD password change site: once a user logs on he can opt to change his password at any given time. If a user logs in and his password is about to expire or is already expired, he will automatically be redirected to the IISADMPWD site to change his password, prior to him being allowed access to any other part of the site.
IISADMPWD page Structure:
You can configure several things for the IISADMPWD site. You can configure its look and feel as well as the way in which it is accessed (location of virtual directory) and the minimum notification time: how many days prior to password expiration will a user on the site be notified.
What we will do in this blog post is add an IISADMPWD site for our websites on the above mentioned case scenario: we will add an IISADMPWD virtual directory for the internal and external sites and we will configure them. For this I will make use of a tool called Metabase Explorer from the IIS Resource Kit available from Microsoft.
Setting up a virtual directory in IIS called IISADMPWD is quite straight forward. All we have to do is create a new virtual directory for each of our two sites, and make it point to the %windir%\system32\inetsrv\iisadmpwd folder on disk. We have to make sure that we grant script execution permissions for the virtual directory:
and ensure that the ASP execution engine is enabled on our IIS server:
Thus we should have the following layout for the case scenario we started with:
Once we add links from our main sites to the /iisadmpwd virtual directories we created, users on these sites should be able to opt to change their password when they wish. The only question is: to which file in the iisadmpwd folder should we add the link to?
This necessitates a closer look at what the purpose of each of the ASP pages in this folder is serves:
- text.asp - Contains the strings that will be used on the labels on all the forms in the other ASP pages, as well as the button labels for the forms. You are free to change any of these strings either to localize the pages or just to customize your forms. A word of warning: the strings are shared amongst all pages of the website, thus changing one string will modify all occurrences in every page.
-achg.asp- is the page that will attempt to perform the password change the user requests and will display the resulting message: either success or error. Based on the variables that this page recovers from the other pages that invoke it, the page will execute the required code to change either passwords for local user accounts or from accounts coming from an Active Directory. After executing the request this page will display the confirmation message, or any error or warning messages resulting from the attempt to execute the password change. The way that IIS knows that this page needs to be invoked when posting data from the other ASP forms is via 'AuthChangeURL' metabase key in IIS. If you wish to change the name of the page on disk you should also change the corresponding key.
- aexp.asp - is the page that will be displayed by default by IIS for an account whose password is expired. This page is configured to be invoked via the 'AuthExpiredURL' of the IIS metabase.
- aexp2.asp - is the page that you link to, to change the passwords for the local user accounts (accounts that are declared on the same machine as the IIS server runs on).
- aexp2b.asp - is the page that you link to when trying to change passwords for domain account users. By default, this page will attempt to post back data to the server over a secure connection, so if your site does not use SSL, your users will not be able to change their domain passwords. You may modify the page source code to change this behavior.
- aexp3.asp -is almost identical to aexp.asp. This page will does not use a secure connection to post back the parameters from its form. This page is invoked by IIS automatically if the password change site is setup to not use HTTPS via the 'AuthExpiredUnsecureURL' metabase key.
- anot.asp - this page will warn the user if the password for the account he/she is trying to change will expire. IIS know how to invoke this page via the metabese key 'AuthNotifyPwdExpURL'.
- anot3.asp - is almost identical to anot.asp, however this page will be used by IIS if the password change site is setup to not use a secure connection. The invocation of this page is configured via the IIS metabase key 'AuthNotifyPwdExpUnsecureURL'.
So now that we know what the pages are, we know that in the scenario we are looking at we will probably point to aexp2b.asp, which will gather data from our users that want to change the password and will forward it to achg.asp. Achg.asp will make a call to the iispwdchg.dll which in turn will make a call to the NetUserChangePassword API call via COM+ and RPC. The result of this call (success or failure due to an error) will be displayed by achg.asp.
Configuration Details:
Upon completing the above steps we now allow users to change passwords for Active Directory accounts in the scenario we started out with. But when looking at the structure of the IISADMPWD site I did mention a lot of IIS metabase keys. These keys are very useful for the notification part of the site, and this is what most people that want to setup IISADMPWD do not understand.
IIS has the capacity to know that the password for a given Active Directory or local account is about to expire or is expired. Afterwards we have to configure IIS to know what to do in this kind of case. This is where we use the Metabase Explorer to set the values of some of the metabase keys I had talked about before.
The first thing we specify to IIS, is where to find the IISADMPWD site. By default, IIS is already configured to look for it in a virtual directory called IISADMPWD underneath the site that uses authentication. This is done via the following keys:
AuthChangeURL /iisadmpwd/achg.asp
AuthExpiredURL /iisadmpwd/aexp.asp
AuthNotifyPwdExpURL /iisadmpwd/anot.asp
AuthExpiredUnsecureURL /iisadmpwd/aexp3.asp
AuthNotifyPwdExpUnsecureURL /iisadmpwd/anot3.asp
Should you wish to change the name of the folder where the password change site is located, you will need to change the values of the keys as well if you wish that notifications work. Should you wish to change the name of one of the pages (change the name of achg.asp to something more meaningful like acknowledgement.asp) you will need to change the key value as well.
Apart from this, you will also need to tell IIS how the site is setup: does it allow unsecured access or not. This is done via the PasswordChangeFlags metabase key. The values of this key are explained in the following article:
What the article does not mention is that in the default installation of IIS 6 this key is set to the value 6, instead of the mentioned default value of 0. This is mentioned in the following article:
Using MetabaseEditor I have modified the PasswordChangeFlags key from the value of 6 to a value of 0, indicating to IIS that my password change site is using HTTPS (secured connection). Next I looked at the PasswordExpirePrenotifyDays key. This was not present in my IIS metabase, so I went ahead and created the key using MetabaseExporer. The key type is DWORD and it is placed in the key hierarchy as shown in the image below (underneath the LM and W3SVC keys).
This key is very important to the notification mechanism on the website. If it is not created, IIS will notify users as soon as their password approaches N days before expiration - this value is defined either in Active Directory (for domain accounts) or in the local security policy settings (if we are dealing with local accounts). For my case scenario this value represents 15 days.
Thus if a user account called Paul in the Active Directory is 15 days or less from password expiration, IIS will immediately redirect the user anot.asp page after validating his logon. The user account Paul will be directed to anot.asp since this is the page that is configured as the default page for notification for users whose passwords are about to expire and since I have setup my site to use a secure connection. Should I have used an unsecured connection (PasswordChangeFlags key value 1), IIS would have redirected to anot3.asp instead.
After setting up the PasswordExpirePrenotifyDays key, I gave it a value of 10. Thus if the account for user Paul is 15 days away from expiration, the user will not be prompted that his password will expire. Should it be 10 days or less away from expiration, IIS will redirect the user to the anot3.asp page. The key acts as a constraint to the notification mechanism for passwords that are about to expire.
A few words before closing:
The first warning that I have to give everyone envisaging to use the password change site is that this component is officially supported by Microsoft up to and including Windows 2003 and IIS 6. Thus when support ends for Windows 2003 support will end for this component as well as stated on the Microsoft Support Site. It will NO LONGER be supported with Windows 2008 and IIS 7 or Windows 7 and IIS 7.5. Having said that I have made this site work even on Windows 2008 - and you can do so too but at your own risk.
Second of all, the people I have spoken to have had huge expectations of the notification mechanism in this site. Keep in mind that a user will only be prompted to change his password:
- if the site is setup correctly
- if he logs on to the site in the first place and his logon credentials are valid (disabled accounts, expired accounts - as opposed to accounts for which the password has expired - will be rejected at all times)
- if the password is about to expire in less days than the expiration age defined by the realm and the PasswordExpirePrenotifyDays metabase keys.
written by: Paul Cociuba - IIS France Support Team