Public | Automated Build

Last pushed: 4 months ago
Short Description
Short description is empty for this repo.
Full Description

docker-freeipa-pwd-portal

A turnkey self service Free IPA password portal ready for most deployment situations. The key features are:

  1. Externalized configuration through the /data volume, including auto-generation of basic Kerberos, JAAS, site, and log configuration files from the specified environment variables .
  2. The ability to either change an expiring password (if the password is known) or to reset password (if the password is not known).
  3. Password reset request emails using the email address configured for the account in the Free IPA instance and with configurable request timeouts.
  4. Optional ReCaptcha support.
  5. Auto-installation of the Free IPA instance's certificate, the keystore containing the password portal's certificate (or generation of a self-signed certificate and keystore if none is provided), and the password portal's keytab.

Quick Start

The command below will setup a freeipa-pwd-portal container with ReCaptcha disabled and a self-signed certificate:

docker run \
--name fpp \
-h freeipa-pwd-portal.example.com \
-p 443:443 \
-v /some/data/path:/data \
-e SMTP_HOST="smtp.example.com" \
-e SMTP_PORT="25" \
-e SMTP_FROM="freeipa-pwd-portal@example.com" \
-e FREEIPA_REALM="EXAMPLE.COM" \
-e FREEIPA_HOSTNAME="freeipa.example.com" \
-e FREEIPA_PWD_PORTAL_PRINCIPAL="host/freeipa-pwd-portal.example.com@EXAMPLE.COM" \
-e FREEIPA_SSL_CERT=/data/your_freeipa_instance_cert.cer \
-e KEYTAB=/data/your_pwd_portal_keytab \
xetusoss/freeipa-pwd-portal

Available Configuration Parameters

  • SMTP_HOST: The SMTP host to send notifications through. Default is "smtp.example.com".
  • SMTP_PORT: The port to use on the SMTP host. Default is "25".
  • SMTP_FROM: The address from which emails should be sent. Defaults to "freeipa-pwd-portal@examplecom".
  • SMTP_USER: The username to use for authenticating against the SMTP_HOST. If neither this nor SMTP_PASS are specified, SMTP AUTH is not used. If SMTP_USER is not specified but smtpPass is, SMTP_FROM will be attempted as the user name for the SMTP AUTH.
  • SMTP_PASS: The password for the SMTP_LOGIN address. If none is specified, will default to attempting to send the email without authentication.
  • FREEIPA_REALM: The Kerberos realm that users will be authenticating against. Defaults to "EXAMPLE.COM".
  • FREEIPA_HOSTNAME: The hostname for the Free IPA instance against which users will authenticate. Defaults to "freeipa.example.com".
  • FREEIPA_PWD_PORTAL_PRINCIPAL: The Kerberos principal name the password portal should use for administrative authentication against the Free IPA instance. For details on creating the Free IPA host account, please see the documentation for the freeipa-pwd-portal.
  • RECAPTCHA_PRIVATE_KEY: The recaptcha private key to use. ReCaptcha will be disabled for the site if none is supplied.
  • RECAPTCHA_PUBLIC_KEY: The recaptcha public key to use. ReCaptcha will be disabled for the site if none is supplied.
  • DISABLE_RECAPTCHA: Force disable ReCaptcha support. If either the RECAPTCHA_PRIVATE_KEY or _RECAPTCHA_PUBLIC_KEY options are ommitted, ReCaptcha support will be disabled regardless of the value for DISABLE_RECAPTCHA. Defaults to false.
  • PASSWORD_RESET_TIME_LIMIT: The time limit before which the generated link in password reset emails will expire in seconds. Defaults to 900 seconds (15 minutes).
  • FREEIPA_PWD_PORTAL_KEYSTORE: The java keystore containing the SSL certificate the password portal should use for serving HTTPS. If none is supplied, a self-signed SSL certificate will be generated in a newly generated keystore, and both will be used to serve HTTPS. This should be mounted somewhere in the /data volume mount prior to running the container.
  • FREEIPA_PWD_PORTAL_KEY_ALIAS: The alias for the SSL certificate in the supplied keystore.
  • FREEIPA_PWD_PORTAL_KEY_PASS: The password for both the supplied keystore and the contained SSL certificate (FREEIPA_PWD_PORTAL).
  • FREEIPA_SSL_CERT: The SSL certificate for the FreeIPA instance with which the password portal will be communicating. This will be added to the container's JRE keystore. This should be placed somewhere in the /data volume mount prior to running the container.
  • KEYTAB: The path within the Docker container to the valid password portal's Kerberos keytab. This should be placed somewhere in the /data volume mount prior to running the container referenced relative to the container, not the host. For details on creating the Free IPA host account, please see the documentation for the GitHub account.
  • X_FORWARDED_FOR_HEADER: The key for the request header from which to extract the remote user's IP, in the event the password portal is being served from behind a proxy. If no header is found, the value for request.getRemoteAddr() will be used instead (for Google Recpatcha). Defaults to "X-Forwarded-To".

Note that by default the web application will log to /var/log/freeipa-pwd-portal/application.log.

Examples

(1) Enabling Recaptcha:

docker run \
--name fpp \
-h freeipa-pwd-portal.example.com \
-p 443:443 \
-v /some/data/path:/data \
-e SMTP_HOST="smtp.example.com" \
-e SMTP_PORT="25" \
-e SMTP_FROM="freeipa-pwd-portal@example.com" \
-e FREEIPA_REALM="EXAMPLE.COM" \
-e FREEIPA_HOSTNAME="freeipa.example.com" \
-e FREEIPA_PWD_PORTAL_PRINCIPAL="host/freeipa-pwd-portal.example.com@EXAMPLE.COM" \
-e RECAPTCHA_PRIVATE_KEY="your_private_key" \
-e RECAPTCHA_PUBLIC_KEY="your_public_key" \
-e FREEIPA_SSL_CERT=/data/your_freeipa_instance_cert.cer \
-e KEYTAB=/data/your_pwd_portal_keytab \
xetusoss/freeipa-pwd-portal

(2) Supplying a valid password portal keystore containing the valid SSL certificate:

docker run \
--name fpp \
-h freeipa-pwd-portal.example.com \
-p 443:443 \
-v /some/data/path:/data \
-e SMTP_HOST="smtp.example.com" \
-e SMTP_PORT="25" \
-e SMTP_FROM="freeipa-pwd-portal@example.com" \
-e FREEIPA_REALM="EXAMPLE.COM" \
-e FREEIPA_HOSTNAME="freeipa.example.com" \
-e FREEIPA_PWD_PORTAL_PRINCIPAL="host/freeipa-pwd-portal.example.com@EXAMPLE.COM" \
-e FREEIPA_SSL_CERT=/data/your_freeipa_instance_cert.cer \
-e FREEIPA_PWD_PORTAL_KEYSTORE=/data/private.keystore \
-e FREEIPA_PWD_PORTAL_KEY_PASS=somepass \
-e FREEIPA_PWD_PORTAL_KEY_ALIAS="freeipa-pwd-portal" \
-e KEYTAB=/data/your_pwd_portal_keytab \
xetusoss/freeipa-pwd-portal

Authentication Stories

The freeipa-pwd-portal offers two main user stories:

  1. Password Change (when the user still knows their password)

    In the case of a password change, the user is authenticated using their supplied password. At minimum the FREEIPA_REALM, FREEIPA_HOSTNAME, and FREEIPA_SSL_CERT must be provided for this to behave as expected.

  2. Password Reset (when the user does not know their password or it has expired and needs to be changed administratively)

    In the case of a password reset, the password portal authenticates through it's FreeIPA HOST account (using an HTTP service for that host) using a Kerberos keytab, retrieves the user's information and generates a password reset email with a secure link back to the portal that will allow the user to reset their password. The email is sent to the email address associated with the supplied uid in the Free IPA instance.

    Once the user follows the generated link, the password portal uses its administrative access to change the password to a generated value and then immediately changes the password (as the user) to the supplied password. In addition to the above the SMTP_HOST, SMTP_PORT, SMTP_FROM_ADDRESS, FREEIPA_PWD_PORTAL_PRINCIPAL, and KEYTAB must additionally be specified for this to behave as expected. Please see the documentation for the freeipa-pwd-portal for information on creating the HOST account, HTTP service and keytab.

Docker Pull Command
Owner
xetusoss

Comments (0)