Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 11. Authentication for enrolling certificates

This chapter covers how to enroll end entity certificates, how to create and manage server certificates, the authentication methods available in the Certificate System to use when enrolling end entity certificates, and how to set up those authentication methods.

Enrollment is the process of issuing certificates to an end entity. The process is creating and submitting the request, authenticating the user requesting it, and then approving the request and issuing the certificate.

The method used to authenticate the end entity determines the entire enrollment process. There are three ways that the Certificate System can authenticate an entity:

  • In agent-approved enrollment, end-entity requests are sent to an agent for approval. The agent approves the certificate request.
  • In automatic enrollment, end-entity requests are authenticated using a plug-in, and then the certificate request is processed; an agent is not involved in the enrollment process.
  • In CMC enrollment, a third party application can create a request that is signed by an agent and then automatically processed.

A Certificate Manager is initially configured for agent-approved enrollment and for CMC authentication. Automated enrollment is enabled by configuring one of the authentication plug-in modules. More than one authentication method can be configured in a single instance of a subsystem.

NOTE

An email can be automatically sent to an end entity when the certificate is issued for any authentication method by configuring automated notifications. See Chapter 13, Using automated notifications for more information on notifications.

11.1. Configuring agent-approved enrollment
Copy link

The Certificate Manager is initially configured for agent-approved enrollment. An end entity makes a request which is sent to the agent queue for an agent’s approval. An agent can modify request, change the status of the request, reject the request, or approve the request. Once the request is approved, the signed request is sent to the Certificate Manager for processing. The Certificate Manager processes the request and issues the certificate.

The agent-approved enrollment method is not configurable. If a Certificate Manager is not configured for any other enrollment method, the server automatically sends all certificate-related requests to a queue where they await agent approval. This ensures that all requests that lack authentication credentials are sent to the request queue for agent approval.

  • To use agent-approved enrollment, leave the authentication method blank in the profile’s .cfg file. For example: 

    auth.instance_id=
    Copy to Clipboard Toggle word wrap

11.2. Automated enrollment
Copy link

In automated enrollment, an end-entity enrollment request is processed as soon as the user successfully authenticates by the method set in the authentication plug-in module; no agent approval is necessary. The following authentication plug-in modules are provided:

  • Directory-based enrollment. End entities are authenticated against an LDAP directory using their user ID and password or their DN and password. See Section 11.2.1, “Setting up directory-based authentication”.
  • PIN-based enrollment. End entities are authenticated against an LDAP directory using their user ID, password, and a PIN set in their directory entry. See Section 11.2.2, “Setting up PIN-based enrollment”.
  • Certificate-based authentication. Entities of some kind - both end users and other entities, like servers or tokens - are authenticated to the CA using a certificate issued by the CA which proves their identity. This is most commonly used for renewal, where the original certificate is presented to authenticate the renewal process. See Section 11.2.3, “Using Certificate-Based Authentication”.

  • AgentCertAuth. This method automatically approves a certificate request if the entity submitting the request is authenticated as a subsystem agent. A user authenticates as an agent by presenting an agent certificate. If the presented certificate is recognized by the subsystem as an agent certificate, then the CA automatically processes the certificate request.

    This form of automatic authentication can be associated with the certificate profile for enrolling for server certificates.

    This plug-in is enabled by default and has no parameters.

  • Flat file-based enrollment. Used exclusively for router (SCEP) enrollments, a text file is used which contains a list of IP addresses, hostnames, or other identifier and a password, which is usually a random PIN. A router authenticates to the CA using its ID and PIN, and then the CA compares the presented credentials to the list of identities in the text file. See Section 11.2.4, “Configuring Flat File Authentication”.

11.2.1. Setting up directory-based authentication
Copy link

The UidPwdDirAuth and the UdnPwdDirAuth plug-in modules implement directory-based authentication. End users enroll for a certificate by providing their user IDs or DN and password to authenticate to an LDAP directory.

  1. Create an instance of either the UidPwdDirAuth or UdnPwdDirAuth authentication plug-in module and configure the instance.

    1. Open the CA Console. 

      pkiconsole https://server.example.com:8443/ca
      Copy to Clipboard Toggle word wrap
      Note

      pkiconsole is being deprecated.

    2. In the Configuration tab, select Authentication in the navigation tree.

      The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.

      Note

      The UidPwdDirAuth plug-in is enabled by default.

    3. Click Add.

      The Select Authentication Plug-in Implementation window appears.

    4. Select UidPwdDirAuth for user ID and password authentication, or select UdnPwdDirAuth for DN and password authentication.

    5. Fill in the following fields in the Authentication Instance Editor window:

      • Authentication Instance ID. Accept the default instance name, or enter a new name.
      • dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
      • ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes are copied from the authentication directory into the authentication token and used by the certificate profile to generate the subject name. Entering values for this parameter is optional.

      • ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.

        Entering values for this parameter is optional.

      • ldap.ldapconn.host. Specifies the fully-qualified DNS hostname of the authentication directory.
      • ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests; if the ldap.ldapconn.secureConn. checkbox is selected, this should be the SSL port number.
      • ldap.ldapconn.secureConn. Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests from the Certificate System. Select if this is an SSL port.
      • ldap.ldapconn.version. Specifies the LDAP protocol version, either 2 or 3. The default is 3, since all Directory Servers later than version 3.x are LDAPv3.
      • ldap.basedn. Specifies the base DN for searching the authentication directory. The server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
      • ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3.
      • ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10.
    6. Click OK. The authentication instance is set up and enabled.

  2. Set the certificate profiles to use to enroll users by setting policies for specific certificates. Customize the enrollment forms by configuring the inputs in the certificate profiles, and include inputs for the information needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a third-party tool.

    For information on configuring the profiles, see Section 3.7.2, “Inserting LDAP directory attribute values and other information into the subject alt name”.

Setting up bound LDAP connection

Some environments require disallowing an anonymous bind for the LDAP server that is used for authentication. To create a bound connection between a CA and the LDAP server, you need to make the following configuration changes:

  • Set up directory-based authentication according to the following example in CS.cfg: 

    auths.instance.UserDirEnrollment.ldap.ldapBoundConn=true
auths.instance.UserDirEnrollment.ldap.ldapauth.authtype=BasicAuth
auths.instance.UserDirEnrollment.ldap.ldapauth.bindDN=cn=Directory Manager
auths.instance.UserDirEnrollment.ldap.ldapauth.bindPWPrompt=externalLDAP
externalLDAP.authPrefix=auths.instance.UserDirEnrollment
cms.passwordlist=internaldb,replicationdb,externalLDAP
    Copy to Clipboard Toggle word wrap

    where bindPWPrompt is the tag or prompt that is used in the password.conf file; it is also the name used under the cms.passwordlist and authPrefix options.

  • Add the tag or prompt from CS.cfg with its password in password.conf: 

    externalLDAP=your_password
    Copy to Clipboard Toggle word wrap
Setting up external authorization

A directory-based authentication plug-in can also be configured to evaluate the group membership of the user for authentication. To set up the plug-in this way, the following options has to be configured in CS.cfg:

  • groupsEnable is a boolean option that enables retrieval of groups. The default value is false.
  • groupsBasedn is the base DN of groups. It needs to be specified when it differs from the default basedn.
  • groups is the DN component for groups. The default value is ou=groups.
  • groupObjectClass is one of the following group object classes: groupofuniquenames, groupofnames. The default value is groupofuniquenames.
  • groupUseridName is the name of the user ID attribute in the group object member attribute. The default value is cn.
  • useridName is the name of the user ID DN component. The default value is uid.
  • searchGroupUserByUserdn is a boolean option that determines whether to search the group object member attribute for the userdn or ${groupUserIdName}=${uid} attributes. The default value is true.

For example: 

auths.instance.UserDirEnrollment.pluginName=UidPwdDirAuth
auths.instance.UserDirEnrollment.ldap.basedn=cn=users,cn=accounts,dc=local
auths.instance.UserDirEnrollment.ldap.groupObjectClass=groupofnames
auths.instance.UserDirEnrollment.ldap.groups=cn=groups
auths.instance.UserDirEnrollment.ldap.groupsBasedn=cn=accounts,dc=local
auths.instance.UserDirEnrollment.ldap.groupsEnable=true
auths.instance.UserDirEnrollment.ldap.ldapconn.host=local
auths.instance.UserDirEnrollment.ldap.ldapconn.port=636
auths.instance.UserDirEnrollment.ldap.ldapconn.secureConn=true
Copy to Clipboard Toggle word wrap

Finally, you have to modify the /instance_path/ca/profiles/ca/profile_id.cfg file to configure the profile to use the UserDirEnrollment auth instance defined in CS.cfg, and if appropriate, provide an ACL for authorization based on groups. For example: 

auth.instance_id=UserDirEnrollment
authz.acl=group="cn=devlab-access,ou=engineering,dc=example,dc=com"
Copy to Clipboard Toggle word wrap

11.2.2. Setting up PIN-based enrollment
Copy link

PIN-based authentication involves setting up PINs for each user in the LDAP directory, distributing those PINs to the users, and then having the users provide the PIN along with their user ID and password when filling out a certificate request. Users are then authenticated both against an LDAP directory using their user ID and password and against the PIN in their LDAP entry. When the user successfully authenticates, the request is automatically processed, and a new certificate is issued.

The Certificate System provides a tool, setpin, that adds the necessary schema for PINs to the Directory Server and generates the PINs for each user.

The PIN tool performs the following functions:

  • Adds the necessary schema for PINs to the LDAP directory.
  • Adds a PIN manager user who has read-write permissions to the PINs that are set up.
  • Sets up ACIs to allow for PIN removal once the PIN has been used, giving read-write permissions for PINs to the PIN manager, and preventing users from creating or changing PINs.
  • Creates PINs in each user entry.
Note

This tool is documented in the Certificate System Command-Line Tools Guide.

  1. Use the PIN tool to add schema needed for PINs, add PINs to the user entries, and then distribute the PINs to users.

    1. Open the /usr/share/pki/native-tools/ directory.
    2. Open the setpin.conf file in a text editor.

    3. Follow the instructions outlined in the file and make the appropriate changes.

      Usually, the parameters which need updated are the Directory Server’s host name, Directory Manager’s bind password, and PIN manager’s password.

    4. Run the setpin command with its optfile option pointing to the setpin.conf file. 

      setpin optfile=/usr/share/pki/native-tools/setpin.conf
      Copy to Clipboard Toggle word wrap

      The tool modifies the schema with a new attribute (by default, pin) and a new object class (by default, pinPerson), creates a pinmanager user, and sets the ACI to allow only the pinmanager user to modify the pin attribute.

    5. To generate PINs for specific user entries or to provide user-defined PINs, create an input file with the DNs of those entries listed. For example: 

      dn:uid=bjensen,ou=people,dc=example,dc=com
dn:uid=jsmith,ou=people,dc=example,dc=com
dn:jtyler,ou=people,dc=example,dc=com
...
      Copy to Clipboard Toggle word wrap

      For information on constructing an input file, see the PIN generator chapter in the Certificate System Command-Line Tools Guide.

    6. Disable setup mode for the setpin command. Either comment out the setup line or change the value to no. 

      # vim /usr/share/pki/native-tools/setpin.conf

setup=no
      Copy to Clipboard Toggle word wrap

      Setup mode creates the required uers and object classes, but the tool will not generate PINs while in setup mode.

    7. Run the setpin command to create PINs in the directory.

      Note

      Test-run the tool first without the write option to generate a list of PINs without actually changing the directory.

      For example: 

      setpin host=yourhost port=9446 length=11 input=infile output=outfile write "binddn=cn=pinmanager,o=example.com" bindpw="password" basedn=o=example.com "filter=(uid=u*)" hash=sha256
      Copy to Clipboard Toggle word wrap
      Warning

      Do not set the hash argument to none. Running the setpin command with hash=none results in the pin being stored in the user LDAP entry as plain text.

    8. Use the output file for delivering PINs to users after completing setting up the required authentication method.

      After confirming that the PIN-based enrollment works, deliver the PINs to users so they can use them during enrollment. To protect the privacy of PINs, use a secure, out-of-band delivery method.

  2. Set the policies for specific certificates in the certificate profiles to enroll users. See Chapter 3, Certificate profiles (Making Rules for Issuing Certificates) for information about certificate profile policies.

  3. Create and configure an instance of the UidPwdPinDirAuth authentication plug-in.

    1. Open the CA Console. 

      pkiconsole https://server.example.com:8443/ca
      Copy to Clipboard Toggle word wrap
      Note

      pkiconsole is being deprecated.

    2. In the Configuration tab, select Authentication in the navigation tree.

      The right pane shows the Authentication Instance tab, which lists the currently configured authentication instances.

    3. Click Add.

      The Select Authentication Plug-in Implementation window appears.

    4. Select the UidPwdPinDirAuth plug-in module.

    5. Fill in the following fields in the Authentication Instance Editor window:

      • Authentication Instance ID. Accept the default instance name or enter a new name.
      • removePin. Sets whether to remove PINs from the authentication directory after end users successfully authenticate. Removing PINs from the directory restricts users from enrolling more than once, and thus prevents them from getting more than one certificate.
      • pinAttr. Specifies the authentication directory attribute for PINs. The PIN Generator utility sets the attribute to the value of the objectclass parameter in the setpin.conf file; the default value for this parameter is pin.
      • dnpattern. Specifies a string representing a subject name pattern to formulate from the directory attributes and entry DN.
      • ldapStringAttributes. Specifies the list of LDAP string attributes that should be considered authentic for the end entity. Entering values for this parameter is optional.

      • ldapByteAttributes. Specifies the list of LDAP byte (binary) attributes that should be considered authentic for the end entity. If specified, the values corresponding to these attributes will be copied from the authentication directory into the authentication token for use by other modules, such as adding additional information to users' certificates.

        Entering values for this parameter is optional.

      • ldap.ldapconn.host. Specifies the fully-qualified DNS host name of the authentication directory.
      • ldap.ldapconn.port. Specifies the TCP/IP port on which the authentication directory listens to requests from the Certificate System.
      • ldap.ldapconn.secureConn. Specifies the type, SSL or non-SSL, of the port on which the authentication directory listens to requests. Select if this is an SSL port.
      • ldap.ldapconn.version. Specifies the LDAP protocol version, either 2 or 3. By default, this is 3, since all Directory Server versions later than 3.x are LDAPv3.
      • ldap.ldapAuthentication.bindDN. Specifies the user entry as whom to bind when removing PINs from the authentication directory. Specify this parameter only if the removePin checkbox is selected. It is recommended that a separate user entry that has permission to modify only the PIN attribute in the directory be created and used. For example, do not use the Directory Manager’s entry because it has privileges to modify the entire directory content.
      • password. Gives the password associated with the DN specified by the ldap.ldapauthbindDN parameter. When saving changes, the server stores the password in the single sign-on password cache and uses it for subsequent start ups. This parameter needs set only if the removePin checkbox is selected.
      • ldap.ldapAuthentication.clientCertNickname. Specifies the nickname of the certificate to use for SSL client authentication to the authentication directory to remove PINs. Make sure that the certificate is valid and has been signed by a CA that is trusted in the authentication directory’s certificate database and that the authentication directory’s certmap.conf file has been configured to map the certificate correctly to a DN in the directory. This is needed for PIN removal only.

      • ldap.ldapAuthentication.authtype. Specifies the authentication type, basic authentication or SSL client authentication, required in order to remove PINs from the authentication directory.

        • BasicAuth specifies basic authentication. With this option, enter the correct values for ldap.ldapAuthentication.bindDN and password parameters; the server uses the DN from the ldap.ldapAuthentication.bindDN attribute to bind to the directory.
        • SslClientAuth specifies SSL client authentication. With this option, set the value of the ldap.ldapconn.secureConn parameter to true and the value of the ldap.ldapAuthentication.clientCertNickname parameter to the nickname of the certificate to use for SSL client authentication.
      • ldap.basedn. Specifies the base DN for searching the authentication directory; the server uses the value of the uid field from the HTTP input (what a user enters in the enrollment form) and the base DN to construct an LDAP search filter.
      • ldap.minConns. Specifies the minimum number of connections permitted to the authentication directory. The permissible values are 1 to 3.
      • ldap.maxConns. Specifies the maximum number of connections permitted to the authentication directory. The permissible values are 3 to 10.
    6. Click OK.
  4. Customize the enrollment forms by configuring the inputs in the certificate profiles. Include the information that will be needed by the plug-in to authenticate the user. If the default inputs do not contain all of the information that needs to be collected, submit a request created with a third-party tool.

11.2.3. Using Certificate-Based Authentication
Copy link

Certificate-based authentication is when a certificate is presented that verifies the identity of the requester and automatically validates and authenticates the request being submitted. This is most commonly used for renewal processes, when the original certificate is presented by the user, server, and application and that certificate is used to authenticate the request.

There are other circumstances when it may be useful to use certificate-based authentication for initially requesting a certificate. For example, tokens may be bulk-loaded with generic certificates which are then used to authenticate the users when they enroll for their user certificates or, alternatively, users can be issued signing certificates which they then use to authenticate their requests for encryption certificates.

The certificate-based authentication module, SSLclientCertAuth, is enabled by default, and this authentication method can be referenced in any custom certificate profile.

11.2.4. Configuring Flat File Authentication
Copy link

A router certificate is enrolled and authenticated using a randomly-generated PIN. The CA uses the flatFileAuth authentication module to process a text file which contains the router’s authentication credentials.

11.2.4.1. Configuring the flatFileAuth Module
Copy link

Flat file authentication is already configured for SCEP enrollments, but the location of the flat file and its authentication parameters can be edited.

  1. Open the CA Console. 

    pkiconsole https://server.example.com:8443/ca
    Copy to Clipboard Toggle word wrap
    Note

    pkiconsole is being deprecated.

  2. In the Configuration tab, select Authentication in the navigation tree.

  3. Select the flatFileAuth authentication module.

    flatfileauth1
    View larger image
    flatfileauth1
  4. Click Edit/View.

  5. To change the file location and name, reset the fileName field.

    To change the authentication name parameter, reset the keyAttributes value to another value submitted in the SCEP enrollment form, like CN. It is also possible to use multiple name parameters by separating them by commas, like UID,CN. To change the password parameter name, reset the authAttributes field.

    flatfileauth2 fixed
    View larger image
    flatfileauth2 fixed
  6. Save the edits.

11.2.4.2. Editing flatfile.txt
Copy link

The same flatfile.txt file is used to authenticate every SCEP enrollment. This file must be manually updated every time a new PIN is issued to a router.

By default, this file is in /var/lib/pki/pki-ca/ca/conf/ and specifies two parameters per authentication entry, the UID of the site (usually its IP address, either IPv4 or IPv6) and the PIN issued by the router. 

UID:192.168.123.123
PIN:HU89dj
Copy to Clipboard Toggle word wrap

Each entry must be followed by a blank line. For example: 

UID:192.168.123.123
PIN:HU89dj

UID:12.255.80.13
PIN:fiowIO89

UID:0.100.0.100
PIN:GRIOjisf
Copy to Clipboard Toggle word wrap

If the authentication entries are not separated by an empty line, then when the router attempts to authenticate to the CA, it will fail. For example: 

... flatfile.txt entry ...
UID:192.168.123.123
PIN:HU89dj
UID:12.255.80.13
PIN:fiowIO89

... error log entry ...
[13/Jun/{YEAR}:13:03:09][http-9180-Processor24]: FlatFileAuth: authenticating user: finding user from key: 192.168.123.123
[13/Jun/{YEAR}:13:03:09][http-9180-Processor24]: FlatFileAuth: User not found in password file.
Copy to Clipboard Toggle word wrap

11.3. CMC authentication plug-ins
Copy link

CMC enrollment allows an enrollment client to use a CMC Authentication plug-in for authentication, by which the certificate request is either pre-signed with an agent certificate or a user certificate, depending on the plug-in. The Certificate Manager automatically issues certificates when a CMC request signed with a valid certificate is received.

The CMC authentication plug-ins also provide CMC revocation for the client. CMC revocation allows the client to have the certificate request either signed by the agent certificate, or a verifiable user that owns the certificate, and then send such a request to the Certificate Manager. The Certificate Manager automatically revokes certificates when a CMC revocation request signed with a valid certificate is received.

Certificate System provides the following CMC authentication plug-ins:

CMCAuth

Use this plug-in when a CA agent signs CMC requests.

To use the CMCAuth plug-in, set the following in the enrollment profile: 

auth.instance_id=CMCAuth
Copy to Clipboard Toggle word wrap

By default, the following enrollment profiles use the CMCAuth plug-in:

  • For system certificates:

    • caCMCauditSigningCert
    • caCMCcaCert
    • caCMCECserverCert
    • caCMCECsubsystemCert
    • caCMCECUserCert
    • caCMCkraStorageCert
    • caCMCkraTransportCert
    • caCMCocspCert
    • caCMCserverCert
    • caCMCsubsystemCert

  • For user certificates:

    • caCMCUserCert
    • caECFullCMCUserCert
    • caFullCMCUserCert
CMCUserSignedAuth

Use this plug-in when users submit signed or SharedSecret-based CMC requests.

To use the CMCUserSignedAuth plug-in, set the following in the enrollment profile: 

auth.instance_id=CMCUserSignedAuth
Copy to Clipboard Toggle word wrap

A user-signed CMC request must be signed by the user’s certificate which contains the same subjectDN attribute as the requested certificate. You can only use a user-signed CMC request if the user already obtained a signing certificate which can be used to prove the user’s identity for other certificates.

A SharedSecret-based CMC request means that the request was signed by the private key of the request itself. In this case, the CMC request must use the Shared Secret mechanism for authentication. A SharedSecret-based CMC request is typically used to obtain the user’s first signing certificate, which is later used to obtain other certificates. For further details, see Section 11.4, “CMC SharedSecret authentication”.

By default, the following enrollment profiles use the CMCUserSignedAuth plug-in:

  • caFullCMCUserSignedCert
  • caECFullCMCUserSignedCert
  • caFullCMCSharedTokenCert
  • caECFullCMCSharedTokenCert

11.4. CMC SharedSecret authentication
Copy link

Use the Shared Secret feature to enable users to send unsigned CMC requests to the server. For example, this is necessary if a user wants to obtain the first signing certificate. This signing certificate can later be used to sign other certificates of this user.

11.4.1. Creating a Shared Secret token
Copy link

The The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide describes the workflow when using a Shared Secret Token. Depending on the situation, either an end entity user or an administrator creates the Shared Secret Token.

Note

To use the Shared Secret token, Certificate System must use an RSA issuance protection certificate. For details, see Enabling the CMC Shared Secret Feature section located in RHCS Planning, Installation, and Deployment Guide.

  • To create a Shared Secret Token, enter: 

    # CMCSharedToken -d /home/jsmith/certs_db -p SECret.123 -s RevocationShrTok -o /home/jsmith/RevocationShrTok.b64 -n "IssuanceProtectionSystemCert" --oaep
    Copy to Clipboard Toggle word wrap

Use oaep if the server is configured to do so.If you use an HSM, additionally pass the -h token_name option to the command to set the HSM security token name.

For further details about the CMCSharedToken utility, see the CMCSharedToken(8) man page.

Note

The generated token is encrypted and only the user who generated knows the password. If a CA administrator generates the token for a user, the administrator must provide the password to the user using a secure way.

After creating the Shared Token, an administrator must add the token to a user or certificate record. For details, see Section 11.4.2, “Setting a CMC Shared Secret”.

11.4.2. Setting a CMC Shared Secret
Copy link

Depending on the planned action, an administrator must store a Shared Secret Token after generating it in the LDAP entry of the user or certificate.

For details about the workflow and when to use a Shared Secret, see the The Shared Secret Workflow section in the Red Hat Certificate System Planning, Installation, and Deployment Guide.

  • To use the Shared Secret Token for certificate enrollment, store it as an administrator in the LDAP entry of the user: 

    # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

	dn: uid=user_name,ou=People,dc=example,dc=com
	changetype: modify
	replace: shrTok
	shrTok: base64-encoded_token
    Copy to Clipboard Toggle word wrap

  • To use the Shared Secret Token for certificate revocations, store it as an administrator in the LDAP entry of the certificate to be revoked: 

     # ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x

	dn: cn=certificate_id,ou=certificateRepository,ou=ca,o=pki-tomcat-CA
	changetype: modify
	replace: shrTok
	shrTok: base64-encoded_token
    Copy to Clipboard Toggle word wrap

11.5. Testing enrollment
Copy link

For information on testing enrollment through the profiles, see Chapter 3, Certificate profiles (Making Rules for Issuing Certificates). To test whether end users can successfully enroll for a certificate using the authentication method set:

  1. Open the end-entities page. 

    https://server.example.com:8443/ca/ee/ca
    Copy to Clipboard Toggle word wrap
  2. In the Enrollment tab, open the customized enrollment form.
  3. Fill in the values, and submit the request.
  4. Enter the password to the key database when prompted.

  5. When the correct password is entered, the client generates the key pair.

    Do not interrupt the key-generation process. Upon completion of the key generation, the request is submitted to the server to issue the certificate. The server subjects the request to the certificate profile and issues the certificate only if the request meets all the requirements.

    When the certificate is issued, install the certificate in the browser.

  6. Verify that the certificate is installed in the browser’s certificate database.
  7. If PIN-based directory authentication was configured with PIN removal, re-enroll for another certificate using the same PIN. The request should be rejected.

11.5.1. Registering custom authentication plug-ins
Copy link

Custom authentication plug-in modules can be registered through the CA Console. Authentication plug-in modules can also be deleted through the CA Console. Before deleting a module, delete instances that are based on that module.

Note

For writing custom plug-ins, refer to the Authentication Plug-in Tutorial.

  1. Create the custom authentication class. For this example, the custom authentication plug-in is called UidPwdDirAuthenticationTestms.java.

  2. Compile the new class. 

    javac -d . -classpath $CLASSPATH UidPwdDirAuthenticationTestms.java
    Copy to Clipboard Toggle word wrap

  3. Create a directory in the CA’s WEB-INF web directory to hold the custom classes, so that the CA can access them for the enrollment forms. 

    mkdir /usr/share/pki/ca/webapps/ca/WEB-INF/classes
    Copy to Clipboard Toggle word wrap

  4. Copy the new plug-in files into the new classes directory, and set the owner to the Certificate System system user (pkiuser). 

    cp -pr com /usr/share/pki/ca/webapps/ca/WEB-INF/classes

chown -R pkiuser:pkiuser /usr/share/pki/ca/webapps/ca/WEB-INF/classes
    Copy to Clipboard Toggle word wrap

  5. Log into the console. 

    pkiconsole https://server.example.com:8443/ca
    Copy to Clipboard Toggle word wrap
    Note

    pkiconsole is being deprecated.

  6. Register the plug-in.

    1. In the Configuration tab, click Authentication in the navigation tree.

    2. In the right pane, click the Authentication Plug-in Registration tab.

      The tab lists modules that are already registered.

    3. To register a plug-in, click Register.

      The Register Authentication Plug-in Implementation window appears.

    4. Specify which module to register by filling in the two fields:

      • Plugin name. The name for the module.
      • Class name. The full name of the class for this module. This is the path to the implementing Java™ class. If this class is part of a package, include the package name. For example, to register a class named customAuth in a package named com.customplugins, the class name is com.customplugins.customAuth.

  7. After registering the module, add the module as an active authentication instance.

    1. In the Configuration tab, click Authentication in the navigation tree.
    2. In the right pane, click the Authentication Instance tab.
    3. Click Add.
    4. Select the custom module, UidPwdDirAuthenticationTestms.java, from the list to add the module. Fill in the appropriate configuration for the module.

  8. Create a new end-entity enrollment form to use the new authentication module. 

    cd /var/lib/pki/pki-tomcat/ca/profiles/ca

cp -p caDirUserCert.cfg caDirUserCertTestms.cfg

vi caDirUserCertTestms.cfg

desc=Test ms - This certificate profile is for enrolling user certificates with directory-based authentication.
visible=true
enable=true
enableBy=admin
name=Test ms - Directory-Authenticated User Dual-Use Certificate Enrollment
auth.instance_id=testms
...
    Copy to Clipboard Toggle word wrap

  9. Add the new profile to the CA’s CS.cfg file.

    TIP

    Back up the CS.cfg file before editing it. 

    # vim /var/lib/pki/instance-name/ca/conf/CS.cfg

profile.list=caUserCert,caDualCert,caSignedLogCert,caTPSCert,caRARouterCert,caRouterCert,caServerCert,caOtherCert,caCACert,caInstallCACert,caRACert,caOCSPCert,caTransportCert,caDirUserCert,caAgentServerCert,caAgentFileSigning,caCMCUserCert,caFullCMCUserCert,caSimpleCMCUserCert,caTokenDeviceKeyEnrollment,caTokenUserEncryptionKeyEnrollment,caTokenUserSigningKeyEnrollment,caTempTokenDeviceKeyEnrollment,caTempTokenUserEncryptionKeyEnrollment,caTempTokenUserSigningKeyEnrollment,caAdminCert,caInternalAuthServerCert,caInternalAuthTransportCert,caInternalAuthKRAstorageCert,caInternalAuthSubsystemCert,caInternalAuthOCSPCert,DomainController,caDirUserCertTestms
...
profile.caDirUserCertTestms.class_id=caEnrollImpl
profile.caDirUserCertTestms.config=/var/lib/pki/pki-tomcat/ca/profiles/ca/caDirUserCertTestms.cfg
    Copy to Clipboard Toggle word wrap

  10. Restart the CA. 

    pki-server restart instance_name
    Copy to Clipboard Toggle word wrap

11.6. Manually reviewing the certificate status
Copy link

To review certificate requests, ensure that you are authenticated as an agent with proper permissions to approve certificate requests. For details about configuring the pki command-line interface, see Section 2.5.1.1, “pki CLI initialization”.

To review the requests using the CLI:

  1. Display the list of pending certificate requests: 

    $ pki agent_authentication_parameters ca-cert-request-find --status pending
    Copy to Clipboard Toggle word wrap

    This command lists all pending certificate requests.

  2. Download a particular certificate request: 

    $ pki agent_authentication_parameters ca-cert-request-review id --file request.xml
    Copy to Clipboard Toggle word wrap
  3. Open the request.xml file in an editor or a separate terminal, and review the contents of the request to ensure it is legitimate. Then answer the prompt: if the request is valid, answer approve and press Enter. If the request is invalid, answer reject and press Enter. Organizations can subscribe semantic differences to reject and cancel; both result in no certificate being issued.

To review the requests using Web UI:

  1. Open the following URL in a web browser: 

    https://server_host_name:8443/ca/agent/ca
    Copy to Clipboard Toggle word wrap
  2. Authenticate as an agent. For information about authenticating as a user and configuring your browser, see Section 2.4.1, “Browser initialization”.
  3. On the sidebar on the left, click the List requests link.
  4. Filter the requests by selecting Show all requests for Request type and Show pending requests for Request status.

  5. Click Find in the lower right corner.

    list requests
    View larger image
    list requests
  6. The results page lists all pending requests waiting for review. Click on the request number to review a request.

  7. Review the request information and ensure that it is a legitimate request. If necessary, modify the policy information to correct any mistakes or make any desired changes to the certificate, such as changing the not valid after field. Optionally, leave an additional note.

    additional notes
    View larger image
    additional notes

    The drop down menu includes several review status updates. Select Approve request to approve the request or Reject request to deny it, and click Submit. Organizations can subscribe semantic differences to Reject request and Cancel Request; both result in no certificate being issued.

Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

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.

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

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

Theme

© 2025 Red Hat