PyPass - Active Directory Password Reset Service

PyPass is a simple self-service password change web app for Active Directory. It is built with Python, Flask, LDAP3, and a lightweight UI.

Features

• Self-service password reset for AD users
• reCAPTCHA support
• Responsive UI for mobile and desktop
• Optional Slack notifications
• LDAP connectivity status badge (top-right)
• UI renders even if LDAP is offline (badge turns red)

Requirements

• Python 3.12
• LDAP server reachable on port 636 (LDAPS)

Quick start (local)

python3.12 -m venv .venv
.venv/bin/pip install -r app/requirements.txt
PYTHONPATH=app .venv/bin/flask --app app run --host 0.0.0.0 --port 5001

Open http://127.0.0.1:5001

Configuration

All settings live in app/src/config.json. Edit the values to match your AD environment.

{
  "SECRET_KEY_FLASK": "werewtrwetewrwer53535353",
  "SLACK_BOT_TOKEN": "xoxb-",
  "domain": "domain.com",
  "BASEDN": "OU=Users,dc=domain,dc=com",
  "user_admin": "admin-user",
  "passwd_admin": "password_admin",
  "slack_db": "slack_db.json",
  "Slack_Activation": "False",
  "debug": "True",
  "company": "DIGITALEBRAIN",
  "RECAPTCHA_PUBLIC_KEY": "GOOGLE CODE",
  "RECAPTCHA_PRIVATE_KEY": "GOOGLE CODE",
  "CRT_CERTIFICATE": "name.crt",
  "KEY_CERTIFICATE": "name.key"
}

Generate a Flask secret key

python3.12 - <<'PY'
import secrets
print(secrets.token_hex(16))
PY

LDAP status badge

The UI shows a green/red indicator based on /health/ldap, which attempts a TCP connect to the configured LDAP host on port 636. The page still loads if LDAP is offline, so you can verify the UI and config without a live LDAP connection. When LDAP is available, the badge turns green.

reCAPTCHA setup

PyPass uses Google reCAPTCHA via Flask-WTF.

1. Create keys at https://www.google.com/recaptcha/admin/create
2. Use the site key and secret key in app/src/config.json:

"RECAPTCHA_PUBLIC_KEY": "YOUR_SITE_KEY",
"RECAPTCHA_PRIVATE_KEY": "YOUR_SECRET_KEY",
"RECAPTCHA_ENABLED": "True"

If you want to disable reCAPTCHA, set RECAPTCHA_ENABLED to False.

LDAP setup guide

To enable LDAP/LDAPS connectivity from any LDAP server, confirm the items below:

1. LDAPS endpoint

• Ensure the LDAP server supports LDAPS on port 636.
• Open firewall rules to allow inbound 636 from the app host.
• If you must use LDAP (389), update the code to use port 389 and disable SSL (not recommended).

2. Certificates (LDAPS)

• The LDAP server must present a valid certificate.
• If you use an internal CA, add the CA certificate to the OS trust store on the app host.

3. Service account

• Create an LDAP user/service account with permission to read user attributes and change passwords.
• In Active Directory, the account must be allowed to reset passwords for the target OU.

4. Config values

• domain: LDAP hostname or IP (e.g., ldap.example.com)
• BASEDN: Base DN for users (e.g., OU=Users,DC=example,DC=com)
• user_admin / passwd_admin: service account credentials

5. Connectivity tests (optional)

• Test TLS handshake:

  openssl s_client -connect ldap.example.com:636

• Test LDAP bind (if you have ldapsearch):

  ldapsearch -H ldaps://ldap.example.com:636 -D "user@example.com" -W -b "OU=Users,DC=example,DC=com"

If LDAP is unreachable, the app will still render and show a warning message, and the status badge turns red.

Slack setup

To enable Slack notifications:

1. Set SLACK_BOT_TOKEN and Slack_Activation to True in the config.
2. Export your Slack user list and save it in app/src/:

import json
from slack_sdk import WebClient

SLACK_BOT_TOKEN = "xoxb-YOUR-TOKEN"
sc = WebClient(token=SLACK_BOT_TOKEN)
response = sc.users_list()
data = json.dumps(response.data, indent=4, sort_keys=True)
print(data)

python3.12 slack_file.py >> app/src/slack_db.json

Docker

docker build -t pypass:latest .
docker run --dns <dns-or-ad-ip> --name pypass -d -p 80:5000 --rm pypass:latest

Kubernetes (example)

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pypass
spec:
  replicas: 1
  selector:
    matchLabels:
      app: pypass
  template:
    metadata:
      labels:
        app: pypass
    spec:
      containers:
        - name: pypass
          image: pypass:latest
          ports:
            - containerPort: 5000
          env:
            - name: PYTHONPATH
              value: "/app"
          volumeMounts:
            - name: config
              mountPath: /app/src/config.json
              subPath: config.json
      volumes:
        - name: config
          configMap:
            name: pypass-config
---
apiVersion: v1
kind: Service
metadata:
  name: pypass
spec:
  selector:
    app: pypass
  ports:
    - port: 80
      targetPort: 5000

Create a ConfigMap named pypass-config with your config.json before applying the manifest.

Troubleshooting

• If LDAP is unreachable, the app shows a warning message and the status badge turns red.
• For LDAPS on Windows, ensure certificate services are installed on the domain controller.

License

MIT. See LICENSE.