Client certificate authentication middleware for Laravel 5
Also known as X.509 client authentication.
How does it work
- You have a user in your app. For example,
Admin:admin@yourapp.tld
- You generate a certificate for that user. Make sure you're using
admin@yourapp.tld
for certificate'semailAddress
field. - This package allows
Admin
to use your app without ever logging in. - All users including
Admin
can still use plain password auth.
Pro tip: you can also use any other certificate attributes for authentication, not only
emailAddress
(likeid
orusername
). I don't think you need this package in that case, but anyway 🤷.
Prerequisites
Please don't blindly copy-paste the commands. It's important for you to know what you're doing.
1. Generate CA and Client certificate
Generating Certificate Authority:
openssl genrsa -out ca.key 2048
openssl req -new -x509 -days 3650 -key ca.key -out ca.crt
Generating client certificate and signing it with your CA. When asked for the email, enter email of your app's user which will be autheticated with this certificate.
openssl req -new -utf8 -nameopt multiline,utf8 -newkey rsa:2048 -nodes -keyout client.key -out client.csr
openssl x509 -req -days 3650 -in client.csr -CA ca.crt -CAkey ca.key -set_serial 01 -out client.crt
Optionally, generate a PKCS certificate to be installed into the browser, mobile or whatever:
openssl pkcs12 -export -clcerts -in client.crt -inkey client.key -out client.p12
2. Configure your web-server
This example is for NGINX with FastCGI.
server {
...
ssl_client_certificate /etc/nginx/certs/Your_CA_Public_Key.crt;
ssl_verify_client optional;
location ~ \.php$ {
...
fastcgi_param SSL_CLIENT_VERIFY $ssl_client_verify;
fastcgi_param SSL_CLIENT_S_DN $ssl_client_s_dn;
}
}
You can also add pass some other useful params, see resources below.
Resources
Installation
1. Install the package
This assumes that you have composer installed globally:
composer require ingria/laravel-x509-auth
2. Register middleware
Add \Ingria\LaravelX509Auth\Middleware\AuthenticateWithClientCertificate::class
to your routeMiddleware
array in app/Http/Kernel.php
.
For example, you can call it auth.x509
, by analogy with Laravel's auth.basic
name:
// app/Http/Kernel.php
...
protected $routeMiddleware = [
// a whole bunch of middlewares...
'auth.x509' => \Ingria\LaravelX509Auth\Middleware\AuthenticateWithClientCertificate::class,
];
Resources
Usage
Just add the middleware's name to any route or controller instead of default auth
. For example:
// routes/web.php
Route::get('/', 'YourController@method')->middleware('auth.x509');
Resources
License
The MIT License (MIT). Please see License File for more information.