7
Signing On with Digital Certificates

Single sign-on with X.509 client certificates provides a stronger degree of security than simple authentication. It offers the benefit that partner applications are, by default, PKI enabled when the single sign-on server is PKI enabled.

This chapter contains the following topics:

• How Certificate-Enabled Authentication Works

• System Requirements

• Configuring the Single Sign-On System for Certificates

• Maintaining a Certificate Revocation List

How Certificate-Enabled Authentication Works

Figure 7-1 depicts the authentication flow for certificate-enabled sign-on.

Figure 7-1 Certificate-Enabled Single Sign-On

Text description of the illustration ssoag038.gif

1. The user tries to access a partner application.

2. The partner application redirects the user to the single sign-on server for authentication. As part of this redirection the browser sends the user's certificate to the login URL of the server (2a). If it is able to verify the certificate, the server returns the user to the requested application.

3. The application delivers content.

   Note: A user whose browser is configured to prompt for a certificate-store password may only have to present this password once depending upon how her browser is configured. If she logs out and then attempts to access a partner application, the browser passes her certificate to the single sign-on server automatically. This means that she never really logs out. To effectively log out, she must close her browser.

System Requirements

The following criteria must be met before certificate-enabled single sign-on can proceed:

• The single sign-on server and Oracle Internet Directory must be installed.

• The Oracle HTTP Server must have a valid server certificate installed.

• The client certificate DN must be chosen in such a way that it meets one of the following two criteria:
  • The DN of the user certificate is the same as the user DN in Oracle Internet Directory

  • The DN of the user certificate contains the user nickname and, optionally, the name of the realm that the user belongs to

• The certificate of the client certificate issuer must be installed as a trusted certificate on the single sign-on server.

• The certificate of the server certificate issuer must be installed as a trusted certificate in the user's browser.

Configuring the Single Sign-On System for Certificates

Certificate-enabled single sign-on is not a default option in OracleAS, and it must be configured manually. Before configuring certificate authentication, you must enable the single sign-on system for SSL. Perform the tasks in "Enabling SSL" in Chapter 9; then return to this section and configure the following components for certificates:

• Oracle HTTP Server

• Single Sign-On Server

• Oracle Internet Directory

Oracle HTTP Server

Configuring the Oracle HTTP Server for certificates consists of adding parameters to the ssl.conf file and, optionally, choosing the certificate authority that issues server and user certificates.

Setting SSL Parameters

To set the required SSL parameters, complete the following steps:

1. Go to ssl.conf, located at $ORACLE_HOME/Apache/Apache/conf.

2. In the SSL Virtual Host Context section of ssl.conf, add or edit the parameters listed in Table 7-1. At the same time, verify that the SSLEngine parameter has been set to on. This should have been done as part of configuring the Oracle HTTP Server for SSL.

   Table 7-1 HTTP Parameters for Certificate-Enabled Single Sign-On

   Parameter	Description
   SSLWallet	The location, or path, of the server wallet. The default location is $ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default. Note: the actual location of the Oracle home must be substituted for the variable. If OracleAS Certificate Authority is installed in the same Oracle home as OracleAS Single Sign-On, and you want to use this CA to issue certificates, the wallet location is $ORACLE_HOME/oca/wallet/ssl. See "Choosing a Certificate Authority" for details.
   SSLWalletPassword	Password for the server wallet
   SSLVerifyClient	The verification type for client certificates. These are the three types: none--SSL without certificates optional--server certificate only require--server and client certificates You must choose either optional or require.

Choosing a Certificate Authority

If you have OracleAS Certificate Authority installed and want to use this CA to issue certificates, edit ssl.conf to point to the desired Oracle CA wallet. You can either use the Oracle CA wallet described in Table 7-1 or have the Oracle CA issue a wallet that is specifically for the single sign-on server. If you choose the first option, copy the wallets that are in $ORACLE_HOME/oca/wallet/ssl to $ORACLE_HOME/Apache/Apache/conf/ssl.wlt/default. If you choose the second option, see Chapter 7 in Oracle Application Server Certificate Authority Administrator's Guide for instructions. The relevant section is "Server/SubCA Certificates Tab." This is a subsection of "User Certificates Tab." Once you obtain the wallet, edit ssl.conf to point to the wallet's location.

You may, of course, elect to use a third-party CA. In this case, too, you must edit ssl.conf to point to the wallet's location as explained in Table 7-1.

Using OracleAS Single Sign-On in conjunction with OracleAS Certificate Authority simplifies the certificate provisioning process. You can configure the Oracle CA to broadcast the URL for its UI to single sign-on users. Users can then use this link to request a single sign-on certificate that is automatically linked to their entry in Oracle Internet Directory.

Single Sign-On Server

Configuring the single sign-on server to accept certificates consists of these tasks:

• Configure the Server to Receive Parameters for Client Certificates

• Configure policy.properties with the Default Authentication Plugin

• Modify the Configuration File for the Authentication Plugin (Optional)

• Customize the User Name Mapping Module (Optional)

• Restart the Single Sign-On Middle Tier

Perform at least the first two. Add the other two if you want to customize the user name mapping module. The default module for user name mapping matches the distinguished name (DN) in the client certificate with a single sign-on user in Oracle Internet Directory. The default implementation assumes that the user's DN in the directory is the same as the certificate DN. A module that maps a field in the certificate DN to the user's name in Oracle Internet Directory is also available. If you want to substitute this module for the DN mapping module, modify the CertificateMappingModule parameter as prescribed in the third task.

Configure the Server to Receive Parameters for Client Certificates

1. Add these lines to the end of the sso_apache.conf file, found at $ORACLE_HOME/sso/conf:

   #Allow single sign-On server to receive client certificate parameters
   <IfModule mod_ossl.c>
     Oc4jExtractSSL on
     <Location /sso>
       SSLOptions +ExportCertData +StdEnvVars
     </Location>
   </IfModule>
   
   

2. Add this tag to the orion-web.xml file at $ORACLE_HOME/j2ee/OC4J_SECURITY/application-deployments/sso/web:

   <jazn-web-app runas-mode="true" />
   
   

   Place the tag before </orion-web-app>. This example orion-web.xml file shows the tag correctly placed:

   <?xml version="1.0"?>
   <!DOCTYPE orion-web-app PUBLIC "-//ORACLE//DTD OC4J Web Application 
   9.04//EN" "http://xmlns.oracle.com/ias/dtds/orion-web-9_04.dtd">
   
   <orion-web-app
      deployment-version="9.0.4.0.0"
      jsp-cache-directory="./persistence"
      temporary-directory="./temp"
   >
   <!-- 
   Uncomment this element to control web application class loader behavior.
   <web-app-class-loader search-local-classes-first="true"   
   include-war-manifest-class-path="true"/>
   -->
   <jazn-web-app runas-mode="true" />
   </orion-web-app>
   

Configure policy.properties with the Default Authentication Plugin

Update the DefaultAuthLevel section of the policy.properties file with the correct authentication level for certificate sign-on. You can find the file in $ORACLE_HOME/sso/conf. Set the default authentication level to this value:

DefaultAuthLevel = MediumHighSecurity

then, in the Authentication plugins section, pair this authentication level with the default authentication plugin:

MediumHighSecurity_AuthPlugin = oracle.security.sso.server.auth.SSOX509CertAuth

For your convenience, policy.properties is available in Appendix C.

Modify the Configuration File for the Authentication Plugin (Optional)

The X509CertAuth.properties file contains the parameters that follow. The file path is $ORACLE_HOME/sso/conf. (Omit this step if you are using the DN-based mapping module.)

CertificateMappingModule

This parameter is set to the class file that performs user name mapping. The parameter can have one of two default values:

oracle.security.sso.server.auth.SSOCertMapperDn

or

oracle.security.sso.server.auth.SSOCertMapperNickname

The first module assumes that the user's DN in the directory is the same as the certificate DN. This is the default, out-of-the-box setting. The second module assumes that the first cn value in the user certificate DN is the user nickname in the default realm of Oracle Internet Directory. If you want to substitute your own module for either of these modules, set the parameter to the class file name for your implementation.

CheckUserCertificate

This parameter indicates whether the user certificate must be verified in Oracle Internet Directory. The default value is true. If you deem the SSL protection provided by the Oracle HTTP Server to be sufficient, set this parameter to false.

CertificateAuthFailureUrl

If certificate authentication fails, the user is redirected to this URL, which displays an error message.

Customize the User Name Mapping Module (Optional)

To customize the user name mapping module, implement a mapping module based on oracle.security.sso.ias904.toolkit.IPASUserMappingInterface. Refer to the example mapping modules shipped with this release. Again, these modules are SSOCertMapperDN.java and SSOCertMapperNickname.java. (Omit this step if you are not writing your own mapping module.)

The example modules contain the following classes:

• Mapping module Interface

  This interface contains the following methods:

  public IPASUserInfo getUserInfo(
         javax.servlet.http.Http/ServletRequest request)
         throws IPASException;
  
  

• User information class

  This class contains user information such as the user nickname and user DN. The package name is oracle.security.sso.ias904.toolkit.IPASUserInfo. The constructor looks like this:

  Public IPASUserInfo(
         String userNickName
         String realmNickname)
  
  Public IPASUserInfo(
         String userNickName,
         String userDN,
         String userGUID,
         String realmNickname,
         String realmDN,
         String realmGUID)
  
  

• Exception class

  A problem with user name mapping raises this exception. The class name is oracle.security.sso.ias904.toolkit.IPASException. The super class is java.lang.Exception. The constructor looks like this:

  public IPASException()
  public IPASException(String Message)
  
  

1. Extract ipassample.jar, the file that contains the modules. See "Obtaining the Sample Files" in Chapter 2.

2. Create a Java class that implements the following interface:

   oracle.security.sso.ias904.toolkit.IPASUserMappingInterface
   
   

3. Compile your custom implementation:

   $ORACLE_HOME/jdk/bin/javac -classpath $ORACLE_HOME/sso/lib/
   ipastoolkit.jar:$ORACLE_HOME/lib/servlet.jar -d $ORACLE_HOME/
   sso/plugin java_file_name -d class_directory
   
   

4. Jar your class file and place it into $ORACLE_HOME/sso/plugin:

   $ORACLE_HOME/jdk/bin/jar -cvf $ORACLE_HOME/sso/plugin/CertMapImpl.jar -C 
   class_directory
   
   

   This step assumes that you do not have individual class files in the plugin directory, a condition that might cause class file duplication.

5. Update x509CertAuth.properties with your implementation. See "Modify the Configuration File for the Authentication Plugin (Optional)".

Restart the Single Sign-On Middle Tier

After configuring the server, restart the middle tier. See "Stopping and Starting the Single Sign-On Middle Tier".

Oracle Internet Directory

For certificate-based authentication to be successful, the user certificate must be present in Oracle Internet Directory. If the certificate is issued by OracleAS Certificate Authority, the certificate is published in the directory automatically. This may also be true if the CA is in-house. If the certificate issuer is a third-party CA, a self-service application can fulfill this function, or the directory administrator can try to add the certificate to the directory as an LDIF file, using the command-line tool ldapmodify.

If you use ldapmodify to publish the certificate, set the appropriate NLS language variable for your environment before running the tool. Here is an example:

• UNIX:

  setenv NLS_LANG AMERICAN_AMERICA.UTF8
  
  

• Windows NT/2000:

  set NLS_LANG=AMERICAN_AMERICA.UTF8
  
  

In UNIX, you may have to use a different procedure to set this variable if you are using a shell other than csh or tcsh.

ldapmodify is located in $ORACLE_HOME/bin. Here is the syntax for the tool:

ldapmodify -h host -p port -D "directory_administrator" -w password -f file_
name.ldif

In the example LDIF file that follows, the certificate of user jsmith is represented as an attribute of his entry in the directory. The attribute type is usercertificate. The attribute value is the long string that follows the attribute type.

dn: cn=jsmith,cn=users,dc=realm1,dc=oracle,dc=com
changetype: modify
replace: usercertificate
usercertificate::MIIC3TCCAkYCAgP3MA0GCSqGSIb3DQEBBAUAMIG8MQswCQ       	
YDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEXMBUGA1UEBxMOUmVkd29vZCBTaG9yZXMxGzAZBg
NVBAoTEk9yYWNsZSBDb3Jwb3JhdGlvbjEfMB0GA1UECxMWV2ViIFNpbmdsZSBTaWduLU9uLCBTVDEeMB
wGA1UEAxMVQ2VydGlmaWNhYoEHmF4gomtc4mxSKh/zAgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAKwXoCL
DRqmK1Y9LQtIjLnCaIJKUZmS1Qj+bhu/IHeZLGHg4TJg3O2XVA5u/VxwjLeGBqLXy2z7o3RujNKx2CVx
6p/0Hkjnw4w6KVau2hcBgC9m4kzUGhHJ9b65v/zx7dIUKyJr4RF+lJhJg4/oYXxLrYHp5NAkHP4htT0g
qCXiI=

Because it is a non-ASCII value, the certificate must be encoded in base 64 format, as shown here. Unlike other attributes, a base 64 attribute requires a double colon (::) as a delimiter. Note, too, that the use of a tab enables a base 64 attribute to be folded.

Maintaining a Certificate Revocation List

To ensure that users are unable to log in using invalid or expired certificates, the administrator must maintain an up-to-date certificate revocation list (CRL) on the Oracle HTTP Server. The CA that issued the certificate must provide this list. The ca-bundle.crl file can be used to maintain it. The path to the CRL file must be $ORACLE_HOME/Apache/Apache/conf.

OracleAS users who use digital certificates to authenticate must not be able to update the userCertificate attribute in their directory entry. The reason is the potentially long lapse time between the revocation of a certificate and the update of the CRL. Note that Oracle Internet Directory, by default, denies the user access to userCertificate. It should be modified only by trusted entities such as the single sign-on server, OracleAS Certificate Authority, or a third-party certificate authority.

For details about implementing and maintaining a CRL, see comments in the SSL Virtual Host Context section of ssl.conf.