Skip to main content

Apache .htpasswd / .htgroup

Authenticate users with Apache-style password and group files.
MAPS can read and manage these files (create, update, delete users; add/remove group membership).

Configuration​

1) AuthManager (global)​

AuthManager:
  authenticationEnabled: true
  authorizationEnabled: false
  config:
    # Option A: Explicit file paths
    identityProvider: "apache"
    passwordFile: "{{MAPS_DATA}}/.security/htpasswd"
    groupFile: "{{MAPS_DATA}}/.security/htgroup"

    # Option B: Config directory containing htpasswd + htgroup
    # configDirectory: "{{MAPS_DATA}}/.security/apache"
  • Option A (direct paths) — point directly to your .htpasswd and .htgroup files.
  • Option B (configDirectory) — use a directory that contains both files (htpasswd and htgroup) in standard Apache format.

2) JAAS (jaasAuth.config)​

ApacheAuthConfig {
  io.mapsmessaging.security.jaas.ApacheLoginModule Required
    htpasswd="{{MAPS_DATA}}/.security/htpasswd"
    htgroup="{{MAPS_DATA}}/.security/htgroup"
    debug=false;
};

3) SecurityManager mapping​

SecurityManager:
  - apache: ApacheAuthConfig

4) Listener example​

- name: "AMQP via Apache"
  url: "tcp://0.0.0.0:5672/"
  protocol: amqp
  auth: apache

Managing users & groups​

MAPS supports full lifecycle management for .htpasswd / .htgroup:

  • Users
    • Create, update password (bcrypt/MD5/crypt depending on policy), delete
    • Disable/enable (by policy or removing from groups)
  • Groups
    • Create/delete groups
    • Add/remove users from groups

Changes are persisted to the configured htpasswd and htgroup files. Keep regular backups and enable audit logging in production.

Operational guidance​

  • Restrict file permissions to the MAPS service account (e.g., 0600).
  • Store files under {{MAPS_DATA}}/.security/ for easier backup/restore.
  • When running in containers, mount the directory as a read–write volume.
  • If you integrate with other systems that also edit these files, coordinate access to avoid conflicts.

Troubleshooting​

  • Auth succeeds but groups don’t apply: verify the htgroup path and membership lines.
  • Password changes don’t stick: check write permissions on htpasswd and container volume mounts.
  • Users can connect but shouldn’t: ensure the listener references the correct auth realm and you’ve removed the user from relevant groups.