If you’re building a website for the U.S. Government, you may be tasked with making “single sign on” (SSO) work with the U.S. Government "Personal Identity Verification" (PIV) Credential cards. PIV cards are used government-wide to control access to Federally Controlled Facilities and information systems at the appropriate security level. Common Access Cards or “CACs ” are a specific subset of PIV cards used by the U.S. Department of Defense.
Interestingly, while PIV authentication is a requirement for FedRAMP certification, there are a number of FedRAMP certified products that currently do NOT provide PIV authentication out of the box. Extensive integration work by your IT team would be required to integrate these SaaS products into your centralized access system. Do your homework if you are going to purchase a SaaS product that is FedRAMP compliant and make sure you can actually enforce login via PIV.
We had to tackle PIV/CAC authentication with Concrete CMS for a large number of U.S. Army websites and Intranets. We found the challenge to be remarkably complicated since there isn’t a lot of documentation or background information out there. We’re sharing what we learned here in an effort to save fellow developers some of the time and headaches we endured. That said, if you’re building a website or intranet using Concrete CMS for the U.S Government, you should strongly consider buying our “PIV/CAC Authentication SSO Provider” - a PIV/CAC SSO authentication portal which handles all of this for you and manages access across multiple connected Concrete sites. That hard sell out of the way, let’s get into the details.
What is a PIV/CAC Card for?
It looks like a drivers license and it's ubiquitous if you’re doing government work. It identifies what security clearance the holder has been granted. It’s got your picture on there and a bunch of digital information embedded on it. You can use it to sign PDF documents for the government with a “digital government signature.” You’ll need it to access your government email and other SaaS systems used by the Government like Microsoft Teams and Concrete CMS. You’ll need it at the gate of any DoD military installation to be allowed in. You could even use it as a Real ID for airplane travel, although flashing around your government ID is considered a no-no as it makes you a target.
How do you get a CAC Card?
On your own, you don’t. You’ll have to be sponsored by a government agency to get one, and if that’s going to happen, chances are you’ll already know about it. Maybe you’re applying for a job at a big contracting firm that does government work like Booz Allen or Accenture. Maybe your company has just won a contract with the government. Regardless, this isn’t a thing you can really prepare for or proactively get ‘just in case.’ If you need one, you’ll be told.
You will have to pass a background check for the level of clearance you will be granted. A basic CAC card does not imply a particularly high level of security clearance by default. Don’t freak out, the government works with literally millions of people and suppliers, none of them are perfect, and having a CAC card does not mean you’re a Jason Bourne. Try not to owe any money to Russian gangsters, have ties to extremist religious groups, or have a raging drug problem and you’re likely going to pass the background check just fine. You’ll have to fill out forms and provide fingerprints. You will also have to provide proof of U.S. Citizenship.
Once the background check has cleared you’ll have to go to a physical location to get your CAC card. Here in Portland, Oregon the best spot is the U.S. Army Corps of Engineers office downtown, but there’s plenty of spots that can issue them. This site will help with details. Remember to bring two pieces of government issued ID (driver’s license, passport) or you won’t be given your CAC/PIV card
What is actually going on inside a PIV/CAC card.
Inside is at least one government issued client side certificate (and sometimes multiple ones for different uses) that is signed by a root certificate the Government Agency (like the DOD) maintains. A key code (typically 6 digits) is uniquely associated with each PIV card that must be entered correctly by the user for access to be granted. When you put your card in a PIV/CAC reader on a computer and visit a government website (or system) that requires PIV/CAC authentication, you’ll be asked to pick one of the certificates on your card and enter the correct pin in order to access that site (or system).
Making a Client Computer Support a PIV/CAC Card
Just plugging your USB card reader into any old computer with a CAC card in it isn’t going to work. That computer will need some certificates installed on it, and depending on the computer that might be a pretty interesting adventure.
The simplest answer is to be issued a U.S. Government Agency issued computer with an internal USB card reader managed by the Agency IT department. You’re not going to be given a brand new MacBook Air, but it will be someone else’s problem when it doesn’t work - and that might be a welcome relief.
If you want to use your own machine, that's totally fine. You’ll need to buy a PIV/CAC smart card reader for whatever type of USB port you have. You’ll also need to manually install a bunch of certificates before anything will work. This step is surprisingly complex and we only got through thanks to the wisdom at https://militarycac.com/. Thank you Michael J. Danberry for building and maintaining that website. Its aesthetic is straight from the 90’s and its spirit of information sharing is the epitome of everything that made the web great back in the day. (Michael, if you ever get tired of editing HTML files by hand, we’d love to help rebuild that site with Concrete CMS.)
Alternatively, there were some applications you could find out there that installed these certs for you. It’s been a while, but check out Centrify, now Delinea.
Your new PIV/CAC card will need to be activated. You’ll have to visit the RAPIDS Self-Service CACF Maintenance website (https://www.dmdc.osd.mil/self_service) and go through the steps there before your card will work on any computer.
Don’t get locked out!
A quick word to the wise, it’s super easy to get your CAC/PIV card locked. Enter your pin wrong 3 times in a row, and that card is now indefinitely locked.
If you have your PIV/CAC inserted when your computer starts up, read your login form carefully. It’s quite likely the password your machine is asking you for on login is actually your PIV/CAC pin code. This is a really good way to accidentally lock your card by entering your machine’s administrator password instead of your pin code.
Unlocking a PIV/CAC requires you to go to a physical location somewhere (perhaps many hours away, with long wait times) and sheepishly explain yourself to a government IT official. While it’s always fun to make new friends, this is not the best use of anyone's time.
Building PIV/CAC Capability into your Product
This information is all pretty high level, we’re assuming you have a solid understanding of authentication and how to build single sign on solutions in general. Here’s some key pieces of information and big ideas that will absolutely save you days of pain.
You will have to map the CAC/PIV certificate's subject DN to the individual’s identity inside your system. You’ll want to make some user model within your app and then bind the certificate's subject DN to that user. Think of the card as a number referencing the access level of this “identity.” It’s still up to you to build a system that tracks whatever user information you actually need like an email, name, or whatever and to manage permissions and access the user is permitted to have. Your application should have its own policy for what to do with a new user. Can people sign up through a user flow, or are they given accounts by an administrator through some other process?
Generally when it comes to storing PII you should be thinking ‘less is more.’ Different Government Agencies have different rules for PII. FedRAMP moderate allows storage of PII but your Agency might have different internal compliance rules. The DoD, for example, has an “impact level” system with restrictions about what can be stored where. The DoD’s “moderate” system does not necessarily map to FedRAMPs “moderate”. We could write a whole separate article on how to navigate their “Information Type Surveys”, Privacy Impact Analysis, DoD SSP Addendums etc. Our advice is to resist the urge to collect information unless there’s a compelling business case for capturing and securely managing that information.
The CAC/PIV card plus pin provides Auth N (authentication.) Just because someone has a valid CAC doesn’t mean they should get access to your application, so you’ll need to be able to lock users out locally too. CAC/PIV cards do NOT provide Auth Z (authorization) for whatever system you are building. In other words, your system will have to include roles for who is allowed to access what. You might want to make your roles customizable like Concrete’s PIV portal so that roles can be configured for different client’s needs. You will have to provide the capability for your government client administrators to add users and remove users to different roles for your system.
Your web server will need to establish a connection with the client. This means you can’t mindlessly use a typical CDN or Application load balancer because the client needs to connect directly to the server without being decrypted along the way. We used a classic AWS network load balancer and configured it to pass encrypted traffic to the final authentication server.
Your authentication web server will also need to be configured to both require client side certificates and to validate the certificates against the appropriate root certificate like the DoD root certificate available here: https://public.cyber.mil/pki-pke/pkipke-document-library/
The web server manages validating the certificates against the root certificate, but we still need to check for whether the certificate has been revoked. When someone’s PIV/CAC is revoked, a revocation certificate is added to the Certificate Revocation List (CRL). As a system administrator you routinely pull all relevant CRLs and update your server to check those, it's your responsibility to ensure that users with a revoked certificate lose access to your system as soon as possible.
There are OSCP endpoints you can connect to as an authoritative server instead of using CRL files, but that means your authentication relies on someone else’s service for which you have no SLA. Here’s a starting point https://public.cyber.mil/pki-pke/admins/.
When someone tries to navigate to your authentication endpoint, the SSL connection handshake will force them to enter their pin and select a valid certificate which will be included in the request. If the certificate is valid, the server will be able to inspect the "subject distinguished name" (subject DN) in order to match the certificate with a user. If the certificate is invalid, a connection will not be established and the user will see an error in their browser.
You will then need to check to see if you’ve got this subject DN bound to a user account in your system, and if not you’ll need to determine what the right process is for your business case.
That’s it. The certificate is just proof that the person has plugged in a card and knows their keycode, and the government issued this card. It’s up to you to manage their session, any required user information, and access levels.
Conclusion
Once you get this stuff figured out it’s a great level of security and feels significantly safer than just forcing good password policies. That said, it is not particularly simple to get set up and if you’re looking at doing this from scratch we’d love to talk to you about how Concrete CMS might save you a lot of time.
Read our additional resources for governments:
- Government Websites Using Concrete CMS
- Government DAM Buying Guide
- How to make U.S Government PIV/CAC Authentication Work
- Lesser Known Requirements For Federal Websites
- Government Website KPIs: How to Choose the Right KPIs for Your Site
-
Open Source For Government and Its Impact on Internal Communications