10g (9.0.4)
Part Number B10663-01
 Home |
 Solution Area |
 Contents |
 Index |
| Oracle® Application Server Certificate Authority Administrator's Guide 10g (9.0.4) Part Number B10663-01 |
|
The Oracle Application Server Certificate Authority web administrative interface covers the following three broad areas, each accessible from a tab on the home page:
This chapter describes the first of those three areas: certificate management. The other two are described in Chapter 4, "Configuring Oracle Application Server Certificate Authority".
Some administrative operations require the command-line interface described in Appendix A, "Command-Line Administration". Two of these operations are starting and stopping Oracle Application Server Certificate Authority, as explained in later sections, along with requesting or replacing the administrator's certificate.
For end-user interactions with Oracle Application Server Certificate Authority, a separate web interface presents forms enabling personal certificate-related operations: see Chapter 7, "End-User Interface of the Oracle Application Server Certificate Authority".
The present chapter contains the following sections:
For security reasons, OCA's start and stop operations can only be done using the command-line tool ocactl, which requires the administrator's password. An example of using these operations appears in Replacing the Administrator Certificate. This tool is fully described in Appendix A, "Command-Line Administration".
Before OracleAS Certificate Authority can be started, the following five components must be operating or available:
If OCA is installed in a different $ORACLE_HOME from the other infrastructure components, then OHS and OCA's OC4J must be started separately, after the repository. Use this command in OCA's $ORACLE_HOME:
$ORACLE_HOME/opmn/bin/opmnctl startall
If a single $ORACLE_HOME contains all the infrastructure components, including OCA, then OHS and OC4J will already have been started, as in Section 4.3 above.
To start, stop, or restart Oracle Application Server Certificate Authority, enter the corresponding command from those shown below, on the command line:
$ORACLE_HOME/oca/bin/ocactl stop
$ORACLE_HOME/oca/bin/ocactl start
$ORACLE_HOME/oca/bin/ocactl status
You must have the administrator certificate before you can use any of the Oracle Application Server Certificate Authority administrative options and controls in the web interface. If you have the administrator password created during installation, this certificate is easy to get, and is the first step you must do before any other task.
In other systems, requesting, acquiring, and installing your administrator PKI certificate required a whole set of command-line, floppy disk, and cut-and-paste operations.
With Oracle Application Server Certificate Authority, however, the process is simple and easy:
To request the administrator certificate for your authentication, you simply fill in and submit a brief form that appears after Oracle Application Server Certificate Authority is started for the first time. You must be accessing Oracle Application Server Certificate Authority from the computer you intend to use as the administrator. Clicking the Certificate Management tab displays a Welcome page, followed by a form requesting your identifying data.
The form requires your common name, organization, and the Certificate Authority administrator password created during installation. You can also supply other DN information: your email address, organizational unit, locality, state, and country.
You can select the certificate key size (default: 1024) and the validity period (default: 1 year).
When the administrator certificate is issued, you import it into your browser. With this certificate in your browser, you can access the Certificate Authority facilities in the administration and configuration interfaces to manage certificate requests, certificate revocation or renewal, and policies.
This simple process -- easy importation after filling in a simple request-form -- replaces all the operations formerly required (before Oracle Application Server Certificate Authority) for PKI certificate acquisition and use.
To request your certificate, perform the following seven steps:
Launch your web browser and enter the URL and port number of the administration server as they were displayed at the end of installation. For example:
https://Oracle_HTTP_host:ssl_port/oca/admin
where oracle_HTTP_HOST as the host on which OCA is installed, and
ssl_port is listed in $ORACLE_HOME/install/portlist.ini under "Oracle Certificate Authority SSL Server Authentication port". For Windows, the path is $ORACLE_HOME\install\portlist.ini.
The screen displays a welcome page. Clicking the link provided there displays the form to request the administrator certificate.
Table 3-1 DN Information for the Administrator's Certificate
Text description of the illustration iekeystorchoicswcts.gif
Oracle Application Server Certificate Authority recommends using Microsoft Enhanced Cryptographic Provider for the Administrator Certificate. However, if readers for smartcards like Gemplus are available, they should be used; if no reader is installed, selecting smartcard suppliers like Gemplus or Schlumberger causes an error.
Now you have a client authentication certificate in the common name you specified.
At this point, you can perform any of the tasks available through the web interface of Oracle Application Server Certificate Authority, as described in Chapter 4, "Configuring Oracle Application Server Certificate Authority".
You may in future need to replace the administrator's certificate. Reasons could include the password to your private key being lost, the private key somehow being compromised or stolen, or the administrator role being given to someone new.
To replace the administrator certificate, you must stop the server, revoke the current administrator's certificate, and restart the server. These tasks are performed by using the command-line tool ocactl, which requires the OCA Administrator password. For security reasons, these commands are only enabled on the command line.
The administrator then navigates to the Oracle Application Server Certificate Authority web page and fills in the form presented for Web Administrator Enrollment, as described above in Requesting the Administrator Certificate.
Here are the three relevant command-line tasks:
$ORACLE_HOME/oca/bin/ocactl stop
$ORACLE_HOME/oca/bin/ocactl revokecert -type WEBADMIN -reason <REASON_CODE>
Note: You may choose any one of the following reason codes (separated by | ):
{KEY_COMPROMISE | CA_COMPROMISE | AFFILIATION_CHANGE | SUPERSEDED | CESSATION_OF_OPERATION | CERTIFICATE_HOLD | REMOVE_FROM_CRL | UNSPECIFIED}
For UNIX, enter $ORACLE_HOME/oca/bin/ocactl start
For Windows, enter %ORACLE_HOME%\oca\bin\ocactl start.
At this point, follow the instructions at Requesting the Administrator Certificate to obtain that certificate, enabling all administrative capabilities.
To perform administrative tasks you must have a valid administrator certificate. If your initial sign-in is as a regular user, rather than as administrator, you may get the error message described in Appendix C, "Known Troubleshooting Tips", in section 1. Prerequisite Issues and Warnings, item b. Issue: Cannot Log in as Administrator after Logging in as Normal User.
To access the Oracle Application Server Certificate Authority administration interface, launch your web browser. Enter the URL and port number of the administration server as they were displayed at the end of installation:
https://Oracle_HTTP_host:ssl_port/oca/admin
where oracle_HTTP_HOST as the host on which OCA is installed, and
ssl_port is listed in $ORACLE_HOME/install/portlist.ini under "Oracle Certificate Authority SSL Server Authentication port". For Windows, the path is $ORACLE_HOME\install\portlist.ini.
The Oracle Application Server Certificate Authority home page appears, presenting three additional subtabs, as the following figure shows:
These three subtabs enable you to address specific tasks in managing certificates or the Certificate Authority configuration:
The Certificate Management tab shows all the pending certificate requests, displaying a page that looks like the following:
Text description of the illustration certrqstlistxpnddrva.gif
This page enables the administrator to choose among the following tasks:
Oracle Application Server Certificate Authority maintains a master list of all certificate requests and their current status: pending, rejected, or certified. Upon entering the Certificate Management tab, all certificate requests needing action (pending) are displayed. The administrator is responsible for approving or rejecting such requests, for revoking or renewing certificates as needed, and for managing the Certificate Revocation List (CRL) generation.
In performing these tasks as the administrator, you can search the master lists of certificates or certificate requests by name or number, and then examine specific certificates or requests of interest.
You can then
You can specify this renewal-period window: see Chapter 5, "Managing Policies in Oracle Application Server Certificate Authority", in the following sections:
See Also:
All of these certificate management tasks are described in the sections that follow:
The starting screen of the Certificate Management tab displays a list of all pending certificate requests. To approve or reject one, follow the steps in the corresponding section below.
From the Certificate Management tab, you can select a certificate and view its details.
To select a single certificate, see "Listing a Single Certificate Request or Issued Certificate" .
To display a list of certificates, see "Using Advanced Search" .
From your search results, select the certificate you wish to review, and click View Details. The Certificate page appears, showing the certificate's detailed contents. (This page's buttons also enable you to revoke, renew, or import the selected certificate.)
As the administrator, you can revoke certificates, and should do so if one of the following situations occurs:
To find the target certificate, follow the instructions in "Listing a Single Certificate Request or Issued Certificate" or "Using Advanced Search" . Once you have selected the correct certificate, you can choose to review its detailed contents by clicking View Details, or revoke it with the following steps:
End-users who are using SSO or SSL authentication can also revoke their own certificates, as described in Certificate Revocation in Chapter 7, "End-User Interface of the Oracle Application Server Certificate Authority".
See also:
Notes:
ocactl command-line tool.
The administrator can renew a user certificate 10 days (default policy) before or after it expires, enabling it to continue to be used without interruption. (The administrator can alter the number of days allowed before and after expiration.) Expired certificates can be renewed during the number of days specified for the period before and after the expiration date. Once a certificate expires and is not renewed during this permitted period, it becomes unusable and must be replaced by submitting a new certificate request and having it approved.
To renew a certificate, the administrator selects it (see the sections on listing and searching), clicks View Details to display the Certificate page, and then clicks Renew. If the date is within the established window around the certificate's expiration date (default: 10 days before or after), the certificate can be renewed. Otherwise, an error message appears, regarding the established window.
For SSO- or SSL-authenticated renewal requests, the same policy governing user certificate renewals (RenewalCertificateRequestConstraints) is applied automatically. When Oracle Application Server Certificate Authority processes renewal requests from end entities, this policy sets the new validity period for the renewed certificate.
From the first page of the user web interface, the Oracle Application Server Certificate Authority administration interface allows you to display a specific certificate or certificate request. (To generate a list of certificates or requests that meet criteria you specify, see Using Advanced Search.)
To find a specific certificate or certificate request, do the following steps:
The Advanced Search feature enables you to use more complex search criteria to find and list multiple certificates or certificate requests, as follows:
From the results listed for a search, the administrator can select
In each type of search, after you specify your search parameters, click the Go button. Oracle Application Server Certificate Authority displays 25 records at a time.
To perform an advanced search for certificate requests or issued certificates:
The resulting page is structured in sections, each described below, so that you can choose the particular type of search you want, from the following choices:
For all search results, Oracle Application Server Certificate Authority displays 25 records at a time. To see more, use the Previous and Next buttons to navigate.
Use this section of the Advanced Search page to list certificate requests by status. From the drop down menu, select Pending, Rejected or Certified, and click Go. The list of certificate requests matching your status selection will display, 25 records at a time.
Use this section of the Advanced Search page to list certificates by a particular owner, which can be a server or an end-user. You can search by issued certificates or by requested certificates.
Use this section of the Advanced Search page to search for issued certificates (Certificate) or requested certificate (Certificate Request) by the distinguished name of the owner. You can enter the complete DN string instead of entering a value for each RDN string.
|
See Also:
The section entitled Domain Component Attributes in Appendix E, "Glossary". |
Use this section of the Advanced Search page to find all issued or requested certificates within a range of serial numbers. You can search by issued certificates or by requested certificates. Select one of those two choices, specify the lowest and highest serial number of interest, and click Go.
| Element Specifying Range | Meaning/Content of that Element |
|---|---|
|
Lowest Serial Number |
Enter the lowest serial number of the range |
|
Highest Serial Number |
Enter the highest serial number of the range |
Use this section of the Advanced Search page to find all valid, revoked, or expired certificates. Select one of those three choices and click Go.
Revoking a certificate should make it unusable in your environment. Making the fact of revocation publicly available ensures that revoked certificates are not misused. Publishing the list of revoked certificates, called the certificate revocation list (CRL), accomplishes this goal because entities granting authentication can first check this list. For example, all the applications in your trust environment can use the CRL to prevent authentication of a revoked certificate.
You generate an updated CRL by performing the following steps:
After filling in the form, click the Submit button. This action generates the CRL.
You can retrieve it for review or saving by choosing Download CRL then Import to Browser or Download to your local disk.
The Oracle HTTP Server uses this list to check the validity of the SSL certificates it receives, rejecting an SSL connection with any end-entity whose certificate is on the CRL. If your system uses multiple such servers, you will need to copy the CRL to the appropriate path and filename used by those servers as their CRL. Follow the steps established for each server in setting up its CRL.
Similarly, browser and email clients can verify servers they are connecting to, verifying incoming S/MIME email using these CRLs.
OCA and SSO complement each other in simplifying the provisioning of user certificates and using them to enable PKI authentication to all applications that use SSO. The two configuration choices described in this section can make this collaboration even easier:
The first configuration choice, broadcasting, makes it even easier for an SSO user to file a certificate request than it is using the default OCA configuration. OCA's default is to provide certificates when an SSO-authenticated user files a certificate request, a process that takes several steps. That process is described in the Single Sign-on Authentication (SSO) section of Chapter 7, "End-User Interface of the Oracle Application Server Certificate Authority".
Broadcasting makes it even easier by providing a link that can be sent to all users, enabling them to request an SSO/OCA certificate directly.
The second configuration choice is described in the section following that, Bringing SSO-Authenticated Users to the OCA Certificate Request URL. It explains an OCA configuration command that shortens that process considerably, by simplifying SSO configuration. SSO's default deployment does not automatically use SSL, which PKI authentication requires. So for SSO to leverage OCA-provided user certificates at run-time, SSO needs to be configured to use SSL and certificates. This second configuration choice, described in the second subsection below, details how this process can be further simplified, leveraging the usual configuration defaults.
The last two subsections are
They describe all the steps required for PKI authentication with OCA and SSO, and the process Single Sign-On uses for authentication.
The URL at which SSO users can get an OCA Certificate can be sent by email, as an embedded HTML link, or published as a link in the enterprise portal. These methods give you flexibility in publishing this capability to users who may need it.
This URL, for the SSO Certificate Request, is
https://<Oracle_HTTP_host>:<oca_ssl_port>/oca/sso_oca_link
in which the sender of such an email should of course replace <Oracle_HTTP_host> by the web or IP address of the host, and replace <oca_ssl_port> by the Oracle Certificate Authority SSL Server Authentication port number.
where oracle_HTTP_HOST is the host on which OCA is installed, and
oca_ssl_port is listed in $ORACLE_HOME/install/portlist.ini under "Oracle Certificate Authority SSL Server Authentication port". For Windows, the path is $ORACLE_HOME\install\portlist.ini.
Users can then click this link and do the same steps detailed in the next section, Bringing SSO-Authenticated Users to the OCA Certificate Request URL.
Although OCA is configured by default to act on SSO authentication, there are several steps. Users would still need to go to the OCA user interface, select SSO authentication, and then request the certificate. (See Chapter 7, "End-User Interface of the Oracle Application Server Certificate Authority", in the Single Sign-on Authentication (SSO) subsection.) Some users might find this process a bit difficult.
Therefore, Oracle Application Server Certificate Authority has a mechanism to simplify the user experience, by sending users directly to the OCA Certificate Request URL after authentication by the SSO server.
Oracle Application Server Certificate Authority can be configured to provide this URL to the SSO server, for display whenever SSO is not using a certificate to authenticate a user. After SSO authenticates such a user, it then displays the OCA screen enabling that user to request a certificate. After that certificate is created and imported into the user's browser, future authentication can simply use that certificate automatically. (It should be noted, however, that this pop-up screen is shown to all users whether they are interested or not, and to some it could seem an inconvenience.)
To configure OCA in this way, the administrator uses the ocactl command-line tool (with the administrator password) to issue the following command:
ocactl linksso
The administrator can also use the ocactl command-line tool (with the administrator password) to cancel the use of this URL through the SSO server, by issuing the following command:
ocactl unlinksso
Please note that these commands do not require OCA service to be shut down. However, the SSO server needs to be restarted for them to take effect, by using the following commands in the SSO server ORACLE_HOME:
$ORACLE_HOME/opmn/bin/opmnctl stopproc type=oc4j instancename=oca$ORACLE_HOME/opmn/bin/opmnctl startproc type=oc4j instancename=oca
After the ocactl linksso command is executed and the SSO server is restarted, the OCA welcome page will be displayed whenever SSO is not using a certificate to authenticate a user. That page looks like the following illustration:
When the SSO user clicks that "here" link, the OCA certificate request page appears:
Text description of the illustration scndssontscpaftrwlcom.gif
This composite illustration shows that SSO users must choose a key size and then click Submit once their choice is set as desired. (Clicking Revert changes the choice back to the default.) After the request is submitted, the key for this certificate is automatically generated (which can take a few minutes). Then the certificate is imported into Oracle Internet Directory and displayed to the user. After the user views the certificate information and clicks Import to Browser, the certificate is imported into the user's browser for automatic use.
After being PKI-enabled, the SSO server can use certificates to authenticate users for applications rather than requesting username and password. When a user chooses SSO authentication, the browser asks her to choose a certificate previously imported into the browser, after which the certificate enrollment form will show up directly.
You need to do certain steps to configure SSO to use certificates. These steps are fully described in the Oracle Application Server Single Sign-On Administrator's Guide:
Each time the administrator enables the SSO server to use SSL, the OCA virtual host must be re-registered with the SSL-enabled SSO server. All SSO-using applications must do so. Re-registration is done by using the single sign-on registration tool, ossoreg.jar. OCA's use of this tool is explained here; its general use for all Single Sign-On enabled applications is explained in Oracle Application Server Single Sign-On Administrator's Guide.
Running this tool on the machine hosting the SSO server generates OCA's mod_osso record in the osso.conf file, reflecting SSL settings on the single sign-on server, as follows:
Use a command of the following form (although on a single line) from the $ORACLE_HOME where OCA is installed:
$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar -oracle_home_path orcl_home_path -site_name site_name -config_mod_osso TRUE -mod_osso_url mod_osso_url -u userid [-virtualhost virtual_host_name] [-update_mode CREATE | DELETE | MODIFY] [-config_file config_file_path] [-admin_info admin_info] [-admin_id adminid]
Suppose that the OCA host name is myoca.mysite.com and the OCA server authentication port is 4400. The following steps accomplish the re-registration:
setenv ORACLE_HOME /sso_server/oracle_home setenv LD_LIBRARY_PATH $ORACLE_HOME/lib
$ORACLE_HOME/jdk/bin/java -jar $ORACLE_HOME/sso/lib/ossoreg.jar -oracle_home_path $ORACLE_HOME -site_name "my_oca_site_name" -config_mod_osso TRUE -mod_osso_url https://myoca.mysite.com:4400 -u root -config_file $ORACLE_HOME/Apache/Apache/conf/osso/oca/osso.conf
$ORACLE_HOME/opmn/bin/opmnctl restartproc type=ohs
After OCA is re-registered with the Single Sign-On server, users who have already authenticated to OCA using Single Sign-On can use their certificates as before.
New users can provision their certificates by using the OCA Certificate Request URL for SSO, as described in the sections referenced above.
Once SSO can recognize a user by means of a certificate, she can access applications, including OCA, either by username/password log-in or by certificate.
Thus, after a user logs in with username/password, follows the steps to create a certificate, and imports it into the browser, she can thereafter authenticate herself to SSO through PKI.
When the browser of a user presents a certificate to SSO, wanting authentication to use some application, SSO checks that certificate against the directory. If the certificate stored under the user's nickname (and optionally his subscriber name) matches the one presented by the browser, the authentication is successful.
The single sign-on server then supplies the application with a URLC token containing user information, enabling the application to redirect the user to the requested URL. The requested content can then be delivered.
Table 3-2 lists the installation default values and other information, including default locations and validity periods for several important wallets.
If you want to change the depth of Sub CA's, that is, the path length, then the CA signing wallet should be regenerated using the command line. Use ocactl as described in Appendix A, "Command-Line Administration", in the section entitled Generating a Sub CA Wallet from Oracle Application Server Certificate Authority.
However, once the CA is regenerated, all previously issued certificates would be invalid. So if you want to change the path length value, the CA signing wallet should be regenerated immediately after the install, as should all dependent wallets such as the SSL wallet.
Notes to Table 3-2:
ocactl generatewallet -type CA to regenerate the CA signing wallet. You can also change the validity period by renewing this certificate with the desired validity period.
ocactl generatewallet -type CASSL. It can be regenerated at any time, such as expiration, with a commandline option or replaced with an SSL wallet from a different CA, such as Verisign. This can be done to avoid the warning "CA certificate not trusted" when first connecting to OCA.
|
 Copyright © 2002, 2003 Oracle Corporation. All Rights Reserved. |
|