Use Smart Cards on Chrome OS

This article focuses on the steps required to successfully start using your Smart Card on Chrome OS on your personal device. If you are an admin and wish to deploy smart cards across your organization, then please refer to Deploy Smart Cards on Chrome OS.

Step 1: Install the Smart Card Connector app

The Smart Card Connector app provides Chromebooks with PCSC support. This PCSC API can then be used by other applications such as smart card middleware and Citrix to provide functionality on top e.g. browser integration and virtual session redirection. You can install the app by going to the entry on the Chrome Web Store and clicking on Add to Chrome.

Step 2: Install a Smart Card middleware app

In addition to the connector, you need to install the proper middleware app that can communicate with smart cards and offer client certificates that can authenticate you to HTTPS websites. Google has partnered with Charismathics to bring support for a wide range of cards and profiles, including PIV and CAC, onto Chrome OS. You can install the app by going to the entry on the Chrome Web Store and clicking on Install.


Note: The connector app offers a public API that middleware apps other than Charismathics can also use. You can install other middleware vendors like CACKey directly from the Chrome Web Store.

Step 3: Install all necessary root and intermediate certificates

Depending on the sites you are trying to access, you might need to install trust roots and intermediaries onto your Chromebook. Once those certificates are identified, you can install them by navigating to the chrome://certificate-manager URL and then going to Authorities > Import… Once you select a file, Chrome will ask you to configure trust settings for a certain root. Check all boxes that apply and then press OK.


Note: Installing a root certificate on a device is a very privacy and security sensitive operation. Please ensure you only install trust roots you obtained and verified from sources you trust.

Note: For US Department of Defense users, most websites require users to install several trust roots and intermediaries. These are available as official downloads from IASE Tools > Trust Store > PKI CA Certificate Bundles: PKCS#7 > For DoD PKI Only bundle. Once you download that bundle on Chrome OS, go to the Files app, double click to mount the zip and then drag and drop the contents of the mounted zip into the downloads folder. Then follow the import instructions in Step 3 for the following two files, checking all boxes when configuring trust



Step 4: Allow middleware to communicate with the Smart Card Connector

Apps like Citrix and Charismathics will need to contact the Smart Card Connector to communicate with your cards and readers. As cards and readers contain sensitive user information, the connector app will show users a permission dialog before granting access to any app. If you see a permission dialog prompted by a third party app you trust, click on ALLOW to move on.

You are now ready to use your smart card! Navigate to HTTPS websites and Chrome will prompt you to use certificates it has detected off your card to authenticate you into your remote systems.

Known Issues

Chrome not matching certificate on card

This is most likely an issue with configuration of root and intermediary certificates. Please ensure that you have followed the instructions to set those properly. If this issue keeps happening, it is probably best to file a bug report with more information.

Chrome keeps connection open after card is removed

If a user removes their card, Chrome will not end their session with that server. This is working as intended (and is the default behavior on Chrome on other platforms as well). Chrome will only try to authenticate again when challenged by the server; this is a security setting determined by your administrator.  If you are testing and need to force reauthentication with the server, try using an Incognito window, which will not use the previous session and will not be retained in subsequent requests.

No UI feedback on wrong PIN

If users enter a wrong PIN, Charismathics does not offer any direct feedback in the dialog. The user will need to navigate to the site to be asked for the PIN again.

Certificates provided are not filtered

All certificates are provided to the system regardless of their type e.g. certificates for email signature are also shown in the drop-down dialog. You need to be aware of what certificate is needed for a certain website so you can choose it from the dropdown. This may mean experimenting to pick the first, second, or even third apparently-identical certificate from your card when authenticating to some sites. The order remains stable across attempts so this is something that only needs to be done once.

Reporting Bugs

Hopefully everything goes smoothly for you. In the event that you run into any bugs, we would be more than happy to get a bug report that can help us look into the issue. Any bug report must contain:

  1. Description of the issue and instructions to reproduce. Preferably a screencast (there are several third party Chrome apps that can capture screencasts e.g. Screencastify).
  2. The website you are trying to connect to. Please file separate bug reports for separate websites.

  3. System, card, and reader Information

  4. Smart Card Connector logs

  5. Middleware app logs

  6. chrome://net-internals export

Once compiled, please send this report to us when you contact support.

System, card, and reader Information

  1. Chrome OS version

  2. Type of smart card reader

  3. Smart card info: smart card vendor, type, and profile.

Smart Card Connector logs

The screen for the Smart Card Connector has a link at the bottom that allows the user to export the logs. This will copy all logs onto the clipboard. Use any text editing app to save those logs and send them along.

Middleware app logs

Each middleware app will have its own method to extract logs. For the Charismathics app in particular, logs can be extracted from the developer console.

  1. Go to chrome://extensions.

  2. Check Developer mode at the top-right corner.

  3. Scroll to the Charismathics extension. Click on background page.

  4. Go to the Console section.

  5. Right click and Save as… to export the logs.

Note: Your administrator might have disabled Chrome dev tools via policy in which case you will not be able to get access to the background page.

chrome://net-internals export

Some issues might be related to the way Chrome is handling client connections. Chrome logs can be extracted by going to chrome://net-internals/#export. Note that the logs only start populating when you navigate to the URL, so please make sure you navigate prior to running the buggy scenario.

Note: As logs can be very verbose, try restricting your log capture to only the buggy scenario. This will help us focus on the things that are going wrong without getting distracted by noisy traffic e.g. doing a Google search while you are capturing logs.

Was this helpful?
How can we improve it?