Authenticating clients

The IBM HTTP Server supports three levels of client authentication and two types of access control, based on client certificate information. This section discusses setting the desired client authentication level and the access control type, along with associated notes . Links to related information appear at the end of this section.

• Setting client authentication levels
• Setting access control types
• Finding related information

Setting client authentication levels

Set the level of client authentication with the SSLClientAuth directive:

• Required, (2)

• Optional, (1)

• None, (0)

You can add a second argument, crl, to use a certificate revocation list. For example, SSLClientAuth 1 crl

>Choosing the Required level

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 a trusted Certificate Authority root certificate in the local key database. A trusted Certificate Authority (CA) root certificate is a certificate signed by a certificate authority, 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 an expired certificate, or if a certificate authority (CA) that is not designated as a trusted CA on the server, signs the certificate.

SSL client authentication increases network traffic.

Choosing the Optional level

If you choose the Optional level of client authentication, the server requests a client certificate. If the client does not provide a certificate, the server still establishes a secure connection. The server denies the request if the client has provided an expired certificate, or if a certificate authority (CA) that is not designated as a trusted CA on the server, signs the certificate.

SSL client authentication increases network traffic.

Choosing None

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

Setting access control types

Set the access control type with the SSLFakeBasicAuth, or SSLClientAuthRequire directives.

The SSLClientAuthRequire directive is the preferred type of client authentication.

SSLFakeBasicAuth directive

Using the SSLFakeBasicAuth directive is not recommended. Password files generated for use with Apache SSL code, or mod_ssl and Apache, do not work with the IBM HTTP Server because of differing distinguished name formats.

The SSLFakeBasicAuth type provides a simple method for client authentication. If you specify SSLFakeBasicAuth, the client certificate distinguished name and the password ("password") are Base64-encoded and placed in the authorization header. Put the mod_ibm_ssl module first in the module list, so that subsequent authentication modules have the fake basic authentication user ID and password available. Basic authentication support within a specified virtual host does not work because the client distinguished name and the password, password, overwrite the user ID and password supplied by a user.

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

SSLClientAuthGroup directive

This directive enables you to specify a logic string of specific client certificate attributes and group them together as a single unit. This ability enables a certain set of client certificate attributes access to multiple objects on that server.

The syntax is SSLCLientAuthGroup (name) (expression)

Use parentheses to group comparisons. If the value of the attribute contains a non-alphanumeric character, delimit the value with quotes.

Valid attributes follow:

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

The following short names are also valid:

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

SSLClientAuthRequire directive

The more extensive SSLClientAuthRequire support enables the webmaster to define logical expressions containing the x509 attributes. Comparisons between these logical expressions and the client certificate information determine object access. Before processing occurs, GSK validates the client certificate to ensure that a trusted certificate authority signed the certificate.

The SSLClientAuthRequire directive enables a webmaster to build a logical expression consisting of attribute checks linked with AND, OR, and NOTs. You can also use parentheses. For example:

SSLClientAuthRequire (CommonName = "Fred Smith" OR CommonName = "John Deere") AND Org = IBM

For the attribute checks, the only valid comparisons are equal and not equal (= and !=). You can link each attribute check with AND, OR, or NOT (also &&, ||, and !). When you specify multiple SSLClientAuthRequire directives for one resource, the resource acts as if Boolean AND operators join the values.

Use parentheses to group comparisons. If the value of the attribute contains a nonalphanumeric character, delimit the value with quotes.

Valid attributes follow:

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

The following short names are also valid:

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

     (Back to the top)