Two-factor authentication on the site using a USB token. Now for Linux

  • Tutorial

In one of our previous articles, we talked about the importance of two-factor authentication on company corporate portals. Last time, we demonstrated how to configure secure authentication in the IIS web server.

In the comments, we were asked to write instructions for the most common web servers for Linux - nginx and Apache.

You asked - we wrote.

What do you need to get started?

  • Any modern Linux distribution. I did a test setup on MX Linux 18.2_x64. This is certainly not a server distribution, but there are hardly any differences for Debian. For other distributions, the paths to libraries / configs may slightly vary.
  • Token. We continue to use the PKI Rutoken EDS model , which is ideally suited for high-speed performance for corporate applications.
  • To work with the token on Linux, you need to install the following packages:
    libccid libpcsclite1 pcscd pcsc-tools opensc

Certificate writing

In previous articles, we relied on the fact that server and client certificates will be issued using Microsoft CA. But since we are configuring everything in Linux, at the same time we will talk about an alternative way to issue these certificates - without leaving Linux.
As a CA we will use XCA ( ), which is available in any modern Linux distribution. All the actions that we will perform in XCA can also be done in command line mode using the OpenSSL and pkcs11-tool utilities, but for the sake of simplicity and clarity, we will not give them in this article.

Beginning of work

  1. Install:

    $ apt-get install xca
  2. And run:

    $ xca
  3. We create our database for CA - /root/CA.xdb
    We recommend that you store the Certificate Authority database in a folder where only the administrator has access. This is important to protect the private keys of root certificates, which are used to sign all other certificates.

Create keys and root CA certificate

The public key infrastructure (PKI) is based on a hierarchical system. Central to this system is the root certification authority or root CA. His certificate must be created first.

  1. We create the RSA-2048 private key for CA. To do this, on the Private Keys tab, click New Key and select the appropriate type.
  2. Set a name for the new key pair. I called it - CA Key.
  3. We write out the CA certificate itself, using the created key pair. To do this, go to the Certificates tab and click New Certificate .
  4. Be sure to choose SHA-256 , because using SHA-1 can no longer be considered safe.
  5. As a template is required to select the [default] CA . Do not forget to click Apply all , otherwise the template does not apply.
  6. On the Subject tab, select our key pair. There you can fill out all the main fields of the certificate.

Create keys and https server certificate

  1. Similarly, we create the RSA-2048 private key for the server, I called it - Server Key.
  2. When creating the certificate, we select that the server certificate must be signed on the CA certificate.
  3. Do not forget to choose SHA-256 .
  4. As the template, select [default] HTTPS_server . Click on Apply all .
  5. Then, on the Subject tab, select our key and fill in the required fields.

We create keys and the certificate for the user

  1. The user's private key will be stored on our token. To work with it, you need to install the PKCS # 11 library from our site. For popular distributions, we distribute ready-made packages that lie here - . We also have assemblies for arm64, armv7el, armv7hf, e2k, mipso32el, which can be taken in our SDK - . In addition to assemblies for linux, there are also assemblies for macOS, freebsd and android.
  2. Add the new PKCS # 11 Provider to the XCA. To do this, go to the Options menu on the PKCS # 11 Provider tab .
  3. Click Add and select the path to the PKCS # 11 library. In my case it is \ usr \ lib \
  4. We need a formatted token Rutoken EDS PKI. Download the rtAdmin utility -
  5. We carry out

    $ rtAdmin -f -q -z /usr/lib/ -u 
  6. As the type of key we select - the RSA-2048 key on the PKI Rutoken EDS. I named this key Client Key.

  7. Enter the PIN code. And we are waiting for the completion of the hardware generation of the key pair

  8. We create the certificate for the user by analogy with the server certificate. This time select the [default] HTTPS_client template and don't forget to click Apply all .
  9. On the Subject tab, enter user information. We respond in the affirmative to the request to save the certificate for the token.

As a result, on the Certificates tab in XCA, you should get something like this.

This minimum set of keys and certificates is enough to start setting up the servers directly.

To configure, we need to export the CA certificate, server certificate and server private key.

To do this, select the desired entry on the appropriate tab in the XCA and click Export .


How to install and run a nginx server, I won’t write - there are enough articles on the Internet on this subject, not to mention the official documentation. Let's get down to setting up HTTPS and two-factor token authentication.

Add the following lines to the server section in nginx.conf:

server {
	listen 443 ssl;
	ssl_verify_depth 1;
	ssl_certificate /etc/nginx/Server.crt;
	ssl_certificate_key /etc/nginx/ServerKey.pem;
	ssl_client_certificate /etc/nginx/CA.crt;
	ssl_verify_client on;

A detailed description of all the parameters related to the ssl configuration in nginx can be found here -

I will only briefly describe those that I myself set:

  • ssl_verify_client - Indicates that the certificate trust chain needs to be verified.
  • ssl_verify_depth - Determines the depth of the trusted root certificate search in the chain. Since our client certificate is immediately signed on the root certificate, the depth is set to 1. If the user certificate is signed on an intermediate CA, then 2 must be specified in this parameter, and so on.
  • ssl_client_certificate - Specifies the path to the trusted root certificate, which is used to verify trust in the user certificate.
  • ssl_certificate / ssl_certificate_key - indicate the path to the server certificate / private key.

Do not forget to run nginx -t to check that there are no typos in the config, and all the files are where necessary and so on.

And actually everything! As you can see, the setup is very simple.

Checking work in Firefox

Since we are doing everything completely on Linux, we will assume that our users also work on Linux (if they have Windows, then see the instructions for setting up browsers in the previous article .

  1. We start Firefox.
  2. Let's try to log in without a token at the beginning. We get the following picture:

  3. Go to about: preferences # privacy , and go to Security Devices ...
  4. Click Load to add the new PKCS # 11 Device Driver and specify the path to our
  5. To verify that the certificate is visible, you can go to Certificate Manager . You are prompted for a PIN code. After the correct entry, you can verify that on the Your Certificates tab our certificate with a token has appeared.
  6. Now we go with the token. Firefox suggests choosing a certificate that will be selected on the server. Choose our certificate.

  7. PROFIT!

The setup is done once, and as you can see in the certificate request window, we can save our choice. After that, each time you enter the portal, we only need to insert a token and enter the PIN code of the user that was set during formatting. After such authentication, the server already knows which user has logged into it and you can no longer make any additional windows for verification, but immediately let the user into his personal account.


As with nginx, no one should have problems installing apache. If you do not know how to install this web server, just use the official documentation.

And we are starting to configure our HTTPS and two-factor authentication:

  1. First you need to activate mod_ssl:

    $ a2enmod ssl
  2. And then enable the default HTTPS site settings:

    $ a2ensite default-ssl
  3. Now edit the configuration file: /etc/apache2/sites-enabled/default-ssl.conf:

        SSLEngine on
        SSLProtocol all -SSLv2
        SSLCertificateFile	/etc/apache2/sites-enabled/Server.crt
        SSLCertificateKeyFile /etc/apache2/sites-enabled/ServerKey.pem
        SSLCACertificateFile /etc/apache2/sites-enabled/CA.crt
        SSLVerifyClient require
        SSLVerifyDepth  10

    As you can see, the names of the parameters almost coincide with the names of the parameters in nginx, so I will not explain them. Again, anyone interested in the details - welcome to the documentation.
    Now restart our server:

    $ service apache2 reload
    $ service apache2 restart

  4. As you can see, configure two-factor authentication on any web server, that on Windows, that on Linux it takes a maximum of one hour. And setting up browsers takes about 5 minutes. Many people think that setting up and working with two-factor authentication is difficult and incomprehensible. I hope our article at least a little, but debunking this myth.

Only registered users can participate in the survey. Please come in.

Do I need instructions on how to configure TLS with certificates in accordance with GOST 34.10-2012:

  • 84.6% Yes, TLS-GOST is very necessary 44
  • 15.3% No, tuning with GOST algorithms is not interesting 8

Also popular now: