zim32/cert-auth-bundle

Two-factor x509 certificate authentication

Symfony2-CertAuthBundle

Integrate two-factor certificate authentication in you project., _(*1)

With this bundle it is possible to easily integrate two-factor x509 based browser authentication into your project., _(*2)

Basic features: - Tightly integrated into Symfony2 firewall system (less code more security) - Integrate it on top of any authentication method - http-basic, form-login, pre-auth etc... - Automatic x509 certificate generation, storage and restoring - Pluggable certificate storage system based on Persisters, Filters and Formatters (store your certificates the way you like) - Flexible access rules: store ip, email or any custom field into client certificate and then filter by Symfony Expression Language - Outstanding security for your customers: hacker must store user certificate, know his credentials and event then it is almost impossible to login if you will deny access by ip stored in certificate - Since x509 ValidFrom and ValidTo fields are automatically validated by nginx or any similar server, it will automatically reduce probability of inactive accounts being your headache, _(*3)

How it works?

• User is logged in as usual
• User is redirected to DENY page
• User enters his secure word and click generate certificate
• Generated certificate is stored on server (localfs, db, {your_custom_storage})
• User downloads certificate and installs it into the browser
• User refreshes page and get into admin interface
• Your frontend server stack validates user certificate and pass several SERVER variables to backend
• Bundle checks this variables to grant or deny access

What if user go to another computer?

• User is logged in as usual
• System detects that he has certificate locally
• User is redirected to RESTORE page
• User enters his secure word and download certificate again

Certificates are protected by password and even your admin can not view it's content., _(*4)

Contents

Installationbr/ Configuration referencebr/ Customizebr/ Disable automatic certificate recovery
Run Testsbr/ Using Command Linebr/ How to add custom fieldsbr/ br/, _(*5)

Installation

Download via composer, _(*6)

composer require zim32/cert-auth-bundle

Add bundle to your Kernel, _(*7)

# app/AppKernel.php
$bundles = array(
...
    new Zim\CertAuthBundle\ZimCertAuthBundle(),
...
 );

Import routes, _(*8)

# app/config/routing.yml
zim_cert_auth:
    resource: "@ZimCertAuthBundle/Resources/config/routing.yml"
    prefix:   /cert

Generate CA certificate (if you don't have one), _(*9)

mkdir /{your_app_root}/cert
cd /{your_app_root}/cert
openssl genrsa -des3 -out private.pem 4096
openssl req -new -x509 -key private.pem -out CA.crt -days 365
chmod a-rwx * && chmod u+r *

Modify nginx config. Add lines in your server section:, _(*10)

# /etc/nginx/sites-available/yoursite.conf
server {
...
ssl_verify_client optional;
ssl_trusted_certificate /{your_app_root}/cert/CA.crt;
...
}

Depenging on version of nginx you should add ssl_client_certificate /{your_app_root}/cert/CA.crt; instead of ssl_trusted_certificate, but this is not recommended option, consider updating your nginx server., _(*11)

Modify your openssl config file, _(*12)

This bundle uses custom openssl extension section called zim_usr_cert to prevent different conflicts with your existing configurations. So add this to the end of your openss config file (on Debian /etc/ssl/openssl.cnf):, _(*13)

[zim_usr_cert]
basicConstraints=critical,CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

For PHP-FPM use:, _(*14)

fastcgi_param   CLIENT_CERT         $ssl_client_raw_cert;
fastcgi_param   CLIENT_CERT_OK      $ssl_client_verify;

For proxy pass use:, _(*15)

proxy_set_header    CLIENT_CERT         $ssl_client_raw_cert;
proxy_set_header    CLIENT_CERT_OK      $ssl_client_verify;

Add directory to store generated client's certificates, _(*16)

mkdir /{your_app_root}/cert/clients

Add bundle configuration, _(*17)

# app/config/config.yml
...
zim_cert_auth:
    ca_path: %kernel.root_dir%/cert/CA.crt
    ca_key_path: %kernel.root_dir%/cert/private.pem
    ca_key_password: my_des3_password
    client_csr_options:
        countryName: UA
        organizationName: YOUR ORGANIZATION NAME Limited
    cert_content_server_var: CLIENT_CERT
    cert_storage_formatter:
        id: zim_cert_auth.certificate_storage.formatter.pkcs12
        options: []
    cert_storage_persister:
        id: zim_cert_auth.certificate_storage.persister.localfs
        options:
            rootDir: %kernel.root_dir%/cert/clients

Modify security config, _(*18)

# app/config/security.yml
firewalls:
    firewallname:
        ...
        pattern: ^/admin
        access_denied_handler: zim_cert_auth.access_denied_handler
        zim_cert: ~
        ...
    access_control:
        ...
        - { path: ^/cert/denied, role: IS_AUTHENTICATED_FULLY }
        - { path: ^/admin, allow_if: "'ROLE_ADMIN' in roles and 'ROLE_CERT_AUTHENTICATED_FULLY' in roles" }

Configuration reference

See documentation, _(*19)

Customize

This bundle has four templates: - Resources/views/Denied/layout.html.twig - Resources/views/Denied/index.html.twig - Resources/views/Denied/restore.html.twig - Resources/views/Denied/blocked.html.twig, _(*20)

Override them using Symfony Override Templates technique to add f.e. instructions how to install certificate into the browser., _(*21)

Override Controller/AccessDeniedController if you need some custom logic., _(*22)

Change persister to store client certificates other way then localfs (f.e. in database)., _(*23)

Disable automatic certificate recovery

If you want to disable certificate automatic recovery, just add this to config.yml file:, _(*24)

zim_cert_auth:
    ...
    disable_cert_restore: true

Run Tests

cd /{your_project_root} && KERNEL_DIR=./app ./bin/phpunit vendor/zim32/cert-auth-bundle/Tests/

Using command line

You can dump client certificates and private keys using, _(*25)

app/console zim:cert:dump -p {secure_word} {identity}

You can remove certificate from storage, _(*26)

 app/console zim:cert:remove {identity}

How to add custom fields

Suppose you want to add ipAddress field to your client certificates equal to current client IP and then deny access based on this field. You should do several simple steps: - Find free OID in registry to prevent conflicts - Add custom OID to your openssl configuration file - Add event listener to add ipAddress field to client certificate - Add custom expression to validate this field, _(*27)

Step #1

For example you choose your company OID section to be 1.3.6.1.4.1.77777. So your ipAddress field OID should be something like 1.3.6.1.4.1.77777.1 Open your openssl config file, find [new_oids] section and add the following line, _(*28)

[new_oids]
...
ipAddress = 1.3.6.1.4.1.77777.1

Step #2

Add zim_cert.modify_csr event listener, _(*29)

app.listener_modify_csr:
    class: AppBundle\EventListener\ModifyCSREventListener
    arguments: [@request_stack]
    tags:
      - { name: kernel.event_listener, event: zim_cert.modify_csr, method: handle }

Step #3

Create event listener, _(*30)

<?php

namespace AppBundle\EventListener;

use Symfony\Component\HttpFoundation\RequestStack;
use Zim\CertAuthBundle\Event\ModifyClientCSREvent;

class ModifyCSREventListener
{

    protected $requestStack;

    public function __construct(RequestStack $requestStack)
    {
        $this->requestStack = $requestStack;
    }

    public function handle(ModifyClientCSREvent $event)
    {
        $event->dn['ipAddress'] = $this->requestStack->getCurrentRequest()->getClientIp();
    }

}

Step #4

From now on you are able to use Symfony Expression Language to deny access based on this field. Modify your config.yml:, _(*31)

zim_cert_auth:
    ...
    cert_validation_expression: cert["subject"]["CN"] == token.getUserName() && cert["subject"]["ipAddress"] == request.getClientIp() && request.server.get("CLIENT_CERT_OK") === "SUCCESS"

That's all., _(*32)