Chapter 30. Configuring smart card authentication with the web console for centrally managed users

Configure smart card authentication in the RHEL 8 web console for users who are centrally managed by:

  • Identity Management
  • Active Directory which is connected in the cross-forest trust with Identity Management
Smart card authentication does not elevate administrative privileges yet and the web console opens in the web browser in the read-only mode.
You can run administrative commands in the built-in terminal with `sudo`.


  • The system for which you want to use the smart card authentication must be a member of an Active Directory or Identity Management domain.

    For details about joining the RHEL 8 system into a domain using the web console, see Joining a RHEL 8 system to an IdM domain using the web console.

  • The certificate used for the smart card authentication must be associated with a particular user in Identity Management or Active Directory.

    For more details about associating a certificate with the user in Identity Management, see Adding a certificate to a user entry in IdM.

30.1. Smart card authentication for centrally managed users

A smart card is a physical device, which can provide personal authentication using certificates stored on the card. Personal authentication means that you can use smart cards in the same way as user passwords.

You can store user credentials on the smart card in the form of a private key and a certificate. Special software and hardware is used to access them. You insert the smart card into a reader or a USB socket and supply the PIN code for the smart card instead of providing your password.

Identity Management (IdM) supports smart card authentication with:


If you want to start to use smart card authentication, see the hardware requirements: Smart Card support in RHEL8.

30.2. Installing tools for managing and using smart cards

To configure your smart card, you need tools which can generate certificates and store them on a smart card.

You must:

  • Install the gnutls-utils package which helps you to manage certificates.
  • Install the opensc package which provides a set of libraries and utilities to work with smart cards.
  • Start the pcscd service which communicates with the smart card reader.


  1. Install the opensc and gnutls-utils packages:

    # dnf -y install opensc gnutls-utils
  2. Start the pcscd service.

    # systemctl start pcscd

Verify that the pcscd service is up and running.

30.3. Storing a certificate on a smart card

This section describes smart card configuration with the pkcs15-init tool, which helps you to configure:

  • Erasing your smart card
  • Setting new PINs and optional PIN Unblocking Keys (PUKs)
  • Creating a new slot on the smart card
  • Storing the certificate, private key, and public key in the slot
  • Locking the smart card settings (some smart cards require this type of finalization)


  • The opensc package, which includes the pkcs15-init tool is installed.

    For details, see Installing tools for managing and using smart cards.

  • The card is inserted in the reader and connected to the computer.
  • You have the private key, public key, and certificate to store on the smart card. In this procedure, testuser.key, testuserpublic.key, and testuser.crt are the names used for the private key, public key, and the certificate.
  • Your current smart card user PIN and Security Officer PIN (SO-PIN)


  1. Erase your smart card and authenticate yourself with your PIN:

    $ pkcs15-init --erase-card --use-default-transport-keys
    Using reader with a card: Reader name
    PIN [Security Officer PIN] required.
    Please enter PIN [Security Officer PIN]:

    The card has been erased.

  2. Initialize your smart card, set your user PIN and PUK, and your Security Officer PIN and PUK:

    $ pkcs15-init --create-pkcs15 --use-default-transport-keys \
        --pin 963214 --puk 321478 --so-pin 65498714 --so-puk 784123
    Using reader with a card: Reader name

    The pcks15-init tool creates a new slot on the smart card.

  3. Set the label and the authentication ID for the slot:

    $ pkcs15-init --store-pin --label testuser \
        --auth-id 01 --so-pin 65498714 --pin 963214 --puk 321478
    Using reader with a card: Reader name

    The label is set to a human-readable value, in this case, testuser. The auth-id must be two hexadecimal values, in this case it is set to 01.

  4. Store and label the private key in the new slot on the smart card:

    $ pkcs15-init --store-private-key testuser.key --label testuser_key \
        --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name

    The value you specify for --id must be the same when storing your private key, and certificate. If you do not specify a value for --id, a more complicated value is calculated by the tool and it is therefore easier to define your own value.

  5. Store and label the certificate in the new slot on the smart card:

    $ pkcs15-init --store-certificate testuser.crt --label testuser_crt \
        --auth-id 01 --id 01 --format pem --pin 963214
    Using reader with a card: Reader name
  6. (Optional) Store and label the public key in the new slot on the smart card:

    $ pkcs15-init --store-public-key testuserpublic.key
        --label testuserpublic_key --auth-id 01 --id 01 --pin 963214
    Using reader with a card: Reader name

    If the public key corresponds to a private key and/or certificate, you should specify the same ID as that private key and/or certificate.

  7. (Optional) Some smart cards require you to finalize the card by locking the settings:

    $ pkcs15-init -F

    At this stage, your smart card includes the certificate, private key, and public key in the newly created slot. You have also created your user PIN and PUK and the Security Officer PIN and PUK.

30.4. Enabling smart card authentication for the web console

To be able to use smart card authentication in the web console, enable smart card authentication in the cockpit.conf file.

Additionally, you can disable password authentication in the same file.



  1. Log in to the RHEL web console with administrator privileges.

    For details, see Logging in to the web console.

  2. Click Terminal.
  3. In the /etc/cockpit/cockpit.conf, set the ClientCertAuthentication to yes:

    ClientCertAuthentication = yes
  4. Optionally, disable password based authentication in cockpit.conf with:

    action = none

    This configuration disables password authentication and you must always use the smart card.

  5. Restart the web console to make sure that the cockpit.service accepts the change:

    # systemctl restart cockpit

30.5. Logging in to the web console with smart cards

You can use smart cards to log in to the web console.


  • A valid certificate stored in your smart card that is associated to a user account created in a Active Directory or Identity Management domain.
  • PIN to unlock the smart card.
  • The smart card has been put into the reader.


  1. Open your web browser and add the web console’s address in the address bar.

    The browser asks you to add the PIN protecting the certificate stored on the smart card.

  2. In the Password Required dialog box, enter PIN and click OK.
  3. In the User Identification Request dialog box, select the certificate stored in the smart card.
  4. Select Remember this decision.

    The system does not open this window next time.

  5. Click OK.

You are now connected and the web console displays its content.

30.6. Limiting user sessions and memory to prevent a DoS attack

Certificate authentication is protected by separating and isolating instances of the cockpit-ws web server against attackers who wants to impersonate another user. However, this introduces a potential Denial of Service (DoS) attack: A remote attacker could create a large number of certificates and send a large number of HTTPS requests to cockpit-ws each using a different certificate.

To prevent this DoS, the collective resources of these web server instances are limited. By default, limits to the number of connections and to memory usage are set to 200 threads and a 75% (soft) / 90% (hard) memory limit.

The following procedure describes resource protection by limiting the number of connections and memory.


  1. In the terminal, open the system-cockpithttps.slice configuration file:

    # systemctl edit system-cockpithttps.slice
  2. Limit the TasksMax to 100 and CPUQuota to 30%:

    # change existing value
    # add new restriction
  3. To apply the changes, restart the system:

    # systemctl daemon-reload
    # systemctl stop cockpit

Now, the new memory and user session limits protect the cockpit-ws web server from DoS attacks.

30.7. Additional resources