search

unosquare / passcore

A self-service password management tool for Active Directory
https://unosquare.github.io/passcore/
MIT License
1.04k stars 232 forks source link
activedirectory application-pool dotnet dotnetcore iis password password-manager password-meter powershell react recaptcha self-service ssl-certificate

readme

Github All Releases Buils status

Passcore Logo

PassCore: A self-service password change utility for Active Directory

:star: Please star this project if you find it useful!

Overview

PassCore is a very simple 1-page web application written in C#, using ASP.NET Core, Material UI (React Components), and Microsoft Directory Services (Default provider).

It allows users to change their Active Directory/LDAP password on their own, provided the user is not disabled.

PassCore does not require any configuration, as it obtains the principal context from the current domain. I wrote this because a number of people have requested several features that the original version did not have. The original version of this tool was downloaded around 8000 times in 2.5 years. My hope is that the new version continues to be just as popular. There really is no free alternative out there (that I know of) so hopefully this saves someone else some time and money.

You can check the wiki section for additional content related to development of this project.

Features

PassCore has the following features:

Installation on IIS

You can easily install using Powershell. Check the next section to know how.

  1. Ensure the server running IIS is domain-joined. To determine if the computer is domain-joined:
    • Go to the Start menu, right-click on Computer, then select Properties
    • Make sure the Domain field contains the correct setting.
  2. You need a Passcore copy to continue. We recommend to download the latest binary release of PassCore.
  3. NOTE: Before extracting the contents of the file, please right-click on it, select Properties and make sure the file is Unblocked (Click on the Unblock button at the bottom of the dialog if it is available). Then, extract the contents of the zip file to the directory where you will be serving the website from.
    • If you download the source code you need to run the following command via an Command Prompt. Make sure you start the Command Prompt with the Administrator option.
    • dotnet publish --configuration Release --runtime win-x64 --output "<path>"
    • The <path> is the directory where you will be serving the website from.
  4. Install the .NET Core 5.0.1 Windows Server Hosting bundle.
  5. Go to your IIS Manager, Right-click on Application Pools and select Add Application Pool.
  6. A dialog appears. Under Name enter PassCore Application Pool, Under .NET CLR Version select No Managed Code and finally, under Managed pipeline mode select Integrated. Click OK after all fields have been set.
  7. Now, right-click on the application pool you just created in the previous step and select Advanced Settings .... Change the Start Mode to AlwaysRunning, and the Idle Time-out (minutes) to 0. Click on OK. This will ensure PassCore stays responsive even after long periods of inactivity.
  8. Back on your IIS Manager, right-click on Sites and select Add Website
  9. A dialog appears. Under Site name, enter PassCore Website. Under Application pool click on Select and ensure you select PassCore Application Pool. Under Physical path, click on the ellipsis (...), navigate to the folder where you extracted PassCore.
    • Important: Make sure the Physical path points to the parent folder which is the one containing the files, logs and wwwroot folders.
    • NOTE: If the folder logs is not there you can created. To enable the logs you need to change stdoutLogEnabled to true in the web.config file. You need to add Full Control permissions to your IIS Application Pool account (see Troubleshooting).
  10. Under the Binding section of the same dialog, configure the Type to be https, set IP Address to All Unassigned, the Port to 443 and the Hostname to something like password.yourdomain.com. Under SSL Certificate select a certificate that matches the Hostname you provided above. If you don't know how to install a certificate, please refer to SSL Certificate Install on IIS 8 or SSL Certificate Install on IIS 10 , in order to install a proper certificate.
    • Important: Do not serve this website without an SSL certificate because requests and responses will be transmitted in cleartext and an attacker could easily retrieve these messages and collect usernames and passwords.
  11. Click OK and navigate to https://password.yourdomain.com (the hostname you previously set). If all is set then you should be able to see the PassCore tool show up in your browser.

NOTE: If you have a previous version, you can not use the same appsettings.json file. Please update your settings manually editing the new file.

PowerShell Installer

Use PowerShell to download and setup Passcore using the following command line, just make sure you have installed the .NET Core 5.0.1 Windows Server Hosting bundle and enabled World Wide Web publishing service:

Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/unosquare/passcore/master/Installer.ps1'))

Using the command shown above will install to the folder C:\passcore and using the HTTP Port 8080 with the default (localhost) binding.

If you want to customize your installation please download the installer script and the IIS setup script.

NOTE: You need PowerShell version 5 or better to execute the script.

Linux

We recommend use the docker image and redirect the traffic to nginx.

Docker

You can use the Alpine Docker Builder image and then copy the assets over to an Alpine container. You can pass environment attributes directly into docker without modifying the appsettings.json

docker build --rm -t passcore .
docker run \
-e AppSettings__LdapHostnames__0='ad001.example.com' \
-e AppSettings__LdapHostnames__1='ad002.example.com' \
-e AppSettings__LdapPort='636' \
-e AppSettings__LdapUsername='CN=First Last,OU=Users,DC=example,DC=com' \
-it \
-p 80:80 \
passcore:latest

NOTE: Docker image contains a build using the LDAP Provider (see below).

LDAP Provider

PassCore was created to use the Microsoft Active Directory Services provided by .NET Framework, but a new Provider using Novell LDAP Client can be used instead. This provider is the default when PassCore is running at Linux or macOS since Microsoft AD Services are NOT available.

The configuration of the LDAP Provider is slightly different. for example, the AutomaticContext is not available and you need to supply credentials.

WIP

Pwned Password Support

Sometimes a simple set of checks and some custom logic is enough to rule out non-secure trivial passwords. Those checks are always performed locally. There are, however, many more unsafe passwords that cannot be ruled out programatically. For those cases there are no simple set of rules that could be used to check those passwords that should never be used: You either need a local DB with a list of banned passwords or use an external API service.

Here is where Pwned Password API comes into play. Pwned Passwords are more than half a billion passwords which have previously been exposed in different data breaches along the years. The use of this service is free and secure. You can read more about this service in Pwned Passwords overview

Customization and Configuration

All server-side settings and client-side settings are stored in the /appsettings.json file. The most relevant configuration entries are shown below. Make sure you make your changes to the appsettings.json file using a regular text editor like Visual Studio Code

Running as a sub-application

To run as a sub-application you need to modify the base href="https://github.com/unosquare/passcore/blob/master/" value in the wwwroot/index.html file to be the base URL for PassCore. For example you might have PassCore setup at /PassCore so you would put

<base href="https://github.com/unosquare/passcore/blob/master/PassCore/" />

Troubleshooting

LDAP Support

License

PassCore is open source software and MIT licensed. Please star this project if you like it.

passcorepro

PassCore is free and will continue to be free forever. However, you can access a complete, brand new version with new features and tools.

Introducing passcorepro. This new, enhanced version of our self-service password manager comes with new features such as:

Go to our store and download a free trial: https://store.unosquare.com/PasscorePro