PIV-I Identity Provider

From NIEF Wiki
Jump to navigation Jump to search

This guide describes how one can implement a NIEF compliant Identity Provider that authenticates users who possess PIV-I cards that have been cross certified with the Federal Bridge PKI.

Background

Personal Identification Verification Interoperable (PIV-I) cards are smart cards issued by various organizations, typically operating at the state and local government level. The standard is designed to be aligned/interoperable with the Federal standard for PIV. Supporting this type of user base with a turnkey Identity Provider capability has tremendous value.

This implementation guide is designed around the use of free and open sourced capabilities, primarily focusing on the use of the following:

Getting Started

This guide assumes the user is comfortable deploying a Linux (or equivalent) server with Apache HTTP, Java, and Tomcat. No specific Shibboleth experience is required to follow this guide. If a user is not comfortable deploying the prerequisites, they should acquire that experience or collaborate with help@nief.org before attempting to follow this guide. The authors of this guide tested this deploy guide with CentOS 7, but any modern Linux distribution that includes packages for the Apache HTTP Server is expected to work. It is likely also possible to do deploy to a Windows or other server environment as long as the deployer is able to adapt the HTTP configuration steps accordingly and that Java 8 is available for running Apache Tomcat and Shibboleth.

Enabling Authentication

TBD. Describe how to configure Apache HTTPD. Include a section on CA chaining. Include a section on OCSP/CRL. Include a sample php page for verifying authn and passing of credential data.

Certificate Authority Specification

Apache requires the full certificate chain including an anchor (self signed certificate) to be specified in the HTTP Server configuration. This is an important thing to understand as typically with PIV-I (and PIV), you are working with cross certified CAs, and if you only include cross certified certs in the CA certificate chain, Apache will fail with errors about chain length being too long (it gets stuck in a loop going through the chain back and forth).

Here is a copy of a valid chain (uni-directional chain) from the FTI Test CA to the Federal Test PKI CA: File:Fti-test-ca-chain.txt.

Within the Apache configuration, typically within the file ssl.conf you specify this CA file like this:

    SSLCACertificateFile /etc/httpd/trust/fti-test-ca-chain.pem

For a production deploy the CA chain would be different and will need to be constructed by following the chain and combining the certificates into a single PEM file.

Certificate Status / Revocation Checking

If OCSP (online certificate status protocol) is available for verifying a certificate is current then it is the simplest option to enable it with a single Apache HTTP Server directive:

   SSLOCSPEnable On

In some cases (for example the current test CA chain) OCSP is not fully implemented and it's necessary to instead use CRL (Certificate Revocation List) checking. This is enabled within the the Apache HTTP Server configuration:

   SSLCARevocationFile /etc/httpd/trust/fti-crl.pem

This file has to be updated regularly as it only works if it is current, and by design the file has an expiration date to insure software checking against the CRL is using a current copy of the CRL. The following script may be useful in configuring this in an automated fashion:

   #!/bin/bash
   cd /etc/httpd/trust
   if [ -f FTITestCA.crl ]; then rm FTITestCA.crl; fi
   wget http://pki.fti.org/fti_ca/crl/FTITestCA.crl
   openssl crl -in FTITestCA.crl -inform DER -out fti-crl.pem
   systemctl restart httpd

A script such as this can then be configured in a crontab to insure the CRL is up to date.

Configuring Client Certificate Authentication

It is very rare that you will want to require client certificate authentication for the entire server, typically this require is constrained to specific URL paths. At the toplevel of the HTTP Server SSL configuration you include this directive:

   SSLVerifyClient none

Possibly in another configuration file (or in another section of the SSL configuration file) you would enable TLS client certificate authentication like this:

  <Location "/pivi-test">
     SSLOptions +StdEnvVars +ExportCertData
     SSLVerifyClient require
     SSLVerifyDepth 4
  </Location>

Installing Shibboleth

TBD. Include download links. Specify how to run the installer. Specify how to enable trusted partners. Specify how to enable X.509 Authn. Specify how to enable Shibboleth within Apache Tomcat.

Configuring NIEF Attributes

TBD. Explain how attribute resolution works. Explain how attribute filtering works. Pointers to existing connectors on github. Pointers to documentation on the Shibboleth wiki.

Testing

Just link to the NIEF Testbed part of the wiki.