Client authentication

The server supports three levels of client authentication and two types of access control based on client certificate information.

Level of client authentication

The level is set with the SSLCLientAuth directive:

If you choose "required"...

If you choose the required level of client authentication, the secure server requests a certificate from all clients making an https request. The server validates clients by checking for trusted CA root certificates in the local key database. A trusted CA root certificate is a certificate signed by a certificate authority who is designated as a trusted CA on your server.

The server establishes a secure connection if the client has a valid certificate. The server denies the request if the client has a certificate that has expired or if the certificate is signed by a certificate authority (CA) that is not designated as a trusted CA on the server.

Keep in mind that SSL client authentication increases network traffic.

If you choose "optional"...

If you choose the optional level, the server requests a client certificate. If the client does not provide one, a secure connection is still established. The server denies the request if the client has provided a certificate that has expired or if the certificate is signed by a certificate authority (CA) that is not designated as a trusted CA on the server.

Keep in mind that SSL client authentication increases network traffic.

If you choose "none"...

If you choose none, the secure server does not request certificates from clients.

Types of access control based on client certificate information

The type is set with the SSLFakeBasicAuth or SSLClientAuthRequire directives.

Note: SSLClientAuthRequire is the preferred type of client authentication.

SSLFakeBasicAuth directive

The use of SSLFakeBasicAuth is not recommended. Password files that were generated for use with Apache SSL code (or mod_ssl and Apache) will not work with IBM HTTP Server because the format of the distinguished name is different.

SSLFakeBasicAuth type is a very simplistic method for performing client authentication. If you specify SSLFakeBasicAuth, the client certificate's distinguished name and the password (which is "password") are Base64-encoded and placed in the authorization header. The mod_ibm_ssl module needs to be the first module in the module list, so that subsequent authentication modules will have the fake basic authentication user ID and password available. Be aware that basic authentication support within a specified virtual host will not work, because the user ID and password supplied by a user will be overwritten by the client's distinguished name and the password (which is "password.")

To display the distinguished name from a client certifcate, create a CGI program to print out the SSL_CLIENT_DN environment variable.

SSLClientAuthRequire directive

The more extensive SSLClientAuthRequire support allows the webmaster to define logical expressions containing the x509 attributes. These logical expressions are then compared with the client certificate information in order to either grant or deny access to an object. Before all of that processing can occur, however, GSK first validates the client certificate to ensure that it has been signed by a trusted certificate authority.

The SSLClientAuthRequire directive allows a webmaster to build a logical expression consisting of attribute checks linked with AND, OR, and NOTs. Parentheses are also allowed. For example:

SSLClientAuthRequire (CommonName = "Fred Smith" OR CommonName = "John Deere") AND Org = IBM
means that the object will not be served unless the client certificate contains a common name of either Fred Smith or John Deere and the organization must be IBM.

For the attribute checks, the only valid comparisons are equal and not equal (= and !=). Each attribute check can be linked with AND, OR, or NOT (also &&, ||, and !). When multiple SSLClientAuthRequire directives are specified for one resource, the effect on the resource is as if the values are joined by Boolean AND operators.

Parentheses can be used to group comparisons. If the value of the attribute contains a non-alphanumeric character, the value must be delimited with quotes.

Valid attributes are as follows:

     IssuerStateOrProvince 
     IssuerCommonName 
     IssuerOrgUnit 
     IssuerCountry 
     IssuerLocality 
     IssuerOrg 
     IssuerEmail 
     StateOrProvince 
     CommonName 
     OrgUnit 
     Country 
     Locality 
     Org 
     Email 

Also valid are the short names:

     IST, ICN, IOU, IC, IL, IO, IE, ST, CN, OU, C, L, O, E 

Related information