Apache Module mod_authn_cert

Description:	Allows client certificate fields to be used for authentication
Status:	Extension
Module Identifier:	authn_cert_module
Source File:	mod_authn_cert.c

Summary

This module accepts client certificate credentials in lieu of HTTP basic authentication usernames and passwords. If no client certificate is provided, the server falls back to whatever configured AuthBasicProvider is specified.

Topics

Example configuration
SSL Client Certificate variables

Example configuration

<location /secure>
  # a basic auth config
  authtype basic
  authbasicprovider file
  authname "my realm"
  authuserfile /etc/myrealm.passwd
  require valid-user

  # enable mod_authn_cert processing 
  certificateusername on
 
  # expression to derive http username from certificate
  certificateusernameexpression "%{ssl_client_cn}"
</location>

<location /secure-no-auth>
  # r->user / REMOTE_USER will be set for modules to look at despite no authentication.  Requires PH29569
  certificateusername on
  certificateusernameexpression "%{ssl_client_cn}"
</location>

SSL Client Certificate variables

For convenience, the SSL client certificate related variables from https://www.ibm.com/support/knowledgecenter/en/SSEQTJ_9.0.0/com.ibm.websphere.ihs.doc/ihs/rihs_clcertenvvar.html are reproduced below. SSL_CLIENT_DN and SSL_CLIENT_CN are natural inputs into the expression used to form an HTTP username from a client certificate.

SSL client certificate environment variable	Description	Value
SSL_CLIENT_C	Contains the client certificate country	String
SSL_CLIENT_CERTBODY	Contains the client certificate	This value is the unformatted body of the client certificate, if a certificate was provided by the client
SSL_CLIENT_CERTBODYLEN	Contains the length of the client certificate	Integer
SSL_CLIENT_CN	Contains the client certificate common name	String
SSL_CLIENT_DN	Contains the distinguished name from the client certificate	String
SSL_CLIENT_EMAIL	Contains the client certificate e-mail	String
SSL_CLIENT_IC	Contains the country name of the client certificate issuer	String
SSL_CLIENT_ICN	Contains the common name of the client certificate issuer	String
SSL_CLIENT_IDN	Contains the distinguished name of the client certificate issuer	String
SSL_CLIENT_IEMAIL	Contains the e-mail address of the client certificate issuer	String
SSL_CLIENT_IL	Contains the locality of the client certificate issuer	String
SSL_CLIENT_IO	Contains the organization name of the client certificate issuer	String
SSL_CLIENT_IOU	Contains the organizational unit name of the client certificate issuer	String
SSL_CLIENT_IPC	Contains the postal code of the client certificate issuer	String
SSL_CLIENT_IST	Contains the state or province of the client certificate issuer	String
SSL_CLIENT_L	Contains the client certificate locality	String
SSL_CLIENT_NEWSESSIONID	Indicates whether this session ID is new	String. This value must be TRUE or FALSE.
SSL_CLIENT_O	Contains the client certificate organization	String
SSL_CLIENT_OU	Contains the client certificate organizational unit	String
SSL_CLIENT_PC	Contains the client certificate postal code	String
SSL_CLIENT_SERIALNUM	Contains the client certificate serial number	String
SSL_CLIENT_SESSIONID	Contains the session ID	String
SSL_CLIENT_ST	Contains the client certificate state or province	String

CertificateUserName Directive

Description:	Enables processing by this module
Syntax:	`CertificateUserName OFF\|ON`
Default:	`OFF`
Context:	virtual host, directory
Status:	Extension
Module:	mod_authn_cert

If set to "ON" and a client certificate is provided, the CertificateUsernameExpression will be used to authenticate the user.

CertificateUsernameExpression Directive

Description:	Instructs this module how to map a distinguished name to a HTTP username
Syntax:	`CertificateUsernameExpression expression`
Default:	`disabled`
Context:	virtual host, directory
Status:	Extension
Module:	mod_authn_cert

This directive determines which certificate data is used to construct the HTTP username. The parameter is an expression as described in the ap_expr documentation. The expression must resolve to a non-empty string to pass authentication.