14.3. Opening Subsystem Consoles and Services

Each subsystem has different interfaces for different user types to access. All subsystems have some kind of web services page for agents, administrators, or end users (or all three), with the exception of the TKS. Additionally, the CA, KRA, OCSP, and TKS all have a Java-based Console, which must be installed on a server, to perform administrative tasks to manage the subsystem itself.
The appearance and, to a limited extent, functionality of the subsystem's web-based services pages can be customized to better integrate with an organization's existing websites. See Red Hat Certificate System Planning, Installation, and Deployment Guide.

14.3.1. Finding the Subsystem Web Services Pages

The CA, KRA, OCSP, TKS, and TPS subsystems have web services pages for agents, regular users, and administrators. These menu of web services can be accessed by opening the URL to the subsystem host over the subsystem's secure end user's port. For example, for the CA: 
https://server.example.com:8443/ca/services
The main web services page for each subsystem has a list of available services pages; these are summarized in Table 14.1, “Default Web Services Pages”. To access any service specifically, access the appropriate port and append the appropriate directory to the URL. For example, to access the CA's end entities (regular users) web services: 
https://server.example.com:8443/ca/ee/ca
If DNS is properly configured, then an IPv4 or IPv6 address can be used to connect to the services pages. For example: 
https://1.2.3.4:8443/ca/services
https://[00:00:00:00:123:456:789:00:]:8443/ca/services
Some subsystem interfaces require client authentication to access them, usually interfaces associated with agent or administrator roles. Other interfaces, even those that run over secure (SSL connections) do not require client authentication. Some of these interfaces (such as end entities services) can be configured to require client authentication, but others cannot be configured to support client authentication. These differences are noted in Table 14.1, “Default Web Services Pages”.

Note

Anyone can access the end user pages for a subsystem, but accessing agent or admin web services pages requires that an agent or administrator certificate be issued and installed in the web browser, or authentication to the web services fails.

Table 14.1. Default Web Services Pages

Used for SSL Used for Client Authentication[a] Web Services Web Service Location
Certificate Manager    
No End Entities ca/ee/ca/
Yes No End Entities ca/ee/ca
Yes Yes Agents ca/agent/ca
Yes No Services ca/services
Yes No Console pkiconsole https://host:port/ca
Key Recovery Authority    
Yes Yes Agents kra/agent/kra
Yes No Services kra/services
Yes No Console pkiconsole https://host:port/kra
Online Certificate Status Manager    
Yes Yes Agents ocsp/agent/ocsp
Yes No Services ocsp/services
Yes No Console pkiconsole https://host:port/ocsp
Token Key Service    
Yes No Services tks/services
Yes No Console pkiconsole https://host:port/tks
Token Processing System    
Yes Services index.cgi
[a] Services with a client authentication value of No can be reconfigured to require client authentication. Services which do not have either a Yes or No value cannot be configured to use client authentication.

14.3.2. Starting the Certificate System Administrative Console

Important

pkiconsole is being deprecated.
The Console is opened by connecting to the subsystem instance over its SSL port using the pkiconsole command. This command has the format: 
pkiconsole https://server.example.com:admin_port/subsystem_type
The subsystem_type can be ca, kra, ocsp, or tks. For example, this opens the KRA console: 
pkiconsole https://server.example.com:8443/kra
If DNS is properly configured, then an IPv4 or IPv6 address can be used to connect to the console. For example: 
pkiconsole https://1.2.3.4:8443/ca
pkiconsole https://[00:00:00:00:123:456:789:00:]:8443/ca

14.3.3. Enabling SSL for the Java Administrative Console

Certificate-based authentication to the Certificate System Console can be enabled so that administrators must authenticate using a client certificate before logging into the Certificate System Console. Store the administrators' certificates before enabling certificate-based authentication.
To enable SSL in the Console, configure both the client and the server.

Important

If a CA is configured for client authentication over the admin port and that CA is a security domain manager, then no new PKI subsystems can be configured that use that CA for its security domain. New PKI instances register themselves to the security domain CA over the admin port but without using client authentication. If the CA requires client authentication, then the registration attempt fails.
First, set up the Certificate System server to use SSL client authentication:
  1. Store the certificates for any administrator using this system. The certificate should be either from the CA itself or from whichever CA signed the certificate for the subsystem.
    1. Open the subsystem console.
    2. Select the Users and Groups option on the left.
    3. In the Users tab, select the administrative user, and click Manage Certificates.
    4. Click Import.
    5. Paste in the base-64 encoded SSL client certificate, such as the administrator certificate stored in the web browser.
    Make sure the client certificate is good for SSL client authentication; otherwise, the server will not accept the client certificate and will post an error message in the error log in the /var/log/instanceID/system: 
    failure (14290): Error receiving connection
SEC_ERROR_INADEQUATE_CERT_TYPE - Certificate type not approved for application.)
  2. Stop the subsystem. 
    pki-server stop instance_name
  3. Open the instance configuration directory, /var/lib/pki/instance_name/subsystem_type/conf.
  4. Open the file CS.cfg.
  5. Change the value of the authType parameter from pwd to sslclientauth: 
    authType=sslclientauth
  6. Save the file.
  7. Open the server.xml file.
  8. Change the clientAuth="false" attribute to clientAuth="want" in the admin interface connector section: 
    <Connector port="8443" maxHttpHeaderSize="8192"
        maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
        enableLookups="false" disableUploadTimeout="true"
        acceptCount="100" scheme="https" secure="true"
        clientAuth="want" sslProtocol="SSL"
.....
        serverCertFile="/var/lib/pki/pki-tomcat/conf/serverCertNick.conf"
        passwordFile="/var/lib/pki/pki-tomcat/conf/password.conf"
        passwordClass="org.apache.tomcat.util.net.jss.PlainPasswordFile"
        certdbDir="/var/lib/pki/pki-tomcat/alias"/>
    The want value means that client authentication is preferred, but not required. This allows client authentication through interfaces that can easily use it (like the Console) while still allowing clients which do not easily support client authentication (other subsystems within the security domain) to connect using regular connections.
  9. Start the subsystem. 
    pki-server start instance_name
After setting up the server, then configure the client to use SSL client authentication.
The Console must have access to the administrator certificate and keys used for SSL client authentication to the server. The Console's default certificate and key databases are stored in the .redhat-idm-console directory.
To provide access to the administrator certificate and keys, either export them from the administrator's browser into a .p12 file and then import it by using pk12util, or copy the browser's certificate and key databases into the .redhat-idm-console directory. (This procedure assumes that the certificates are exported from the browser into a .p12 file.)
  1. Export the administrator user certificate and keys from the browser into a file, such as admin.p12.
  2. Open the user's console directory. 
    /user-directory/.redhat-idm-console
  3. If necessary, create new security databases. 
    certutil -N -d .
  4. Stop the Certificate System instance. 
    pki-server stop instance_name
  5. Use pk12util to import the certificates. 
    # pk12util -i /tmp/admin.p12 -d /user-directory/.redhat-idm-console -W [p12filepassword]
    If the procedure is successful, the command prints the following: 
    pk12util: PKCS12 IMPORT SUCCESSFUL
  6. Export the 64-bit blob of the issuing CA certificate from the browser and save it to a file like ca.crt.
  7. Import the CA certificate from the base 64-blob associated with the admin user cert. 
    certutil -A -d . -n ca -t CT,C,C -i ./ca.crt
  8. Start the Certificate System instance. 
    pki-server start instance_name
  9. Start the Console; now, it prompts for a certificate.