SAML - SSL Client Certificate Authentication

The purpose of this document is to describe how to configure PhenixID server for federation with SAML2 using SSL Client Certificate authentication. Example SSL Client Certificates are SITHS and Telia. This authentication method can be used for any CA.

Prerequisites

  • PhenixID Server configured according to this instruction: "Federation - Username and password"

    Certificate infrastructure:
  • Create jks file and import trusted CA certificates file. Save jks file in <phenixid_server>/config folder.
    Make sure you not the jks file path and password.

  • A front end http server which handles the SSL termination must be installed and configured. The front end server must send the certificate data to the backend (PAS) server.
    NB! The communication between the front end server / LB / proxy and the PhenixID Authentication Services backend may be encrypted. The configuration example below describes an unencrypted communication between the front end server / LB / proxy and the PhenixID Authentication Services backend.
  • Howto setup ssl client certificate with Apache HTTP: https://httpd.apache.org/docs/current/ssl/ssl_howto.html
  • Howto setup ssl client certificate with Citrix Netscaler
    https://support.phenixid.se/sbs/netscaler-mutual-tls/
  • PAS must be configured with ssl=false for http communication.
  • Example:
  • PAS is setup on ip 52.16.27.23.
  • PAS is configured to listen to port 80 with SSL=false.
  • PAS needs the uri https://front-end-domain/saml/authenticate/siths to be protected by SSL client authentication (using a front-end such as Apache). The front end must proxy the traffic to the backend server (PAS).
  • Apache configuration example (from http-ssl.conf):

https://front-end-domain/saml/authenticate/siths

ProxyPass / http://52.16.27.23/

ProxyPassReverse / http://52.16.27.23/
<Location /saml/authenticate/siths>

SSLVerifyClient require

SSLVerifyDepth 10

# initialize the SSL headers to a blank value to avoid http header forgeries

RequestHeader set SSL_CLIENT_CERT ""
RequestHeader set SSL_CLIENT_VERIFY "
# add whatever SSL_* variables needed to pass to web application

RequestHeader set SSL_CLIENT_CERT "%{SSL_CLIENT_CERT}s"
RequestHeader set SSL_CLIENT_VERIFY "%{SSL_CLIENT_VERIFY}s"
RequestHeader add X-Forwarded-Scheme https

</Location>
Click to copy

Convert the Federation - Username and Password scenario to HeaderBasedCertificateSAML

Open the Advanced tab and locate the Authentication - HTTP entry that was configured in the previous "Federation - Username and password" scenario.

Change the value of the name parameter from "PostUidAndPasswordSAML" to "HeaderBasedCertificateSAML"

Click the plus sign next to "configuration" to add new parameters

Set "certificateheader" = "SSL_CLIENT_CERT"

Click Stage changes

Click Commit changes

Configure the execution flow to validate certificate

  1. Open the Execution flow tab and expand the flow.
  2. Delete the valve #1 (InputParameterExistsValidatorValve) and valve #3 (LDAPBindValve)
  3. Change the LDAPSearchValve filter to suit the user identifier value from the certificate attribute. (The attribute may differ depending on type of certificate)

Add a new valve, CertificateValidatorValve, after the LDAPSearchValve. This valve will perform the certificate revocation control.

Click Save