Smart Card Logon for Firefox Browser
You may need to configure Firefox to enable your agency users to log into web applications using their PIV credentials. This can be tricky because Firefox supports a protocol (PKCS #11) that is not always natively supported by operating systems (OS) or OS default drivers.
This guide will help you configure Firefox by using an open source software package. In addition to open source solutions, commercial software may be used.
PKCS #11
Are you interested in learning more? Search online for PKCS #11 to find other available resources.
Install and Test OpenSC
OpenSC will enable a user’s PIV credential to work with Firefox and some signing and encryption applications.
First, you will need to install and test OpenSC. OpenSC has installers for multiple operating systems, including Windows, macOS, and Linux flavors. The installers can be downloaded directly from GitHub and the OpenSC wiki:
When installing OpenSC, you need to consider some items that are specific for the federal government:
Use OpenSC Version Greater Than 0.20.0 to avoid Authentication Errors
If a version of OpenSC less than 0.20.0 is used, users will encounter errors when performing mTLS with servers that offer TLS 1.3. This can include browser errors like ERR_SSL_CLIENT_AUTH_SIGNATURE_FAILED.
- You will need to download and install either the 64-bit or 32-bit version of OpenSC, depending on the OS.
- You do not need to install the full packages for OpenSC.
- You can limit the packages for distribution to enterprise workstations to just support PKCS #11.
- You can push the packages to the enterprise workstations using your enterprise configuration management tools.
Configure Firefox
Load New Security Device
Launch Firefox and load a new Security Device (i.e., the Security Device is your PIV credential) using the OpenSC PKCS #11 driver:
- From the Firefox taskbar, click the Options icon (“gear” shape).
- Click the Privacy & Security menu from the left-hand navigation.
- Scroll down until you see the Certificates heading, and then click Security Devices.
- At the Device Manager window, click the Load button and enter this module name: OpenSC PKCS#11 Module.
- Select the directory where the OpenSC PKCS #11 driver is located. The default locations are:
| OS | Default Driver Location | Driver File Name |
|---|---|---|
| Windows | C:\Windows\System32 | pkcs11.dll |
| macOS | /Library/OpenSC/lib/ | pkcs11.so |
| Red Hat | /usr/lib/ | pkcs11.so |
| Ubuntu | /usr/lib/x86_64-linux-gnu/ | opensc-pkcs11.so |
- Click Open and verify that the module has been loaded. Then click OK to return to the Privacy & Security options.
Import PIV Issuer Certificate
- Click the View Certificates button. If prompted, enter your PIV credential PIN.
- Click the Authorities tab from the top navigation.
- Click the Import button to import a copy of your PIV credential issuer’s certification authority (CA) certificate. When prompted, trust the certificate for identifying websites and email users.
- Click OK and restart Firefox.
Test Authentication
- Browse to a web application that requires authentication with a PIV credential. A common web application to use as a test is MAX.gov. (Note: You’ll need to have an existing MAX.gov account for this to work.)
- Firefox will prompt you to enter your PIV credential PIN and select a certificate for authentication.
