4
Single Sign-On Using Digital Certificates

Single Sign-On using simple authentication poses a serious security risk. If hackers can access a Single Sign-On account, they can access numerous applications and do untold damage. Fortunately, Single Sign-On users have the option of using digital certificates instead of the Single Sign-On user name and password to authenticate. This form of authentication involves an exchange of X.509 certificates between client and server over Secure Sockets Layer (SSL).

This chapter covers the following topics:

• Benefits of Certificate-Enabled Single Sign-On

• Authentication Options

• Authentication Flow in Certificate-Enabled Single Sign-On

• System Requirements

• Configuring Single Sign-On for Certificates

• Troubleshooting Certificate-Enabled Single Sign-On

• Maintaining a Certificate Revocation List

Benefits of Certificate-Enabled Single Sign-On

Certificate authentication offers the benefit that partner applications are, by default, PKI enabled when the Single Sign-On Server is PKI enabled. As in Single Sign-On without certificates, these applications rely on cookies for authentication. Retrieving and checking a cookie requires less computing overhead than performing an SSL handshake. For Web applications characterized by short-lived sessions, the result is a significant improvement in server performance and throughput.

Authentication Options

Oracle Single Sign-On can be configured for SSL both with and without client certificates. The first option, server-side authentication, offers a strong degree of security. Still, the user's password is vulnerable to attack--either by guesswork or by brute force. Certificate-based authentication on both client and server sides, on the other hand, makes it difficult to sniff or modify data or to impersonate the client or server.

Authentication Flow in Certificate-Enabled Single Sign-On

Figure 4-1 depicts the authentication flow for certificate-enabled Single Sign-On.

Figure 4-1 Certificate-Enabled Single Sign-On

Text description of the illustration ssoag005.gif

1. The Single Sign-On user tries to access a partner application.

2. The partner application redirects the user to the Single Sign-On server for authentication. The server must be configured so that, at the very least, it asks for optional client certification.

3. If the server has been configured for SSL, the SSL handshake occurs. The browser prompts the user for a password that opens the browser certificate and key database. The browser then sends the user's certificate to the login URL of the Single Sign-On server.

4. Mod_ossl, the SSL module on the Single Sign-On server, passes the user's certificate information to a PL/SQL module that maps the user's nickname and, optionally, his subscriber name.

5. The mapping module passes the mapped user name and optional subscriber name to an authentication module.

6. The authentication module uses the mapped user name to retrieve the user certificate stored in the directory; then it compares this certificate with the browser certificate received from mod_ossl.

7. If the two certificates match, the Single Sign-On server signifies that authentication has been successful by passing a URLC token that contains user information to the application.

8. The application redirects the user to the requested URL, which then delivers content.

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, Oracle9iAS, Release 2, 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 contains some information about the Single Sign-On user name, or nickname, and, optionally, the subscriber name for this user name. The cn attribute within the DN, for instance, might be the user's nickname (cn=jsmith). An o attribute might be the user's subscriber name (o=acme).

• 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 Single Sign-On for Certificates

Certificate-enabled Single Sign-On is not a default option in Oracle9iAS, and it must be configured manually. The follow components may require configuration:

• Oracle HTTP Server (SSL)

• Mod_plsql

• User Name Mapping Module

• Oracle Internet Directory

• Single Sign-On Server

Oracle HTTP Server (SSL)

To configure the Oracle HTTP server, navigate to the server configuration file, using the following path:

IAS_HOME/Apache/Apache/conf/httpd.conf

In the SSL Virtual Host Context section of the httpd.conf file, add the parameters listed in Table 4-1:

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

Parameter	Description
ServerName	The name of the server to be enabled for SSL
SSLEngine [on | off]	Setting the SSLEngine parameter to on enables the server for SSL
SSLWallet file:	The location, or path, of the server wallet
SSLVerifyClient	The verification type for client certificates. The options are as follows: none--SSL without certificates optional--server certificate only require--server and client certificates

When configured properly, the SSL Virtual Host Context section of the httpd.conf file looks like this:

## SSL Virtual Host Context
##
#
# file otherwise your virtual host will not respond to SSL requests.
#

<VirtualHost _default_:443>
#  General setup for the virtual host
DocumentRoot "/ade/lkethana_iasdemo/oracle/work/Apache/Apache/htdocs"
ServerName eastsun5.us.oracle.com
ServerAdmin you@your.address
ErrorLog /pivate/oracle/work/Apache/Apache/logs/error_log
TransferLog /private/oracle/work/Apache/Apache/logs/access_log

#   SSL Engine Switch:
#   Enable/Disable SSL for this virtual host.
SSLEngine on

#   Server Wallet:
#   The server wallet contains the server's certificate, private key
#   and trusted certificates. Set SSLWallet at the wallet directory
#   using the syntax:  file:<path-to-wallet-directory>

SSLWallet file:/private/iAS/wallet

#   Certificate Revocation Lists (CRL):
#   Set the CA revocation path where to find CA CRLs for client
#   authentication or alternatively one huge file containing all
#   of them (file must be PEM encoded)
#   Note: Inside SSLCARevocationPath you need hash symlinks
#         to point to the certificate files. Use the provided
#         Makefile to update the hash symlinks after changes.
#SSLCARevocationPath /private/oracle/Apache/Apache/conf/ssl.crl
#SSLCARevocationFile /private/oracle/Apache/Apache/conf/ssl.crl/ca-
 bundle.crl
#   Client Authentication (Type):
#   Client certificate verification type and depth.  Types are
#   none, optional, require and optional_no_ca.  Depth is a
#   number which specifies how deeply to verify the certificate
#   issuer chain before deciding the certificate is not valid.
SSLVerifyClient optional

</VirtualHost>

Mod_plsql

Configuring the plsql module for certificate-based authentication entails adding environment variables to the database access descriptor (DAD) for the Single Sign-On server. To add these variables, navigate to the DAD configuration file, using the following path:

IAS_HOME/Apache/modplsql/conf/dads.conf

In the dads.conf file, add the PlsqlCGIEnvironmentList parameter and the variables in Table 4-2.

Table 4-2 dads.conf Environment Variables

Variable	Description
SSL_CLIENT_S_DN_CN	The user's nickname, represented by the attribute cn (common name)
SSL_CLIENT_S_DN_O	The subscriber name associated with the user, if any. The subscriber name is represented by the attribute O (organization)
SSL_CLIENT_S_DN	The distinguished name of the user
SSL_CLIENT_CERT	The client certificate in base 64 format

Mod_plsql must pass these variables to the user name mapping module.

When configured properly, the relevant section of the dads.conf file looks something like this:

<IfModule mod_plsql.c>
<Location /pls/orasso>
  SetHandler pls_handler
  Order deny,allow
  PlsqlDatabaseConnectString    host:port:database_sid
  PlsqlDatabasePassword         orasso
  PlsqlDatabaseUsername         orasso
  PlsqlDefaultPage              orasso.home
  PlsqlDocumentTablename        orasso.wwdoc_document
  PlsqlDocumentPath             docs
  PlsqlDocumentProcedure        orasso.wwdoc_process.process_download
  PlsqlEnableConnectionPooling  On
  PlsqlAuthenticationMode       SingleSignOn
  PlsqlPathAlias                url
  PlsqlPathAliasProcedure       orasso.wwpth_api_alias.process_download
  PlsqlSessionCookieName        orasso
  PlsqlCGIEnvironmentList       SSL_CLIENT_S_DN_CN,SSL_CLIENT_S_DN_O,SSL_CLIENT_
  S_DN, SSL_CLIENT_CERT
</Location>

<IfDefine SSL>
<Location /pls>
  SSLOptions +ExportCertData +StdEnvVars
</Location>
</IfDefine>

User Name Mapping Module

The user name mapping module, which consists of the files ssodnmap.pks and ssodnmap.pkb, is located in the following directory:

IAS_HOME/sso/admin/plsql/sso

If the user accepts the default implementation for the package, no file configuration is required. The default implementation assumes that the user's DN in the directory is the same as the certificate DN. The files ssodnmap.pkb and ssodnmap.pks are reproduced here for those who want to customize the module.

/*  Copyright (c) Oracle Corporation 2001. All Rights Reserved. */

create or replace package body wwsso_map_dn
as

/* Global Variable */
g_user_certificate_dn  varchar2(2000) default null;

/**
 * This function reverses order of a given DN
 */
function reverse_dn(p_dn in varchar2 )
 return varchar2
is
 l_rdns   dbms_ldap.string_collection;
 l_rdn    varchar2(500);
 l_rev_dn varchar2(2000);
 l_index  pls_integer;
begin
 if(p_dn is null) then
     return null;
 end if;
 l_rdns  :=  dbms_ldap.explode_dn(p_dn, 0);
 l_index := l_rdns.first;
 loop
     exit when l_index is null;
     l_rdn    := l_rdns(l_index);
     l_rev_dn := l_rdn || ',' ||l_rev_dn;
     l_index  := l_rdns.next(l_index);
  end loop;
  l_rev_dn := substr(l_rev_dn, 0, length(l_rev_dn) -1);
  return l_rev_dn;
end reverse_dn;


/**
 * Get header list
 */
procedure get_headers
(
  p_header_list out header_collection
)
as
begin
  /* Set header name for certificate DN */
  p_header_list.delete;
  p_header_list(0) := 'SSL_CLIENT_S_DN';
end get_headers;

/**
 * Set value for given headers
 */
procedure set_header_values
(
   p_header_value_list in header_value_collection
)
as
begin
   /* Set certificate DN value */
   g_user_certificate_dn := p_header_value_list(0);
end set_header_values;

/**
 * Map SSO user from user certificate information
 *
 */
 procedure map_name
 (
    p_sso_user        out varchar2
  , p_subscriber      out varchar2
 )
 as
 begin
   /* You may change this default implementation according to your
    * requirements.
    *
    * In this simple mapping example, we will assume that
    * user certificate DN is same as directory DN
    */

   -- SSO USER INFORMATION --
   -- Set SSO User DN  from certificate attribute
   -- Note: certificate DN value send b yApache/mod_ossl is just
   -- reverse order of directory DN
   p_sso_user := reverse_dn(g_user_certificate_dn);

   -- SUBSCRIBER INFORMATION --
   -- Set subscriber name to null
   -- Note: subscriber information for this user can be retrieved
   --       from directory
   p_subscriber := null;

 end map_name;

end wwsso_map_dn;
/

show errors package body wwsso_map_dn;



/*  Copyright (c) Oracle Corporation 2001. All Rights Reserved. */
create or replace package wwsso_map_dn
as
/**
 * ssodnmap.pks
 *
 * Description:
 *    This package maps SSO username and subscriber name
 *    from user certificate information
 *
 * Configuration setup:
 *
 *  1. A copy of user certificate for this user should be
 *     stored  the userCertificate directory attribute for successful
 *     authentication
 *
 *  2. SSO DAD configuration(dads.conf) should have following entry:
 *      PlsqlCGIEnvironmentList = SSL_CLIENT_S_DN_CN, SSL_CLIENT_S_DN_O,
        SSL_CLIENT_S_DN, SSL_CLIENT_CERT
 *
 *  3. SSO DAD should be able to get SSL variables with following
 *     Apache configuration setting(dads.conf file):
 *
 *     <IfDefine SSL>
 *      <Location /pls/<sso_dad_name>>
 *        SSLOptions +ExportCertData +StdEnvVars
 *      </Location>
 *     </IfDefine>
 *
 *  Please refer to the SSO Server administration guide for detailed
 *  information
 */

/**
 *  Exception list
 */

 CERT_DN_MAPPING_EXCEPTION    exception;
 INVALID_HEADER_EXCEPTION     exception;

/**
 * These data structures are used to hold a list of values
 */

  type header_collection is table of varchar2(100)
    index by binary_integer;

  type header_value_collection is table of varchar2(5000)
      index by binary_integer;


/**
 *  Get header list
 *  This procedure returns required CGI headers for name mapping
 *
 * <template>
 *   wwsso_map_dn.get_headers(
 *      p_header_list   ==> -- out header_collection
 *      );
 * </template>
 *
 * <code>
 *   wwsso_map_dn.get_headers
 *   (
 *      p_header_list   ==> -- out header_collection
 *   );
 * </code>
 *
 *  @return p_header_list => list of headers
 *
 *  This procedure is used to specify required CGI variable names
 *  necessary for mapping module to map SSO user and subscriber name
 */
procedure get_headers
(
  p_header_list out header_collection
);

/**
 *  Set value for given headers
 *  This procedure sets required CGI headers  necessary
 *  for name mapping
 *
 * <template>
 *   wwsso_map_dn.set_header_values(
 *      p_header_value_list  ==> -- out header_value_collection
 *      );
 * </template>
 *
 * <code>
 *   wwsso_map_dn.set_header_values
 *   (
 *      p_header_value_list   ==> -- out header_value_collection
 *   );
 * </code>
 *
 *  @return p_header_value_list  => list of header values
 *
 *  This procedure is used set required CGI header values
 *  necessary for mapping module to map SSO user and subscriber name
 */

procedure set_header_values
(
   p_header_value_list in header_value_collection
);

 /**
 * Map user and subscriber name
 *
 * This procedure will map SSO username and subscriber name
 * from user certificate information, received from Apache/mod_ossl.
 *
 * <template>
 *   wwsso_map_dn.map_name(
 *      p_sso_user   ==> -- out varchar2
 *      p_subscriber ==> -- out varchar2
 *      );
 * </template>
 *
 * <code>
 *   wwsso_map_dn.map_name
 *   (
 *      p_sso_user    ==> Mapped SSO user name
 *    , p_subscriber  ==> Mapped subscriber name
 *   );
 * </code>
 *
 * @return     p_sso_user   => Mapped sso username
 * @return     p_subscriber => Mapped subscriber name
 *
 * @exception  CERT_DN_MAPPING_EXCEPTION
 *             This exception is raised if user information
 *             can not be mapped correctly
 *
 * If browser certificate DN is same as directory DN then
 * p_sso_user should be set to the directory DN and
 * subscriber name should be set to null since subscriber
 * information will be retrieved from directory.
 * Please note that the certificate DN received from
 * Apache/mod_ossl may be in the reverse order of directory DN
 *
 * If SSO username is mapped from certificate DN and mapped
 * subscriber name is set to null then the default
 * subscriber will be used to authenticate the user
 *
 * User certificate received from Apache/mod_ossl
 * will be checked against certificate stored in the
 * userCertificate directory attribute of the mapped
 * SSO user.
*/

 procedure map_name
 (
    p_sso_user        out varchar2
  , p_subscriber      out varchar2

 );
end wwsso_map_dn;
/

show errors package wwsso_map_dn;

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 an in-house certificate authority or by the Oracle CA, it might be possible to publish the certificate in the directory automatically. If the certificate issuer is a third-party CA, a self-service application can fulfill this function.

To determine whether a self-service application is feasible, the directory administrator can try to add the certificate to the directory as an LDIF file, using the command-line tool ldapmodify.

The syntax for this command is as follows:

ldap -h host -p 389 -D "cn=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.

dn: cn=jsmith,o=oracle,dc=com
changetype: modify
replace: usercertificate
usercertificate::MIIC3TCCAkYCAgP3MA0GCSqGSIb3DQEBBAUAMIG8MQswCQ
YDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEXMBUGA1UEBxMOUmVkd29vZCBTaG9yZXMxGz
AZBgNVBAoTEk9yYWNsZSBDb3Jwb3JhdGlvbjEfMB0GA1UECxMWV2ViIFNpbmdsZSBTaWduLU9uLC
BTVDEeMBwGA1UEAxMVQ2VydGlmaWNhYoEHmF4gomtc4mxSKh/zAgMBAAEwDQYJKoZIhvcNAQEEBQ
ADgYEAKwXoCLDRqmK1Y9LQtIjLnCaIJKUZmS1Qj+bhu/IHeZLGHg4TJg3O2XVA5u/VxwjLeGBqLX
y2z7o3RujNKx2CVx6p/0Hkjnw4w6KVau2hcBgC9m4kzUGhHJ9b65v/zx7dIUKyJr4RF+lJhJg4/o
YXxLrYHp5NAkHP4htT0gqCXiI=

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.

Single Sign-On Server

To enable the SSO server for SSL, all references to HTTP in SSO URLs must be changed to HTTPS. The script ssocfg.sh is provided for this purpose.

To run ssocfg.sh:

1. Go to the directory that contains the script. The path is as follows:

   IAS_HOME/sso/bin
   

2. Enter the command, using the following syntax:

   ssocfg.sh protocol host port [sso_schema_name]
   
   

In this case, protocol is https. (To change back to HTTP, use http.) The parameter new_host is the host name of the HTTP listener for the Single Sign-On server. You can either assign a new host name or use an existing one. The parameter new_port is the port number of the listener, and sso_schema_name is the name of the SSO schema. The default schema name is orasso. This last parameter is optional.

Here is an example:

ssocfg.sh https login.acme.com 443

Port 443 is the default port number for single sign-on over SSL.

Troubleshooting Certificate-Enabled Single Sign-On

Use Table 4-3 to identify and solve problems that you are likely to face when configuring Oracle Single Sign-On for certificates.

Table 4-3 Troubleshooting Checklist for Certificate-Enabled Single Sign-On

Problem	Cause	Solution
The user tries to access a partner application over SSL and is presented with the error message "Network Error: Connection Refused"	The SSLEngine on parameter is missing from the httpd.conf file or has not been entered correctly	Add the missing parameter as specified in "Oracle HTTP Server (SSL)". If the parameter is present and is entered correctly, see if the Apache error log file identifies the problem. This file can be found at IAS_HOME/Apache/Apache/logs/ error_log
The Single Sign-On login page fails to prompt the user for a certificate	The SSLVerifyClient optional parameter is missing from the httpd.conf file or has not been entered correctly	Add the missing parameter as specified in "Oracle HTTP Server (SSL)". If the parameter is present and is entered correctly, see if the Apache error log file identifies the problem. This file can be found at IAS_HOME/Apache/Apache/logs/ error_log
Certificate authentication fails to work, and the user is presented the login page.	This problem has three possible causes: PlsqlCGIEnvironmentList variables are missing from the dads.conf file PlsqlCGIEnvironmentList variables are being used improperly in the user name mapping module The user's certificate is missing from the directory or has been entered incorrectly	Add the missing variables to the dads.conf file as specified in the section "Mod_plsql". Check the formatting and spelling of variables in the file ssodnmap.pkb. This file is reproduced in the section "User Name Mapping Module". Reenter the user's certificate into the directory, as specified in the section "Oracle Internet Directory"

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, and the CA that issued the certificate must provide this list. The file ca-bundle.crl can be used to maintain the list. At any rate, the path for the CRL file used must be as follows:

/private/oracle/Apache/Apache/conf/ssl.crl

For details about implementing and maintaining a CRL, see comments in the httpd.conf file. The file is reproduced in the section "Oracle HTTP Server (SSL)".