13.5. Creating and Managing Users and Groups for an RA

When an RA is first created, certain default users and groups with default roles are created automatically. An initial user, admin, is created with both agent and administrator roles, and two groups are created to identify agent and administrator users. Additional users and additional groups can be added to manage the RA subsystem and PKI operations.
The RA subsystem does not use a Java console as the other subsystems do, so users and groups are created and managed through the administrator's web services page for the RA.

13.5.1. Managing RA Groups

By default, the RA has administrator and agent groups. Other groups can be configured, depending on the local demands of the PKI and network, and then the new group can be assigned to function as an administrative or agent group.
A user can perform tasks based on what groups he is a member of. An RA agent, for example, must belong to a configured RA agent group to perform agent tasks.

13.5.1.1. Listing Groups for an RA

  1. Open the RA services page. 
    https://server.example.com:12889/services
  2. Click the Administrator Services link.
  3. Click the List Groups link.
  4. There are two default groups, for agents and for administrators. To view the details about any group, click the GID of the group.

13.5.1.2. Creating a New Group for an RA

  1. Open the RA services page. 
    https://server.example.com:12889/services
  2. Click the Administrator Services link.
  3. Click the New Group link.
  4. Fill in the group ID and the name of the group; the name can be longer than the GID, more like a description, to help differentiate the group.
  5. Click the Add New Group link at the top of the form.
  6. After the group is created, add it to the RA configuration so that the group has agent or administrative functions.
    1. Stop the RA instance. 
      service pki-ra stop
      Always stop a subsystem before editing the subsystem configuration files.
    2. Open the CS.cfg file. 
      vim /var/lib/pki-ra/conf/CS.conf
    3. Add the new group's GID to the administrator or agent group list. 
       admin.authorized_groups=administrators,example    
 agent.authorized_groups=administrators,agents,example  
    4. Start the RA instance. 
      service pki-ra start

13.5.1.3. Adding and Removing Users in an RA Group

When a group is created, it does not have any members. Likewise, as new users are added, they have to be added to a group for them to be granted any privileges to the RA.
  1. Open the RA services page. 
    https://server.example.com:12889/services
  2. Click the Administrator Services link.
  3. Click the List Groups link.
  4. Click the name of the group for which to change the group membership.
  5. In the group page, each current member of the group is listed, with a [Delete] link next to the name.
    Existing members who are not members of the group are listed in a drop-down menu. To add a member, select them from the name from the menu, and click Add.

13.5.2. Managing RA Users

RAs have two distinct types of users: agents and administrators.
There is a division between agent tasks and administrative tasks, even though both sets of functions are accessed through web services pages. RA agent tasks manage operations related to issuing certificates, like approving requests. RA administrator tasks relate to managing the server instance, mainly managing users and groups.
For an RA user to be able to perform their tasks, the user entry must be created and then added to the appropriate group.
A default user is created when the RA is first configured, and this admin user belongs to both the agent and administrator groups.

13.5.2.1. Listing and Viewing Users for an RA

  1. Open the RA services page. 
    https://server.example.com:12889/services
  2. Click the Administrator Services link.
  3. Click the List Users link.
  4. All of the configured users for the RA are shown. To view a user, click the UID for that user.
  5. The user details page shows the person's UID, full name, email address, and user SSL certificate.

13.5.2.2. Creating a New User for an RA

  1. Generate a new certificate for the user. All access to the RA web services pages is done through certificate-based authentication, so all RA agents and administrators must have a certificate. This is covered in Section 13.5.2.3, “Generating Agent Certificates for RA Agents”.
  2. Open the RA services page. 
    https://server.example.com:12889/services
  3. Click the Administrator Services link.
  4. Click the New User link.
  5. Fill in the user ID, full name, and email address of the user, and paste in the base 64-encoded certificate requested in the first step (including the ----BEGIN CERTIFICATE----- and ----END CERTIFICATE----- lines).
  6. Click the Add New User link at the bottom of the form.
  7. Once the user is created, add him as a member to the appropriate group so that the user can perform any RA agent or administrator functions. Adding members to groups is covered in Section 13.5.1.3, “Adding and Removing Users in an RA Group”.

13.5.2.3. Generating Agent Certificates for RA Agents

RA agents must have a client certificate that allows them to authenticate to the RA subsystem (meaning accessing the RA agent and administrator services pages). Any SSL client certificate can be used, as long as it is added to the RA's LDAP database, but it is easier to use the default enrollment process in the RA services page.
  1. Request a one-time PIN to use as a certificate request.
    1. Click SSL End Users Services to open the request submission page.
    2. Click Agent Enrollment.
    3. Click PIN Creation Request.
    4. Enter an appropriate UID and email address.
  2. An existing agent must approve the PIN request.
    1. Open the agent services page.
    2. Click List Requests. The PIN request is listed in a table with a status of OPEN.
    3. Click the Request ID to display the details of the request.
    4. Click Approve to approve the request. This generates the PIN the user will use to retrieve the certificate.
  3. The last step is for the user to use the generated PIN to retrieve his certificate.
    1. Open the SSL End Users Services page.
    2. Click Request Status Check.
    3. In the Request ID field, enter the ID of the PIN request.
    4. Click the value in the Import Certificate field to display the one-time PIN.
    5. Click Agent Enrollment again, and then click the Certificate Enrollment link.
    6. Enter the user ID and the PIN.
    7. When the certificate is successfully generated, base-64 encoded blob is displayed.

13.5.2.4. Renewing RA Administrator Certificates

Regenerating the certificate takes its original key and its original profile and request, and recreates an identical key with a new validity period and expiration date.
The RA has a default administrative user that was created at the time the subsystem was created. A new certificate can be requested for this user when their original one expires, using one of the default renewal profiles.
Certificates for administrative users can be renewed directly in the end user enrollment forms, using the serial number of the original certificate.
  1. Renew the admin user certificates through the CA's end users forms, as described in Section 4.8.2, “Certificate-Based Renewal”. This must be the same CA as first issued the certificate (or a clone of it).
    Agent certificates can be renewed by using the certificate-based renewal form in the end entities page, Self-renew user SSL client certificate. This form recognizes and updates the certificate stored in the browser's certificate store directly.

    TIP

    It is also possible to renew the certificate using certutil, as described in Section 15.3.3, “Renewing Certificates Using certutil”. Rather than using the certificate stored in a browser to initiate renewal, certutil uses an input file with the original key.
  2. Export the renewed certificate from the browser.
  3. Copy the certificate to the RA server.
  4. The certificate can only be imported into the SQLite database used by the RA if it is formatted on a single line, so the certificate has to be edited in two ways:
    • Remove the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines.
    • Remove all of the carriage returns and spaces so that all of the text is on one line.
  5. Back up the current certificate database. For example: 
    cp -p /var/lib/pki-ra/conf/dbfile /var/lib/pki-ra/conf/dbfile-20090318
  6. Update the RA administrator's entry in the SQLite database. Make sure that the complete certificate is pasted in, all on a single line. 
    sqlite3 /var/lib/pki-ra/conf/dbfile "UPDATE users SET certificate='MIIDkBFCAmYusjMpBA==' WHERE uid='admin';"
  7. Restart the RA. 
    service pki-ra restart
  8. Restart the browser, and attempt to log in using the new certificate. When the browser prompts to select the certificate to use to authenticate, the new certificate should be available.

13.5.2.5. Deleting Users for an RA

  1. Open the RA services page. 
    https://server.example.com:12889/services
  2. Click the Administrator Services link.
  3. Click the List Users link.
  4. All of the configured users for the RA are shown. To view a user, click the UID for that user.
  5. At the bottom of the page, click the [Delete] link.