A while ago i wrote a simple tool which allows users to reset their expired password (an IISADMPWD replacment). The tool was created because at the time Office 365 did not have the ability to let federated users change their password. I have noticed that i was not the only one who had to deal with this problem, the tool was downloaded a number of times and i got some positive feedback. The tool was still very limited, if a user forgot his password, he still had to contact someone from IT to reset his password. Because remembering a password is one of the hardest things to do, resetting passwords for users took up to much of our time. This is why i build a new version of the tool which allows users to recover their account through a reset link sent to an alternative e-mail address. On this page you can find how to install, customize and download the tool. You can see it as a self-service portal for users.
[fancy_header variation=”orange”]How does it work[/fancy_header]
Using the Webbased Active Directory / Federated user password and recovery tool is very simple. When you navigate to the address where you installed it, you will see the following page:
Here you can login using your Active directory account. When successful you will see the self-service portal:
Here you can change your password, or the recovery e-mail address. When you try to login with an account that has an expired password, you can change your password immediately.
When the user does not have a recovery e-mail address set, an additional field will appear. You can make this e-mail field mandatory by a setting. If you have forgotten your password, it is possible to send a recovery link to an alternative e-mail address, if you supplied a recovery e-mail address earlier, ofcourse.
If you click on the link, you will land on the Change page, and set a new password. All the labels, notifications en texts can be customized.
- A Microsoft Windows Server
- .net 4.0
- Microsoft SQL 2008 Server or higher
- Some knowledge of IIS websites and application pools
- Some knowledge of Active Directory
- Some knowledge of SQL
- Some knowledge of log4net if desired
- I strongly recommend that you secure the tool with HTTPS.
Any version of SQL server will do. You can use the free express editions if you like. IIS must be .net 4.0 capable. In this howto i used Microsoft Windows Server 2012 R2, .NET 4.5 and Microsoft SQL server 2012 Express.
[fancy_header variation=”orange”]Installation – Active Directory user[/fancy_header]
The first thing you need to do is create an Active Directory user which has permissions to change passwords. I strongly recommend that you create/use a seperate OU for your users set the correct permissions on that OU. Create an Active Directory user called (for example) PasswordChanger . Give the user a very long and strong password, and store this password somewhere safe, you will need it later.
- Right-click the OU where your users are stored and click properties
- Open the tab Security and click Advanced
- Click add and select the user you created earlier.
- Permissions should apply to: Descendant User objects.
- Check the following permissions:
Permissions: Allowed to authenticate
Permissions: Change password
Permissions: Reset password
Properties: Write pwdLastSet
Properties: Write userAccountControl
Properties: Write lockoutTime
- OK all the windows to apply the permissions.
[fancy_header variation=”orange”]Installation – SQL database[/fancy_header]
The tool uses a SQL database to store session information, logging and recovery e-mail addresses. I have included a SQL script to create this database. The steps you need to follow are:
- Open up SQL Management Studio and connect to your server.
- Open db.sql and edit the file before executing. There are 3 variables to change
- @pwcUsername: This is the SQL user created by the script, this user will have full permissions on the new database. (remember this user, you will need it later)
- @pwcPassword: The password for the SQL user, i recommend you use a password generator for this password. (remember/store this password, you will need it later)
- @pwcDatabaseName: The name of the SQL database that will be created. (remember the name, you will need it later)
Then execute the script and the database is created!
[fancy_header variation=”orange”]Installation – IIS[/fancy_header]
To make the Webbased Active Directory / Federated user password and recovery tool work in IIS we have to create an IIS application pool and site. First we are going to create the application pool.
- Start Internet Information Services (IIS) Manager.
- Right click on Application Pools and choose Add Application Pool…
- Choose a name and copy settings from the screenshot. Click OK to continue
- The application pool is created. Right click it and click on Advanced Settings…
- In the section Process Model, change Identity to ApplicationPoolIdentity
- Change Load User Profile to false
The next step is to create the site or application. Before doing this, extract the files to you webserver directory. For instance: C:\inetpub\wwwroot\Password
- Right click Default Website Site and click on Add Application…
- Choose an Alias, the Application pool you just created and point it to the path where you extracted the files. Click OK to continue. The following screenshot is an example:
Configuration of IIS is now completed. The Webbased Active Directory / Federated user password and recovery tool should be accessible via http://<server ip>/Password
[fancy_header variation=”orange”]Configuration – setup page[/fancy_header]
The final step to make the tool work is to navigate to the setup page and fill in some parameters. The setup page is accessible via http://<server ip>/Password/setup/setup.aspx. The page looks like this:
I will explain every setting you can configure in this page. The setup page has little validation, so check your input.
- Active Directory Domain: Your domain name, you can find this domain name when you start Active Directory Users and Computers (Second level)
- Search tring: Where the tool should look for your users. You can limit the search string to a specific OU by adding OU=UserOU. To find out the Search string for your OU you can right click the OU in Active Directory Users and Computers and click properties. Then open the tab Attribute Editor and look for the setting distinguishedName.
- Active Directory user: This is the username of the Active Directory user you created earlier. This user has the permission to change passwords.
- Active Directory password: The password of the Active Directory user
- Password expires in days: Here you can specify your password expiration policy setting. This is used to check if a users password is expired.
- Resetkey timeout: The time in minutes that the resetlink sent via the recovery e-mail is valid.
- Force users to set Reset e-mail address: If this is set, you can force an user to set a recovery e-mail address. Otherwise this is not mandatory while the user changes his password.
- Display user passwords in logging: If this is set, user passwords are logged in plain text to log4net. If you log to your database this means passwords are stored in plain text which is not recommended.
- Session timeout: The time in minutes before a session expires.
- SMTP server: SMTP server used to send recovery e-mail
- SMTP server port: TCP port on which the SMTP server operates.
- From address: From what e-mail address the recovery e-mail should originate
- Blacklisted domains: A comma seperated list of domains which are not allowed in the alternative e-mail address. For example: if the Active Directory user account gives access to a @contoso.com e-mail address, you can blacklist the contoso.com domain. Because if a user is locked out, he cannot access his @contoso.com e-mail to click the recovery link. This would make the tool very useless.
- Database settings: Fill in SQL connection info.
Finally click Save to save the settings. Now you can test if you can login using a active directory account, if everything works as it should be, please remember to delete or secure the setup page.
[fancy_header variation=”orange”]Configuration – log4net[/fancy_header]
I have build in log4net support, and included configuration examples in web.config. To enable them you have to un-comment line 5 and line 41 t/m 107. You also have to change the connection string on line 61. The db.sql script also creates the logging table, so you can log to your SQL server. For more config examples you can take a look at this page.
[fancy_header variation=”orange”]Customization, Language’s [/fancy_header]
The Webbased Active Directory / Federated user password and recovery tool uses resx for localization and modifying labels and notifications in the tool. You can also change the layout by modifying style.css. To change the language file you need a simple free tool called Resx Editor written by someone called joannes, if you don’t want to use a tool you also can use a text editor. There are 2 languages included (you can find them in de App_GlobalResources folder):
- GlobalResources.resx: Default language file if a language specific file cannot be found. Language is english. This file also contains comments.
- GlobalResources.nl.resx: Dutch language file.
If you want to add a language, copy the GlobalResources.resx and rename it to GlobalResources.<lang code>.resx, where <lang code> is the code for your language and modify the file. To find out the code for your language, please look at this page and use the code located in the collumn 639-1. If you have created a new language, consider sharing it with me so i can add it as a download.
[fancy_header variation=”orange”]Downloads and resources [/fancy_header]
Update 2015-10-08: Added 3 items on the overview page: Firstname, Lastname and days until the password expires. (new field in the resx files)
Update 2015-10-21: Implemented bootstrap based layout. Some bugfixes
[fancy_header variation=”orange”]Update 2017-03-22 [/fancy_header]
I have fixed a bug in the tool. The tool used a method called setpassword instead of changepassword which made it possible for users to use a password which do not comply with the security policy. I have also tested the tool against a 2016 active directory. If the tool doesn’t appear to work, make sure the netlogon service is running on your DC’s.
[fancy_header variation=”orange”]Update 2020-03-26 [/fancy_header]
There is a new version available with the following changes: SSL support for connecting to your AD server, and SSL support for the SMTP server.
- Download the tool