README

This symfony user provider reads user from the htpasswd file.

To use the a htpasswd file you need to execute following three steps:

1. Run composer to install the bundle,
2. configure your security configuration and
3. create a htpasswd password storage file.

All available password formats of the basic authentication are supported: apr1-md5, bcrypt, crypt, sha1 and plain text - see http://httpd.apache.org/docs/current/misc/password_encryptions.html.

Table of Contents

• Requirements
• Integration & Basic Usage
  • Installation
  • Symfony Configuration
  • Add Htpasswd File
• Advanced Usage & Configuration
  • Change Location of Your Htpasswd File
  • Change Default User Roles
  • User Roles Inside Htpasswd File
• Credits

Requirements

The usage of PHP ≥ v8.0.2 and Symfony ≥ 6 is recommend.

Integration & Basic Usage

Installation

Please install via composer.

composer require prokki/htpasswd

The bundle will be automatically added to your bundles.yaml configuration.

Symfony v4, Symfony v5

PHP v7.2 and Symfony 4 is obligatory.

To use an older version of Symfony/PHP please use version 0.*

composer require prokki/htpasswd "~0.0"

Symfony Configuration

To enable the functionality you have to change your security configuration manually.

1. Enable the provider HtpasswdUserProvider and the encoder HtpasswdEncoder in your security configuraton, i.e. in your %kernel.project_dir%/config/security.yaml file.
2. To enable http basic authentication add the http_basic authentication method to the firewall configuration.
3. Additionally be sure to enable access_control for at least one path.

security.yaml:

security:

  # 1.a) add the HtpasswdUserProvider as a new provider (the name does not matter)
  providers:
    bz_map_cycle_provider:
      id: Htpasswd\Security\HtpasswdUserProvider

  # 1.b) and add the HtpasswdEncoder as a new encoder (the name does not matter)
  encoders:
    Symfony\Component\Security\Core\User\User:
      id: Htpasswd\Security\HtpasswdEncoder

  # 2. enable basic authentication
  firewalls:
    main:
      http_basic: ~
      
  # 3. be sure to add one path
  access_control:
    - { path: ^/, roles: ROLE_USER }

Feel free to use the full flexibility of the Symfoniy security layer which means i.e. you can

• chain firewalls,
• add other providers and encoders,
• restrict basic authentication to certain paths only
• etc.

Add Htpasswd File

Create your custom htpasswd file using the htpasswd command in the project directory of your project.

Hint: Usually the command is installed automatically if you run an apache web server, i.e. if you use xampp or your package management system. On linux systems the command is mostly provided by the package apache2-utils.

Create a htpasswd file in your project directory. Call the following command and type in your password:

htpasswd -cB .htpasswd admin

A new file was created in your project:

%kernel.project_dir%/
  - config/
    - packages/
      - security.yaml   <-- do not forget to change your configuration
    - bundles.yaml
    - services.yaml
  - src/
    - Controller/
    - Entity/
    - Service/
    - [...]
  - tests/
  - composer.json
  - .htpasswd           <-- new htpasswd file in your project directory

⚠️ For safety reasons we suggest to not include the htpasswd file in your repository!

Advanced Usage & Configuration

You are not really able to change the configuration of the bundle, but at least you can customize the location of your htpasswd file and the default user roles.

In both cases you have to create a new configuratio file htpasswd.yaml for the bundle:

%kernel.project_dir%/
  - config/
    - packages/
      - security.yaml
      - htpasswd.yaml   <-- custom configuration file

The default content of the file should look like following. If you just insert these configuration, the bundle works with default settings.

htpasswd:
  path: ~       # the path of your htpasswd file, ie. "%kernel.project_dir%/public/passwords.txt" 
  roles: ~      # the default roles of each basic auth user

Change Location of Your Htpasswd File

It is possible to change the default location by changing the path variable.

This is useful if you use your htpasswd file in other projects or if you set up a basic authentication additionally via your apache2 configuration.

htpasswd:
  path: "/etc/apache2/.htpasswd" 
  roles: ~

Change Default User Roles

The default user role assigned to each user (included by the HtpasswdUserProvider) is ROLE_USER. To change the default user roles, adapt the roles variable in the configuration:

htpasswd:
  path: ~ 
  roles: ["ROLE_ADMIN", "ROLE_ALLOW_WRITE", ...]

If you change the roles config parameter, be sure to include all roles which are necessary. There is no process to add another default user role.

Additionally please take care, that the roles

1. follow the recommendations of symfony user roles and
2. match the access_control settings in your security.yaml file.

User Roles Inside Htpasswd File

The implementation of the basic authentication allows you to add user roles at the end of each line in the htpasswd file.

Similar to overwriting the user roles by configuration, be sure to

1. follow the recommendations of symfony user roles and
2. match the access_control settings in your security.yaml file.

The user roles are a comma-separated list which are separated from the origin line by a colon. Example:

user:$2y$05$G0q46R6tXNYmGnwHK74hyuUsz.IlCoVoOlMLjuLdgi.hWvwuqAr8G:ROLES_A,ROLES_B,ROLES_C

⚠️ This feature is probably not supported by all platforms!

Content of a well-structured htpasswd file:

# encoded by bcrypt, pass: admin1
admin1:$apr1$j0jl5669$vMiAX1Dxz4li8GACC0bJ1/

# encoded by apr1-md5, pass: admin2
admin2:$2y$05$.im1AvKvAVUTl6rlbY8ycu8iz6Q3.BhMsrZVVZb.agFCQ0u1aTzKa

# encoded by crypt, pass: admin3
admin3:WArkJFYVv3SDU

# encoded by sha1, pass: admin4
admin4:{SHA}6gU9Eaiq0cz4wY+SQbrrnsR+XWQ=

# not encoded / plain text
admin5:admin5

Content of a htpasswd file with additional user roles:

# encoded by bcrypt, pass: admin1, user roles ROLE_USER and ROLE_ADMIN
admin1:$apr1$j0jl5669$vMiAX1Dxz4li8GACC0bJ1/:ROLE_USER,ROLE_ADMIN

# encoded by apr1-md5, pass: admin2, user roles ROLE_USER and ROLE_SUPERVISOR
admin2:$2y$05$.im1AvKvAVUTl6rlbY8ycu8iz6Q3.BhMsrZVVZb.agFCQ0u1aTzKa:ROLE_USER,ROLE_SUPERVISOR

# encoded by crypt, pass: admin3, user roles ROLE_READ_ONLY
admin3:WArkJFYVv3SDU:ROLE_READ_ONLY

# encoded by sha1, pass: admin4, user roles ROLE_USER and ROLE_ADMIN
admin4:{SHA}6gU9Eaiq0cz4wY+SQbrrnsR+XWQ=:ROLE_USER,ROLE_ADMIN

# not encoded / plain text
admin5:admin5

Credits

A big thank you to https://github.com/whitehat101 for the implementation of the apr1-md5 algorithm.