Deploy Smart Cards on Chrome OS
This article focuses on the steps required to successfully deploy Smart Card support on Chrome OS across your enterprise. It also provides helpful troubleshooting information for common errors that admins may run into. If you have comments or suggestions, please send them via email to email@example.com. If you are a regular user and wish to install smart card apps on your personal device, then please refer to Use Smart Cards on Chrome OS.
Step 1: Force 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.
To install the Smart Card Connector for your users, navigate to the app in the Chrome App Management section of the admin console. Under User Settings, select the Organizational Unit of your choice, and check Force installation. This will push the Smart Card Connector to all users in that chosen organization.
Note: The Smart Card Connector app attempts to automatically detect and work with smart card readers. Not all smart card readers are supported however. The app builds on top of libccid which lists supported readers here. Readers in the “supported” and “should work” categories are expected to work reliably.
Step 2: Force Install a Smart Card middleware app
In addition to the connector, admins need to install the proper middleware app that can communicate with smart cards and offer client certificates that can authenticate users 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. The charismathics middleware provider can be found on the Chrome Web Store. To force-install it for your users, follow the same instructions as in Step 1 by navigating to the app in the Chrome App Management section of the console and checking Force installation on your OU of choice.
Note: The connector app offers a public API that other middleware apps like CACKey can also use. If you would like to deploy a different middleware, please put us in touch with your vendor and we will provide them with necessary instructions for bringing support to the Chrome OS platform.
Step 3: Push all necessary root and intermediate certificates
Depending on the sites your users try to access, you might need to install trust roots and intermediaries onto their devices. Once those certificates are identified, you can follow the instructions in Set up an HTTPS Certificate Authority to push those certificates onto your users’ profiles.
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.
Step 4: Configure Smart Card Connector to auto-allow communication
Apps like Citrix and Charismathics will need to contact the Smart Card Connector to communicate with users’ 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.
Admins can remove this step for users by auto-granting such permissions via app configuration on the management console. To do that, go to the App Management section and select the proper OU to configure. Under the Configure option, if Setting Inherited is showing, click on Override. Then click the UPLOAD CONFIGURATION FILE button and upload a configuration file and press Save. The configuration file should be a text file that contains the following value. An example policy file can be found here.
Note: Whitelisting these apps will potentially provide third parties access to your users' personal information such as certificates on a smart card. Please make sure you have the appropriate notification and consent flows with your users for collecting and sharing of their personal information.
Step 5 (Optional): Configure Chrome to auto-select certificates for URLs
Chrome OS can be configured to automatically select certain certificates for certain URLs. In the default case, users will be presented a list of certificates that match a certain website. By setting this policy, administrators can remove that step by pre-matching users’ certificates to certain URL patterns.
This setting can be found on the management console under User Settings > Client Certificates. More information and example values can be found in the help center article.
Your users should now be all set to use their smart cards! All they have to do is login from any Chromebook with their Google credentials. The settings you configured will be downloaded and applied and all your users have to do is navigate to HTTPS websites and Chrome will prompt them to use certificates it has detected off their cards to authenticate them into their remote systems.
Step 6 (Optional): Configure Virtual Desktop Environment
In case you are using a virtual desktop environment such as Citrix or VMware, you will need to properly configure them to allow smart card access through as well as smart card redirection into the virtualized session. Full configuration instructions for the various vendors can be found on their sites: [Citrix documentation].
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. For ensuring the security of your resources, it is recommended to set server timeouts that require a re-auth from the client at regular intervals. 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 signing are also shown in the drop-down dialog. This might lead to user confusion. Properly configuring certificate auto-selection is crucial in cases like these to entirely avoid confusion in the deployment.
Hopefully your deployment goes very smoothly. In the case 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:
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).
The website you are trying to connect to. Please file separate bug reports for separate websites.
System, card, and reader Information
Smart Card Connector logs
Middleware app logs
Once compiled, please send this report to the support alias firstname.lastname@example.org.
System, card, and reader Information
Chrome OS version
Type of smart card reader
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.
Go to chrome://extensions.
Check Developer mode at the top-right corner.
Scroll to the Charismathics extension. Click on background page.
Go to the Console section.
Right click and Save as… to export the logs.
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.