SupportConsoleDevelopersStart a trialContact

Chapter 11. Managing Certificate System Users and Groups

This chapter explains how to set up authorization for access to the administrative, agent services, and end-entities pages.

11.1. About authorization
Copy link

Authorization is the process of allowing access to certain tasks associated with the Certificate System. Access can be limited to allow certain tasks to certain areas of the subsystem for certain users or groups and different tasks to different users and groups.

Users are specific to the subsystem in which they are created. Each subsystem has its own set of users independent of any other subsystem installed. The users are placed in groups, which can be predefined or user-created. Privileges are assigned to a group through access control lists (ACLs). There are ACLs associated with areas in the agent services interface and end-entities page that perform an authorization check before allowing an operation to proceed. Access control instructions (ACIs) in each of the ACLs are created that specifically allow or deny possible operations for that ACL to specified users, groups, or IP addresses.

The ACLs contain a default set of ACIs for the default groups that are created. These ACIs can be modified to change the privileges of predefined groups or to assign privileges to newly-created groups.

Authorization goes through the following process:

  1. The users authenticate to the interface using either the Certificate System user ID and password or a certificate.
  2. The server authenticates the user either by matching the user ID and password with the one stored in the database or by checking the certificate against one stored in the database. With certificate-based authentication, the server also checks that the certificate is valid and finds the group membership of the user by associating the DN of the certificate with a user and checking the user entry. With password-based authentication, the server checks the password against the user ID and then finds the group membership of the user by associating that user ID with the user ID contained in the group.
  3. When the user tries to perform an operation, the authorization mechanism compares the user ID of the user, the group in which the user belongs, or the IP address of the user to the ACLs set for that user, group, or IP address. If an ACL exists that allows that operation, then the operation proceeds.

11.2. Default groups
Copy link

The privileges of a user are determined by its group (role) membership. A user can be assigned to three groups (roles):

  • Administrators. This group is given full access to all of the tasks available in the administrative interface.
  • Agents. This group is given full access to all of the tasks available in the agent services interface.
  • Auditors. This group is given access to view the signed audit logs. This group does not have any other privileges.

There is a fourth role that is exclusively created for communication between subsystems. Administrators should never assign a real user to such a role:

  • Enterprise administrators. Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator when it is joined to a security domain during configuration. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems.

11.2.1. Administrators
Copy link

Administrators have permissions to perform all administrative tasks. A user is designated or identified as being an administrator by being added to the Administrators group for the group. Every member of that group has administrative privileges for that instance of Certificate System.

At least one administrator must be defined for each Certificate System instance, but there is no limit to the number of administrators an instance can have. The first administrator entry is created when the instance is configured.

Administrators are authenticated with a simple bind using their Certificate System user ID and password.

Table 11.1. Security domain user roles
RoleDescription

Security Domain Administrators

  • Add and modify users in the security domain’s user and group database.
  • Manage the shared trust policies.
  • Manage the access controls on the domain services.

By default, the CA administrator of the CA hosting the domain is assigned as the security domain administrator.

Enterprise CA Administrators

  • Automatically approve any sub-CA, server, and subsystem certificate from any CA in the domain.
  • Register and unregister CA subsystem information in the security domain.

Enterprise KRA Administrators

  • Automatically approve any transport, storage, server, and subsystem certificate from any CA in the domain.
  • Register and unregister KRA subsystem information in the security domain.
  • Push KRA connector information to any CA.

Enterprise OCSP Administrators

  • Automatically approve any OCSP, server, and subsystem certificate from any CA in the domain.
  • Register and unregister OCSP subsystem information in the security domain.
  • Push CRL publishing information to any CA.

Enterprise TKS Administrators

  • Automatically approve any server and subsystem certificate from any CA in the domain.
  • Register and unregister TKS subsystem information in the security domain.

Enterprise TPS Administrators

  • Automatically approve any server and subsystem certificate from any CA in the domain.
  • Register and unregister TPS subsystem information in the security domain.

As necessary, the security domain administrator can manage access controls on the security domain and on the individual subsystems. For example, the security domain administrator can restrict access so that only finance department KRA administrators can set up finance department KRAs.

Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. For example, an enterprise CA administrator has the privileges to have sub-CA certificates approved automatically during configuration. Alternatively, a security domain administrator can restrict this right if necessary.

11.2.2. Auditors
Copy link

Auditors view the signed audit logs to audit the operation of the system. Auditors cannot administer the server.

To create an auditor, add a user to the Auditors group and store the auditor’s certificate in the user entry. The auditor’s certificate encrypts the private key of the key pair that signs the audit log.

Certificate System creates the Auditors group during subsystem configuration but does not assign any auditors to the group.

Auditors can only view the audit logs and cannot modify other parts of the system.

11.2.3. Agents
Copy link

Agents are users who have been assigned end-entity certificate and key-management privileges. Agents can access the agent services interface.

Agents are created by assigning a user to the appropriate subsystem agent group and identifying certificates that the agents must use for SSL client authentication to the subsystem for it to service requests from the agents. Each subsystem has its own agent group:

  • The Certificate Manager Agents group.
  • The Key Recovery Authority Agents group.
  • The Online Certificate Status Manager Agents group.
  • The Token Key Service Agents group.
  • The Token Processing System Agents group.

Each Certificate System subsystem has its own agents with roles defined by the subsystem. Each subsystem must have at least one agent, but there is no limit to the number of agents a subsystem can have.

Certificate System identifies and authenticates a user with agent privileges by checking the user’s SSL client certificate in its internal database.

11.2.4. Enterprise Groups
Copy link

Important

No real user should ever be assigned to this group.

During subsystem configuration, every subsystem instance is joined to a security domain. Each subsystem instance is automatically assigned a subsystem-specific role as an enterprise administrator. These roles automatically provide trusted relationships among subsystems in the security domain, so that each subsystem can efficiently carry out interactions with other subsystems. For example, this allows OCSPs to push CRL publishing publishing information to all CAs in the domain, KRAs to push KRA connector information, and CAs to approve certificates generated within the CA automatically.

Enterprise subsystem administrators are given enough privileges to perform operations on the subsystems in the domain. Each subsystem has its own security domain role:

  • Enterprise CA Administrators
  • Enterprise KRA Administrators
  • Enterprise OCSP Administrators
  • Enterprise TKS Administrators
  • Enterprise TPS Administrators

Additionally, there is a Security Domain Administrators group for the CA instance which manages the security domain, access control, users, and trust relationships within the domain.

Each subsystem administrator authenticates to the other subsystems using SSL client authentication with the subsystem certificate issued during configuration by the security domain CA.

Many of the operations that users can perform are dictated by the groups that they belong to; for instance, agents for the CA manage certificates and profiles, while administrators manage CA server configuration.

11.3.1. Managing groups
Copy link

Groups define the privileges that users have within a subsystem. Each group has associated access control lists (ACLs) that determine which operations its members can perform. You can create new groups with custom privileges or modify the membership of existing groups. For more information about the default groups, see Section 11.2, “Default groups”.

11.3.1.1. Creating a new group
Copy link

When you create a new group, configure ACLs to grant the group privileges. Without ACLs, the group has no access permissions to any part of Certificate System. You can only add users who already exist in the internal database.

11.3.1.2. Changing members in a group
Copy link

You can add or remove members from any group. The administrators group must always have at least one user entry.

The users for each subsystem are maintained separately. Just because a person is an administrator in one subsystem does not mean that person has any rights (or even a user entry) for another subsystem. Users can be configured and, with their user certificates, trusted as agents, administrators, or auditors for a subsystem.

11.3.2.1. Creating users
Copy link

After you installed Certificate System, only the user created during the setup exists. This section describes how to create additional users.

Note

For security and audit reasons, create individual accounts for Certificate System users and administrators.

To create a user using the command line:

  1. Add a user account. For example, to add the example user to the CA: 

    # pki -d ~/.dogtag/pki-instance_name/ca/alias/ -c password -n caadmin \
     ca-user-add example --fullName "Example User"
---------------------
Added user "example"
---------------------
  User ID: example
  Full name: Example User

    This command uses the caadmin user to add a new account.

  2. Optionally, add a user to a group. For example, to add the example user to the Certificate Manager Agents group: 

    # pki -d ~/.dogtag/pki-instance_name/ -p password -n "caadmin" \
     user-add-membership example Certificate Manager Agents

  3. Create a certificate request:

    • If a Key Recovery Authority (KRA) exists in your Certificate System environment: 

      # CRMFPopClient -d /home/example-user/certs_db -p password -n "CN=user_name" -q POP_SUCCESS -b kra.transport -w "AES KeyWrap/Wrapped" -v -o ~/user_name.req -oaep

      This command stores the Certificate Signing Request (CSR) in the CRMF format in the ~/user_name.req file.

      Note

      Use -oaep if the server is configured for it. Use AES KeyWrap/WrapWrapped if a modern HSM prefers it over AES/CBC/PKCS5Padding.

    • If no Key Recovery Authority (KRA) exists in your Certificate System environment:

      • Create a NSS database directory: 

        # export pkiinstance=ca1
# echo ${pkiinstance}
# export agentdir=~/.dogtag/${pkiinstance}/agent1.dir
# echo ${agentdir}
# pki -d ${agentdir}/ -C ${somepwdfile} client-init

      • Store the CSR in a PKCS-#10 formatted file specified by the -o option, -d for the path to an initialized NSS database directory, -P option for a password file, -p for a password, and -n for a subject DN: 

        # PKCS10Client -d ${agentdir}/ -P ${somepwdfile} -n "cn=agent1,uid=agent1" -o ${agentdir}/agent1.csr
PKCS10Client: Certificate request written into /.dogtag/ca1/agent1.dir/agent1.csr
PKCS10Client: PKCS#10 request key id written into /.dogtag/ca1/agent1.dir/agent1.csr.keyId

  4. Create an enrollment request:

    • Create the ~/cmc.role`crmf.cfg file with the following content: 

      #numRequests: Total number of PKCS10 requests or CRMF requests.
numRequests=1

#input: full path for the PKCS10 request or CRMF request,
#the content must be in Base-64 encoded format
#Multiple files are supported. They must be separated by space.
input=~/user_name.req

#output: full path for the CMC request in binary format
output=~/cmc.role_crmf.req

#tokenname: name of token where agent signing cert can be found (default is internal)
tokenname=internal

#nickname: nickname for agent certificate which will be used
#to sign the CMC full request.
nickname=PKI Administrator for Example.com

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
dbdir=~/.dogtag/pki-instance_name/

#password: password for cert9.db which stores the agent
#certificate
password=password

#format: request format, either pkcs10 or crmf
format=crmf

      Set the parameters based on your environment and the CSR format used in the previous step.

    • Pass the previously created configuration file to the CMCRequest utility to create the CMC request: 

      # CMCRequest ~/cmc.role_crmf.cfg

  5. Submit a Certificate Management over CMS (CMC) request:

    • Create the ~/HttpClient`role_crmf.cfg file with the following content: 

      # #host: host name for the http server
host=server.example.com

#port: port number
port=8443

#secure: true for secure connection, false for nonsecure connection
secure=true

#input: full path for the enrollment request, the content must be in binary format
input=~/cmc.role_crmf.req

#output: full path for the response in binary format
output=~/cmc.role_crmf.resp

#tokenname: name of token where SSL client authentication cert can be found (default is internal)
#This parameter will be ignored if secure=false
tokenname=internal

#dbdir: directory for cert9.db, key4.db and pkcs11.txt
#This parameter will be ignored if secure=false
dbdir=~/.dogtag/pki-instance_name/

#clientmode: true for client authentication, false for no client authentication
#This parameter will be ignored if secure=false
clientmode=true

#password: password for cert9.db
#This parameter will be ignored if secure=false and clientauth=false
password=password

#nickname: nickname for client certificate
#This parameter will be ignored if clientmode=false
nickname=PKI Administrator for Example.com

#servlet: servlet name
servlet=/ca/ee/ca/profileSubmitCMCFull

      Set the parameters based on your environment.

    • Submit the request to the CA: 

      # HttpClient ~/HttpClient_role_crmf.cfg
Total number of bytes read = 3776
after SSLSocket created, thread token is Internal Key Storage Token
client cert is not null
handshake happened
writing to socket
Total number of bytes read = 2523
MIIJ1wYJKoZIhvcNAQcCoIIJyDCCCcQCAQMxDzANBglghkgBZQMEAgEFADAxBggr
...
The response in data format is stored in ~/cmc.role_crmf.resp

    • Verify the result: 

      # CMCResponse ~/cmc.role_crmf.resp
Certificates:
    Certificate:
        Data:
            Version:  v3
            Serial Number: 0xE
            Signature Algorithm: SHA256withRSA - 1.2.840.113549.1.1.11
            Issuer: CN=CA Signing Certificate,OU=pki-instance_name Security Domain
            Validity:
                Not Before: Friday, July 21, 2017 12:06:50 PM PDT America/Los_Angeles
                Not  After: Wednesday, January 17, 2018 12:06:50 PM PST America/Los_Angeles
            Subject: CN=user_name
...
Number of controls is 1
Control #0: CMCStatusInfoV2
   OID: {1 3 6 1 5 5 7 7 25}
   BodyList: 1
   Status: SUCCESS

  6. Optionally, to import the certificate as the user to its own ~/.dogtag/pki-instance_name/ database: 

    # certutil -d ~/.dogtag/pki-instance_name/ -A -t "u,u,u" -n "user_name certificate" -i ~/cmc.role_crmf.resp

  7. Add the certificate to the user record:

    • List certificates issued for the user to discover the certificate’s serial number. For example, to list certificates that contain the example user name in the certificate’s subject: 

      pki -d ~/.dogtag/pki-instance_name/ -c password -n caadmin ca-user-cert-find example
-----------------
1 entries matched
-----------------
  Cert ID: 2;6;CN=CA Signing Certificate,O=EXAMPLE;CN=PKI Administrator,E=example@example.com,O=EXAMPLE
  Version: 2
  Serial Number: 0x6
  Issuer: CN=CA Signing Certificate,O=EXAMPLE
  Subject: CN=PKI Administrator,E=example@example.com,O=EXAMPLE
----------------------------
Number of entries returned 1

      The serial number of the certificate is required in the next step.

    • Add the certificate using its serial number from the certificate repository to the user account in the Certificate System database. For example, for a CA user: 

      pki -c password -n caadmin ca-user-cert-add example --serial 0x6

There are two methods of renewing a certificate. 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. Re-keying a certificate resubmits the initial certificate request to the original profile, but generates a new key pair. Administrator certificates can be renewed by being re-keyed.

Each subsystem has a bootstrap user that was created at the time the subsystem was created. A new certificate can be requested for this user before 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 in the CA’s end users forms, as described in Section 5.4.1.1.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.

    Note

    It is also possible to renew the certificate using certutil, as described in Section 13.2.2, “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. Add the renewed user certificate to the user entry in the internal LDAP database.

+ This can also be done by using ldapmodify to add the renewed certification directly to the user entry in the internal LDAP database, by replacing the userCertificate attribute in the user entry, such as uid=admin,ou=people,dc=subsystem-base-DN.

When a valid user certificate has already expired, you can no longer use the web service page nor the pki command-line tool requiring authentication. In such a scenario, you can use the pki-server cert-fix command to renew an expired certificate.

Before you proceed, make sure:

  • You have a valid CA certificate.
  • You have root privileges.

Procedure

  1. Disable self test.

    • Either run the following command: 

      # pki-server selftest-disable -i PKI_instance

    • Or remove the following line from CA’s CS.cfg file and restart the CA subsystem: 

      selftests.container.order.startup=CAPresence:critical, SystemCertsVerification:critical

  2. Check the expired certificates in the client’s NSS database and find the certificate’s serial number (certificate ID).

    1. List the user certificates: 

      # certutil -L -d /root/nssdb/

    2. Get the expired certificate serial number, which you want to renew: 

      # certutil -L -d /root/nssdb/ -n Expired_cert | grep Serial
Serial Number: 16 (0x10)

  3. Renew the certificate. The local LDAP server requires the LDAP Directory Manager’s password. 

    # pki-server cert-fix --ldap-url ldap://host389 --agent-uid caadmin -i PKI_instance -p PKI_https_port --extra-cert 16

  4. Re-enable self test.

    • Either run the following command: 

      # pki-server selftest-enable -i PKI_instance

    • Or add the following line to CA’s CS.cfg file and restart the CA subsystem: 

      selftests.container.order.startup=CAPresence:critical, SystemCertsVerification:critical

To verify that you have succeeded in the certificate renewal, you can display sufficient information about the certificate by running: 

# pki ca-cert-find

To see full details of the specific certificate including attributes, extensions, public key modulus, hashes, and more, you can also run: 

# pki ca-cert-show 16 --pretty

11.3.2.4. Deleting a Certificate System user
Copy link

Users can be deleted from the internal database. Deleting a user from the internal database deletes that user from all groups to which the user belongs. To remove the user from specific groups, modify the group membership.

11.4. Configuring access control for users
Copy link

Authorization is the mechanism that checks whether a user is allowed to perform an operation. Authorization points are defined in certain groups of operations that require an authorization check.

11.4.1. About access control
Copy link

Access control lists (ACLs) are the mechanisms that specify the authorization to server operations. An ACL exists for each set of operations where an authorization check occurs. Additional operations can be added to a ACL.

The ACL contains access control instructions (ACIs) which specifically allow or deny operations, such as read or modify. The ACI also contains an evaluator expression. The default implementation of ACLs specifies only users, groups, and IP addresses as possible evaluator types. Each ACI in an ACL specifies whether access is allowed or denied, what the specific operator is being allowed or denied, and which users, groups, or IP addresses are being allowed or denied to perform the operation.

The privileges of Certificate System users are changed by changing the access control lists (ACL) that are associated with the group in which the user is a member, for the users themselves, or for the IP address of the user. New groups are assigned access control by adding that group to the access control lists. For example, a new group for administrators who are only authorized to view logs, LogAdmins, can be added to the ACLs relevant to logs to allow read or modify access to this group. If this group is not added to any other ACLs, members of this group only have access to the logs.

The access for a user, group, or IP address is changed by editing the ACI entries in the ACLs. In the ACL interface, each ACI is shown on a line of its own. In this interface window, the ACI has the following syntax: 

allow|deny (operation) user|group|IP="name"
Note

The IP address can be an IPv4 or IPv6 address. An IPv4 address must be in the format n.n.n.n or n.n.n.n,m.m.m.m. For example, 128.21.39.40 or 128.21.39.40,255.255.255.00. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example, 0:0:0:0:0:0:13.1.68.3, FF01::43, 0:0:0:0:0:0:13.1.68.3,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:255.255.255.0, and FF01::43,FFFF:FFFF:FFFF:FFFF:FFFF:FFFF:FF00:0000.

For example, the following is an ACI that allows administrators to perform read operations: 

allow (read) group="Administrators"

An ACI can have more than one operation or action configured. The operations are separated with a comma with no space on either side. For example: 

allow (read,modify) group="Administrators"

An ACI can have more than one group, user, or IP address by separating them with two pipe symbols (||) with a space on either side. For example: 

allow (read) group="Administrators" || group="Auditors"

You can create or modify ACIs to allow or deny operations for specific users, groups, or IP addresses. Each ACI specifies the permitted operations and the entities that are granted or denied access.

An ACI can either allow or deny an operation for the specified group, user ID, or IP address. Generally, ACIs do not need to be created to deny access. If there are no allow ACIs that include a user ID, group, or IP address, then the group, user ID, or IP address is denied access.

Note

If a user is not explicitly allowed access to any of the operations for a resource, then this user is considered denied; he does not specifically need to be denied access.

For example, user JohnB is a member of the Administrators group. If an ACL has only the following ACL, JohnB is denied any access since he does not match any of the allow ACIs: 

Allow (read,modify) group="Auditors" || user="BrianC"

There usually is no need to include a deny statement. Some situations can arise, however, when it is useful to specify one. For example, JohnB, a member of the Administrators group, has just been fired. It may be necessary to deny access specifically to JohnB if the user cannot be deleted immediately. Another situation is that a user, BrianC, is an administrator, but he should not have the ability to change some resource. Since the Administrators group must access this resource, BrianC can be specifically denied access by creating an ACI that denies this user access.

The allowed rights are the operations which the ACI controls, either by allowing or denying permission to perform the operation. The actions that can be set for an ACL vary depending on the ACL and subsystem. Two common operations that can be defined are read and modify.

The syntax field of the ACI editor sets the evaluator for the expression. The evaluator can specify group, name, and IP address (both IPv4 and IPv6 addresses). These are specified along with the name of the entity set as equals (=) or does not equal (!=).

The syntax to include a group in the ACL is group="groupname". The syntax to exclude a group is group!="groupname", which allows any group except for the group named. For example: 

group="Administrators" || group!="Auditors"

It is also possible to use regular expressions to specify the group, such as using wildcard characters like an asterisk (*). For example: 

group="* Managers"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

The syntax to include a user in the ACL is user="userID". The syntax to exclude the user is user!="userID", which allows any user ID except for the user ID named. For example: 

user="BobC" || user!="JaneK"

To specify all users, provide the value anybody. For example: 

user="anybody"

It is also possible to use regular expressions to specify the user names, such as using wildcard characters like an asterisk (*). For example: 

user="*johnson"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

The syntax to include an IP address in the ACL is ipaddress="ipaddress". The syntax to exclude an ID address from the ACL is ipaddress!="ipaddress". An IP address is specified using its numeric value; DNS values are not permitted. For example: 

ipaddress="12.33.45.99"
ipaddress!="23.99.09.88"

The IP address can be an IPv4 address, as shown above, or IPv6 address. An IPv4 address has the format n.n.n.n or n.n.n.n,m.m.m.m with the netmask. An IPv6 address uses a 128-bit namespace, with the IPv6 address separated by colons and the netmask separated by periods. For example: 

ipaddress="0:0:0:0:0:0:13.1.68.3"

It is also possible to use regular expressions to specify the IP address, such as using wildcard characters like an asterisk (*). For example: 

ipaddress="12.33.45.*"

For more information on supported regular expression patterns, see https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html.

It is possible to create a string with more than one value by separating each value with two pipe characters (||) with a space on either side. For example: 

user="BobC" || group="Auditors" || group="Administrators"

For instruction on how to configure this feature by editing the CS.cfg file, see the Changing the Access Control Settings for the Subsystem.

Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Legal Notice

Theme

© 2026 Red HatBack to top