CAC/PIV Authentication

GOVERN Federal disables username/password authentication and requires Common Access Card (CAC) or Personal Identity Verification (PIV) smart card authentication for all users.

Overview

CAC/PIV authentication works via PKCS#11 (smart card middleware) or via your agency’s identity provider (IdP) with PIV support. GOVERN supports both paths:

Path	Use Case	Infrastructure Required
Direct PKCS#11	On-premise deployments	Smart card readers, middleware
Agency IdP (SAML/OIDC)	GovCloud deployments	IdP with PIV support (e.g., Okta, Azure AD, Ping)
DoD Enterprise IdP	DoD deployments	CAC-enabled IdP (DISA or agency)

Direct PKCS#11 Configuration

For on-premise deployments where users authenticate directly with their smart card:

Prerequisites

OpenSC or DoD/agency-approved smart card middleware
SSL certificates loaded from the DoD Trust Store
CAC/PIV certificates issued by DoD or agency CA

Helm Configuration

auth:
  provider: cac-piv
  cacPiv:
    mode: pkcs11
    trustStore: /etc/govern/certs/dod-trust-store.pem
    ocsp:
      enabled: true
      url: http://ocsp.disa.mil
    crl:
      enabled: true
      url: http://crl.disa.mil/crl/DODIDCA.crl
    userMappingAttribute: upn  # or email, subject
    requiredExtendedKeyUsage:
      - clientAuth
      - msSmartcardLogon

Loading DoD Trust Store

# Download DoD root certificates (from DoD PKI management)
curl -o dod-roots.p7b https://dl.dod.cyber.mil/wp-content/uploads/pki-pke/zip/unclass-dod_approved_external_pkis_trust_chain.zip

# Convert to PEM
openssl pkcs7 -in dod-roots.p7b -print_certs -out dod-trust-store.pem

# Create Kubernetes secret
kubectl create secret generic dod-trust-store \
  --from-file=dod-trust-store.pem \
  -n govern

Agency IdP (SAML/OIDC) Configuration

For GovCloud deployments where authentication flows through an agency IdP:

SAML Configuration

auth:
  provider: saml
  saml:
    metadataUrl: https://idp.agency.gov/saml/metadata
    entityId: https://govern.agency.gov
    assertionConsumerServiceUrl: https://govern.agency.gov/auth/saml/callback
    nameIdFormat: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
    attributeMapping:
      email: mail
      displayName: displayName
      role: memberOf  # LDAP group → GOVERN role mapping
    roleMapping:
      "CN=GOVERN-SOC-Analysts,OU=Groups,DC=agency,DC=gov": soc_analyst
      "CN=GOVERN-Admins,OU=Groups,DC=agency,DC=gov": platform_admin

OIDC Configuration (Azure Government)

auth:
  provider: oidc
  oidc:
    issuer: https://login.microsoftonline.us/$TENANT_ID/v2.0
    clientId: $AZURE_CLIENT_ID
    clientSecret: $AZURE_CLIENT_SECRET
    scopes: [openid, profile, email, User.Read]
    usernameClaim: preferred_username
    groupsClaim: groups
    requirePivClaim: true  # Require PIV method in token claims

Certificate Validation

GOVERN validates smart card certificates against the DoD Trust Store on every authentication:

Certificate chain validation to a trusted root CA
OCSP/CRL check (certificate not revoked)
Certificate policies check (id-fpki-common-authentication policy required)
Extended Key Usage check (clientAuth required)
Subject Alternative Name extraction (UPN or email for user matching)

Testing CAC/PIV Authentication

# Test authentication (from a workstation with CAC reader)
curl -v https://govern.agency.gov/auth/cac \
  --cert /path/to/cac-cert.pem \
  --key /path/to/cac-key.pem \
  --cacert dod-trust-store.pem

Troubleshooting

Issue	Cause	Resolution
Certificate chain error	DoD root not in trust store	Re-import DoD PKI bundle
OCSP timeout	No connectivity to OCSP server	Configure OCSP responder proxy or CRL fallback
User not found	UPN/email not in GOVERN	Provision user in GOVERN or configure auto-provisioning
Role not assigned	Group mapping missing	Add group → role mapping in auth config