Configuration

Pro Self-Hosted configuration — Email & SMTP, Authentication & SSO, and recovery options via Admin Settings.

This article applies to: Pro Self-Hosted

Configuration

All Pro Self-Hosted configuration is done in the Administration center: Admin → Settings. Each area (Email, Auth, Application, etc.) is a section in that single page. After you change settings and click Save Settings, the application restarts to apply them; allow 5–15 seconds for the restart.

This page covers:

  1. Email & SMTP — Outbound email for registration, password reset, and notifications
  2. Authentication & SSO — Single Sign-On with Microsoft Entra ID or other identity providers
  3. Disable “Require SSO for login?” — Recovery when SSO is misconfigured or unavailable
  4. File storage encryption — Default storage behavior and how to add encryption at rest for attached files

Email & SMTP

Password Pusher Pro uses SMTP to send email for account-related messages (e.g. registration, password reset, invitations) and other notifications. You configure SMTP in Admin → Settings → Email. Settings are applied only after you click Save Settings; the application restarts to load the new configuration and may take 5–15 seconds.

Where to configure email

  1. Sign in as an administrator.
  2. Open Admin → Settings and select the Email section.
  3. Enter your SMTP server details in Step 1, then click Save Settings at the bottom of the page.
  4. After the app has restarted, use Step 2 to send a test email and confirm delivery.

Save settings first. Test SMTP uses the saved configuration. If you change SMTP fields but do not save, the test will still use the previous values.

Raise Email Delivery Errors

When enabled, the application shows detailed error messages when email delivery fails. Leave this on when configuring or troubleshooting SMTP so you can see connection and authentication errors. You may turn it off in production if you prefer not to expose raw SMTP errors to users.

SMTP configuration (Step 1)

These settings define how the application connects to your mail server. Values are written to the environment and take effect only after you save and the application restarts.

Setting Description
SMTP Address Hostname of your SMTP server (e.g. smtp.gmail.com, smtp.sendgrid.net, or your corporate mail server).
SMTP Port Port used for the connection. Common values: 587 (submission with STARTTLS), 465 (SMTPS/SSL), 25 (plain SMTP, often restricted).
SMTP Domain Domain used for SMTP authentication (e.g. your sending domain or hostname). Some servers require this to match the server’s expectations.
SMTP Username Username for authenticating with the SMTP server (often your email address or a dedicated API user).
SMTP Password Password or app password for the SMTP user. Stored securely; use the show/hide control as needed.
Authentication Type Method used to authenticate: Login, Plain, or CRAM MD5. Most providers use Login or Plain; use the option recommended by your provider.
Enable STARTTLS Auto When enabled, the client will use STARTTLS when the server supports it (typical for port 587). Leave on unless your provider instructs otherwise.
SSL When enabled, connect using SSL/TLS from the start (typical for port 465). Use either SSL or STARTTLS, not both, depending on your server and port.

Typical combinations: Port 587 → Enable STARTTLS Auto, SSL off. Port 465 → Enable SSL. After changing any of these, click Save Settings and wait for the restart before testing.

Test SMTP (Step 2)

After saving your SMTP settings, use Test SMTP to send a real email and confirm delivery. Enter the recipient address and click Test SMTP. The test uses the saved configuration. For more help with delivery failures, see Troubleshooting Email.

Known working configurations (Email)

The same SMTP providers that work with the open-source edition work with Pro Self-Hosted. In Pro, set all values in Admin → Settings → Email (do not use environment variables or config files).

Provider SMTP Address Port Authentication Notes
Gmail smtp.gmail.com 587 Plain Use an application-specific password; enable 2-Step Verification first.
Microsoft 365 smtp.office365.com 587 Login (not Plain) Use Login or you may see “Authentication method not supported”.
SendGrid smtp.sendgrid.net 587 Plain Username: apikey (literally); password: your SendGrid API key.
Amazon SES email-smtp.<region>.amazonaws.com 587 Plain Use SES SMTP credentials; verify sender/domain in SES. See Amazon SES documentation.

Authentication & SSO

Single Sign-On (SSO) lets users sign in to Password Pusher Pro with your organization’s identity provider (IdP) instead of a local password. Pro Self-Hosted supports several providers; you configure each one in Admin → Settings → Auth and by creating an app (or client) in the IdP’s portal.

This section covers Microsoft Entra ID (Azure AD). Other providers (e.g. Google, Okta) are configured similarly in the Auth section.

Where to configure SSO

  1. Sign in as an administrator.
  2. Open Admin → Settings and go to the Auth section.
  3. Enter the Client ID, Client secret, and any provider-specific fields (e.g. Tenant ID for Microsoft) for the provider you want to enable.
  4. Save settings. The application will restart to apply changes.

The exact field names and values come from your IdP’s app registration. Below is how to set that up for Microsoft Entra ID.

Microsoft Entra ID (Azure AD)

To let users sign in with their Microsoft 365 or Entra ID accounts, you create an App registration in the Azure Portal and then paste the app’s Client ID, Client secret, and (for single-tenant) Tenant ID into Password Pusher.

1. Create an app registration

  1. In Azure Portal, go to Microsoft Entra ID (formerly Azure Active Directory).
  2. Select App registrations → New registration.
  3. Name: e.g. Password Pusher or Password Pusher Pro.
  4. Supported account types:
    • Accounts in this organizational directory only — Single-tenant; only your organization. You must provide the Tenant ID (or tenant domain) in Password Pusher.
    • Accounts in any organizational directory — Multi-tenant; leave Tenant ID blank in Password Pusher.
  5. Redirect URI: leave blank for now; you’ll add it in the next step.
  6. Click Register.

2. Add a Web redirect URI (required)

Password Pusher is a server-side web app and must use a Web redirect URI and a client secret. Do not register it as a “Single-page application” or “Public client,” or you may see errors such as AADSTS700025 (client is public; client secret must not be sent).

  1. In your app registration, open Authentication.
  2. Under Platform configurations, click Add a platform → Web.
  3. Redirect URI: https://<your-password-pusher-domain>/users/auth/microsoft_graph/callback Example: https://pwp.yourcompany.com/users/auth/microsoft_graph/callback
  4. Under Advanced settings, set Allow public client flows to No (so the app is treated as a confidential client).
  5. Click Configure.

3. Create a client secret

  1. In the app registration, open Certificates & secrets.
  2. Client secrets → New client secret.
  3. Add a description (e.g. Password Pusher Pro) and choose an expiry.
  4. Click Add, then copy the Value immediately (it is shown only once). This is the Client secret you will paste into Password Pusher.

4. Note Application (client) ID and Directory (tenant) ID

  1. On the app registration Overview page, copy:
    • Application (client) ID → this is the Client ID in Password Pusher.
    • Directory (tenant) ID → needed only for single-tenant apps; enter this (or your tenant domain, e.g. contoso.onmicrosoft.com) in the Tenant ID field in Password Pusher. Leave Tenant ID blank for multi-tenant apps.

5. Enter values in Password Pusher

  1. In Password Pusher Pro: Admin → Settings → Auth.
  2. In the Microsoft section:
    • Client ID: paste the Application (client) ID.
    • Client secret: paste the client secret value.
    • Tenant ID (optional):
      • Single-tenant app: enter your Directory (tenant) ID (a GUID) or your tenant domain (e.g. contoso.onmicrosoft.com or a custom verified domain like contoso.com). If you omit this for a single-tenant app, sign-in may fail with an error about the app not being multi-tenant.
      • Multi-tenant app: leave blank.
  3. Save. The app will restart.

SSO troubleshooting

Error or behavior What to do
AADSTS50194 — “Application is not configured as a multi-tenant application” / “Use a tenant-specific endpoint” Your app is single-tenant. In Password Pusher, set Tenant ID to your Directory (tenant) ID or tenant domain (e.g. contoso.onmicrosoft.com).
AADSTS700025 — “Client is public so neither client_assertion nor client_secret should be presented” The app is registered as a public client. In Azure, under Authentication, add a Web platform with your redirect URI and set Allow public client flows to No. Ensure you are not using “Single-page application” or “Mobile and desktop” as the only platform.
Sign-in works but then fails with a message about email domain Ensure user accounts in Entra ID have an email (or the mail attribute) set if your organization requires it for account creation.

Disable “Require SSO for login?”

If you have enabled the Require SSO for login? setting and need to disable it (e.g., SSO misconfiguration, emergency access, or recovery scenarios), you can use this command-line utility.

Require SSO for login setting

When to use this

  • SSO is misconfigured — Your SSO provider is not working correctly and users cannot log in
  • Emergency access needed — You need to access the system but SSO is unavailable
  • Recovery scenarios — You’re recovering from a backup or migration and need to reconfigure SSO
  • Testing — You want to temporarily disable SSO requirements for testing

Running the command

Execute the following from the folder containing docker-compose.yml:

docker compose exec pwpush-pro bin/disable_require_sso_login

Re-enabling SSO requirements

To re-enable SSO requirements after using this utility:

  1. Log in to your Self-hosted Password Pusher Pro instance
  2. Go to Admin → Settings and open the Auth section (/admin/settings?active_section=auth)
  3. Enable the Require SSO for login? setting

Warning: Disabling SSO requirements allows all users to log in with email/password. Re-enable SSO requirements once your SSO provider is properly configured.

File storage encryption

Pro Self-Hosted ships with a default Docker volume. This volume is the persistent local storage for the application. In it, the application stores:

  1. Application-related temporary files
  2. SQLite3 database (if not using Enterprise Edition with PostgreSQL)
  3. File uploads (when local storage is selected)

In the Administration Center (Admin → Settings), you can choose where file attachments are stored: local disk (this volume) or cloud storage (e.g. S3, Azure Blob).

For the full security picture of file uploads (obfuscated storage, temporary download links, deletion on expiration), see Security — File Uploads.

This section explains options for encrypting the local Docker volume so that this data is protected at rest.

When you deploy with the standard install instructions, your docker-compose.yml uses a named volume for that storage:

services:
  pwpush-pro:
    image: [registry]/pwpush-pro-advanced:latest
    env_file:
      - .env
    volumes:
      - pwpush-pro-data:/opt/PasswordPusher/storage
    ports:
      - "80:80"
      - "443:443"
    restart: unless-stopped

volumes:
  pwpush-pro-data:
    driver: local

Default: standard Docker volume

With this setup, the volume uses the local driver. Docker does not encrypt it. Whether data is encrypted at rest depends on the host:

  • Full-disk or partition encryption (e.g. LUKS) — If the host’s file system is already encrypted, everything written to that disk (including Docker volumes) is encrypted at rest. No change to docker-compose.yml is required.
  • Unencrypted host — If the host disk is not encrypted, file attachments are stored unencrypted on that volume.

Alternatively, you can configure cloud storage in the application (see Option 3 below). Many cloud providers offer encryption at rest by default (e.g. Amazon S3), so using a cloud backend can be a simple way to get encrypted file storage without managing volumes or host encryption.

Adding encryption for the local Docker volume

If your host is not fully encrypted and you want this volume to be encrypted at rest, you can do one of the following before starting the stack for the first time (so the app writes directly into the encrypted location).

Note: If you decide to encrypt the volume after the first boot, you may need to migrate existing files into the new encrypted location, depending on the option you choose.

Option 1: Bind mount to an encrypted directory

Create an encrypted filesystem on the host (e.g. with LUKS or a user-space option like gocryptfs), mount it at a path such as /var/lib/pwpush-pro-storage, and use that path as a bind mount instead of the named volume.

In docker-compose.yml, replace the volume mapping and remove the named volume definition:

services:
  pwpush-pro:
    image: registry.apnotic.com/pwpush-pro-advanced:latest
    env_file:
      - .env
    volumes:
      - /var/lib/pwpush-pro-storage:/opt/PasswordPusher/storage
    # ... rest unchanged

You are responsible for creating, formatting, and mounting the encrypted filesystem and for unlocking it at boot (e.g. via init scripts or systemd).

Option 2: Volume driver plugin

Use a Docker volume driver that supports encryption (e.g. Portworx), create an encrypted volume with that driver, and reference it in your Compose file. Configuration is specific to the plugin and your environment; see the plugin’s documentation.

Option 3: Cloud storage (application configuration)

Instead of using the default Docker volume, you can configure the application to store file uploads in a cloud storage backend (e.g. AWS S3, Google Cloud Storage, Azure Blob Storage). Many of these providers encrypt data at rest by default—for example, Amazon S3 uses server-side encryption (SSE-S3) for all objects with no extra configuration.

Configure your chosen backend in Admin → Settings; see the application and provider documentation for details. This option keeps file uploads off the host disk entirely and often satisfies encryption-at-rest requirements with minimal setup.

Summary

Scenario Encryption at rest for file storage
Default Docker volume on an encrypted host (e.g. LUKS) Yes — host provides it
Default Docker volume on an unencrypted host No
Cloud storage (S3, GCS, Azure Blob, etc.) Yes — many providers encrypt at rest by default
Bind mount to an encrypted directory on the host Yes — you provide and manage it
Volume from an encryption-capable driver (e.g. Portworx) Depends on plugin and configuration

See also