defaultvalue/passcore repository overview

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

• Overview⁠
  • Features⁠
• Docker⁠
• LDAP Provider⁠
• Pwned Password Support⁠
• Customization and Configuration⁠
  • Running as a sub application⁠
• LDAP Support⁠

⁠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.

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

⁠Features

PassCore has the following features:

• Easily localizable (i.e. you can customize all of the strings in the UI -- see the section on Customization)

• Supports reCAPTCHA⁠

• Has a built-in password meter

• Has a password generator

• Has a server-side password entropy meter

• Responsive design that works on mobiles, tablets, and desktops.

• Works with Windows/Linux servers.

⁠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

⁠Additional Environment Variables

AppSettings__LdapUsername - Set the username or distinguish name (DN) to bind the LDAP server

AppSettings__LdapPassword - Set the password for the username

ClientSettings__Recaptcha__SiteKey - ReCAPTCHA public key: replace this! or leave empty if you don't need ReCAPTCHA

ClientSettings__Recaptcha__PrivateKey - ReCAPTCHA private key: replace this! or leave empty if you don't need ReCAPTCHA

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.

⁠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⁠

• To enable reCAPTCHA
  1. Find the PrivateKey entry and enter your private key within double quotes (")
  2. Find the SiteKey entry and enter your Site Key within double quotes (")
• To change the language of the reCAPTCHA widget
  • Find the LanguageCode entry and enter one of the options listed here⁠. By default this is set to en
• To enable/disable the password meter
  • Find the ShowPasswordMeter entry and set it to true or false (without quotes)
• To enable enable/disable the password generator
  • Find the UsePasswordGeneration entry and set it to true or false (without quotes)
  • Find the PasswordEntropy entry and set it to a numeric value (without quotes) to set the entropy of the generated password
• To enable server-side password entropy meter
  • Find the MinimumScore entry and set it to a numeric value (without quotes) between 1 and 4, where 1 is a bit secure and 4 is the most secure. Set to 0, for deactivate the validation.
• To enable restricted group checking
  1. Find the RestrictedADGroups entry and add any groups that are sensitive. Accounts in these groups (directly or inherited) will not be able to change their password.
• Find the DefaultDomain entry and set it to your default Active Directory domain. This should eliminate confusion about using e-mail domains / internal domain names. NOTE: if you are using a subdomain, and you have errors, please try using your top-level domain.
• To provide an optional parameter to the URL to set the username text box automatically
  1. http://mypasscore.com/?userName=someusername
  2. This helps the user in case they forgot their username and, also comes in handy when sending a link to the application or having it embedded into another application where the user is already signed in.
• To specify which (DC) attribute is used to search for the specific user.
  • With the IdTypeForUser it is possible to select one of six Attributes that will be used to search for the specifiv user.
  • The possible values are:
    • DistinguishedName or DN
    • GloballyUniqueIdentifier or GUID
    • Name
    • SamAccountName or SAM
    • SecurityIdentifier or SID
    • UserPrincipalName or UPN
• The rest of the configuration entries are all pretty much all UI strings. Change them to localize, or to brand this utility, to meet your needs.

⁠Running as a sub-application

To run as a sub-application you need to modify the base href="/" 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="/PassCore/" />

⁠LDAP Support

• If your users are having trouble changing passwords, try configuring the section PasswordChangeOptions in the /appsettings.json file. Here are some guidelines:
  1. Ensure UseAutomaticContext is set to false
  2. Ensure LdapUsername is set to an AD user with enough permissions to reset user passwords
  3. Ensure LdapPassword is set to the correct password for the admin user mentioned above
  4. User @gadams65 suggests the following: Use the FQDN of your LDAP host. Enter the LDAP username without any other prefix or suffix such as domain\\ or @domain. Only the username.
• You can also opt to use the Linux or macOS version of PassCore. This version includes a LDAP Provider based on Novell. The same provider can be used with Windows, you must build it by yourself.

GitHub⁠