Smarter by Design.Simpler for Business
Client Certificates
What Is a Client Certificate?
Client Certificate is the certificate that proves who is connecting in a TLS connection. While the certificates on the SSL/TLS Certificates screen are the identity TR7 offers to the clients as a server, the certificates on this screen are used in the connections in which TR7 is the client: TR7 introduces itself with this certificate in the TLS connection it establishes to the Backend Service (backend) and in the health checks it makes to the Backend Service (mutual TLS, mTLS).
The record is created in two ways: it is produced with an internal CA on TR7 (the person or device name, the e-mail addresses, the Windows logon names and the personnel/asset number are written to the certificate), or an existing certificate the corporate CA has issued is imported together with its key. The certificate and the key cannot be changed after the record is created; only the name and the offered chain are edited.
2
Adding method
Issue from an internal CA or Import an existing certificate (PEM)
Identity
Certificate content
CN, O, OU, C, the personnel number; the e-mail address and the Windows logon name (UPN) as a SAN
clientAuth
Key usage
In the internal CA production Client Authentication is added in every case
30 days
Period health
The Valid until column becomes orange 30 days before the end and red when it has expired
mTLS
Usage location
The Backend Service connection and the health checks; it is not offered in the vServices
CA profile
The offered chain
The intermediate and root certificates are offered with a reference to the CA records; they can be edited
How does it work?
- In the production from an internal CA, an issuing CA with client usage on the Certificate Authorities (CA) screen and a profile with Client / mTLS usage on the Certificate Profiles screen are selected; TR7 produces the key, cuts the certificate with the period and the algorithm in the profile and binds the chain from the CA hierarchy.
- In the importing the certificate and the private key are pasted as PEM; the pair is validated and the key is stored encrypted on the device.
- The record is selected in the Client Certificate presented to backend (mTLS) field on the Backend Services screen or in the Client Certificate to present (mTLS) field of the health check; TR7 offers the certificate together with its chain while it is establishing the connection.
- The period of the certificate is tracked with a color in the list; the client certificates are not renewed by themselves, a new record is produced and the assignments are updated before it expires.
Identity Fields
In the certificate produced with an internal CA there are two types of identity information:
| Field | Its place in the certificate | Description |
|---|---|---|
| Person or Device (CN) | The subject CN | The name of the person or the device; it is shown in the Person or Device column in the list. |
| Organization (O), Organizational Unit (OU), Country (C) | The subject | The organization, the unit and the two-letter country code. |
| Staff / Asset Number | The subject serialNumber | The personnel or asset number; it is shown in the Staff No column in the list. |
| E-mail Addresses | SAN (e-mail) | The e-mail addresses of the account the certificate represents. |
| Windows Logon Names (UPN) | SAN (the Windows logon name) | The Windows account; in the Account column in the list the first UPN, or the first e-mail if there is none, is shown. |
A domain name (DNS) is not written to a client certificate; the certificate identifies an account, not a server. The content of the imported certificate is resolved as well; however, because the subject and account fields are written to the record only in the internal CA production, the identity columns in the list are seen as - in the imported records and only the end of the validity comes filled.
Operational Best Practices
- The CA and the profile first. For production from an internal CA, an issuing CA whose area of use is client and a profile with Client / mTLS usage must be defined beforehand; the form does not allow these records to be added without leaving the page and if the selectors are empty the record cannot be completed.
- The CA the Backend Service trusts. In order for the certificate produced from an internal CA to be accepted by the Backend Service, the (root and intermediate) certificates of the CA must be added to the trust store of the Backend Service.
- Tracking the period. The client certificates are not renewed by themselves and no period notification is produced; the color in the Valid until column must be tracked regularly and for a certificate whose period is approaching a new record must be produced and the Backend Service and health check assignments must be updated.
- The assignments before deleting. The deletion confirmation does not show the usage locations; the Backend Services and the health checks that use the record must be moved to another certificate before deleting.
- The completeness of the chain. If there is no intermediate certificate in the imported certificate, a CA record must be assigned with Intermediate Cert. CA Profile in the editing form; if the Backend Service cannot validate the chain, it rejects the connection.
How to Add?
A new Client Certificate is added over the TR7 web management interface with the following steps:
- The Configuration Menu is opened by clicking the TR7 logo at the bottom left.
- The Certificates & PKI → Client Certificates → Add steps are followed; the form opens as a closable Add tab inside the list screen.
- A name is entered for the certificate; Issue from an internal CA or Import an existing certificate is selected in the How to add field and the fields that are seen are filled in (for the details of the fields see the Adding Form section).
- The certificate is produced or imported by clicking the
Addbutton.
TIP
Reaching the page via quick search
Instead of navigating the menu step by step, the related page is reached directly by using the search bar in the bottom left corner of the screen. The search bar opens with the Alt + T shortcut on Windows and Opt + T on macOS; typing the name of the feature being searched for is then sufficient.
The Client Certificates Listing Screen
The list of all the client certificates that are added on the TR7 device is reached by following the Certificates & PKI → Client Certificates path. The certificate adding, editing and deleting operations are done through this screen.
The Client Certificates Listing Form
The table opens with the following columns by default:
| Column | Description |
|---|---|
| Certificate Name | The name of the record. |
| Person or Device | The CN value of the certificate; in the imported records, -. |
| Account | The account the certificate represents: the first Windows logon name (UPN), or the first e-mail address if there is none, or -. When the cell is hovered over, all the Windows logon names are listed; if there is no UPN in the certificate, even though the cell shows the e-mail address the tooltip displays -. |
| Staff No | The personnel or asset number; if there is none, -. |
| Source | The source of the record: Issued by the internal PKI or Imported. |
| Issuing CA | The link to the internal CA that produces the certificate; in the imported records, -. |
| Valid until | The end of the validity; at the beginning a colored circle that shows the period status and that gives the status text when it is hovered over (green Valid, orange Expiring Soon, red Expired), and at the end the abbreviation of the remaining period (12d, 8mo, 3y; Expired in the ones that have expired). In the records that have not expired, the number of days remaining is seen when the abbreviation is hovered over. |
The period status is determined according to the number of days remaining until the end: more than 30 days Valid, 0–30 days Expiring Soon, and if it has expired Expired.
There is no column hidden by default; these seven columns take place in the column selector. The certificate and key content is not shown in any column. The table is not sorted when it is opened; when a column header is clicked, first a descending and then an ascending sorting is applied, and at the third click the sorting is removed.
The items in the toolbar are arranged from left to right in the following order; the last two items (Page Information and Page Size) are located in the information strip below the table.
Columns
Which columns are shown in the table is selected; all seven columns are on by default. In the same panel, columns are reordered by dragging and alignment is selected per column; the row height is fitted to the page with the Fit rows to the page button, and the column layout is reset to default with the Reset button. When the width badge next to a manually widened column is clicked, the column returns to the automatic width. The layout is stored per user.
Filter
The Filter button is used in order to filter the certificates shown in the list according to certain criteria; the button shows the number of active filters with a badge. In the strip there is a single card: Used in. The card always offers the Unused Entries value; a certificate that is used in a definition remains outside this value. Which Backend Service a certificate is used in is tracked from the Used in tab in the preview panel and from the Backend Services screen.
Export
The table is exported as Excel, CSV or PDF by clicking the Export button. In the window that opens, the Filename, Format and Data Source, together with the Columns to be exported, are determined; the remaining fields are displayed according to the format: CSV Separator for CSV, Excel Sheet Name for Excel, and Page Orientation and Page Size for PDF.
There is no certificate and key content in the exported table.
Add
By clicking the Add button, a new certificate creation form is opened in the Add tab.
Delete
When one or more certificates are selected and the Delete button is clicked, the related certificates are deleted. Before the deletion the "Are you sure that you want to delete client certificate object?" (in a multiple selection "Are you sure you want to delete N client certificate objects?") confirmation is asked.
WARNING
A certificate that is in use can also be deleted and the confirmation window does not show the usage locations; before the deletion the Used in tab in the preview panel must be checked.
In the Backend Service that uses the record the selection is not cleared by itself: in the configuration applied after the deletion TR7 connects to that Backend Service without offering a client certificate and the service that asks for mTLS rejects the connection; another certificate must be selected by editing the Backend Service. The health checks that select the record fall into an error state because they cannot find the certificate (Client certificate for mTLS could not be resolved (certificate content or key is missing)). Nothing changes in the CA that produces the certificate; the deleted certificate is not taken into a revocation list. The deletion operation is written to the user operation record.
Edit
By clicking the Edit button, the editing form of the selected certificate is opened in the Edit tab. The button becomes active only when a single certificate is selected.
The editing form is different from the adding form and it contains four items: Certificate Name, the information box with the lock icon (The certificate, its key and the identity inside it cannot be changed — they are what the certificate SAYS, and changing them would mean issuing a new one. The chain presented with it and the download permission can still be adjusted.) and the Intermediate Cert. CA Profile and Root Cert. CA Profile fields that will be offered together with the certificate in the connection. These two fields are selected from the records on the Certificate Authorities (CA) screen; when Manual is selected, a CA record is not offered for that position. The certificate, key and identity fields cannot be changed and the Allow Download switch does not take place in the form; the change is saved without confirmation being asked and the configuration is applied again to the Backend Service connections that use the record.
Search
Used to search all information in the table.
RegExp Search
Used to search all information in the table with a regular expression (RegExp).
Column Based Search
It is used in order to search the information in the table based on the column; next to every box there are the Negate switch that inverts the result and its own RegExp option.
Usage Filter
It is used in order to filter which vServices the certificates are bound to. Because the records in this collection are not bound to the vServices directly, in the selector there is only the Unused Entries option and it is selected by itself; the list is limited to the records that are not used in any definition. While the filter is active, the selector takes the place of the search box; when the icon is clicked again, the search box returns.
Page Information
Information about the total number of defined certificates and the number of certificates displayed in the list takes place: Showing N-M of T records and the number of selected certificates (N selected, Nothing selected while there is no selection). If a selection has been made in the filter strip, the number of filters applied and the shown/total row information are added to the same row.
Page Size
The maximum number of certificates to be displayed on the page is selected. The default is 20; the options are 5, 10, 20, 50, 100, 200, 500 and All.
Right-Click Menu
When a row is right-clicked, a menu with the certificate's name in its title opens. Both operations in the menu apply only to the right-clicked certificate; a selection made in the list does not affect the menu. The re-signed certificate uploading, renewing and downloading operations in the certificate list are not present on this screen.
| Operation | What it does |
|---|---|
| Edit | Opens the editing form of the certificate in the Edit tab; it is the same as the form opened by the Edit button in the toolbar. |
| Delete | Deletes the right-clicked certificate; the same confirmation question as the deletion in the toolbar is displayed. |
The Preview of the Selected Certificate
When a row in the list is clicked, the preview of the certificate opens on the right of the screen; when the selected row is clicked again, the panel closes. In the header there are the identity badge icon, the name of the record and the Client certificate subheading, and at the top right there is a single operation.
The Preview of the Selected Certificate
| Operation | What it does |
|---|---|
| Edit | Opens the editing form of the certificate in the Edit tab. |
In the panel there are three tabs; the last one is displayed only if there is a definition that uses the certificate:
Details
Lists the identity and validity information of the record (the table below).
Log
Lists the user operations on the record (adding, editing, deleting) as a timeline.
Used in
Lists the definitions that use the certificate. The badge next to the tab name shows the number of usages; if there is no definition that uses the certificate, the tab is not displayed at all.
The rows in the Details tab are as follows, in order:
| Row | Description |
|---|---|
| Certificate Name | The name of the record. |
| Person or Device | The CN value; if there is none, -. |
| Logon Names (UPN / E-mail) | All the Windows logon names, or, if there are none, all the e-mail addresses separated with commas; if there are none, -. |
| Staff No | The personnel or asset number; if there is none, -. |
| Valid until | The end of the validity (the local date format of the browser). |
In the preview the source, the producing CA, the subject fields (O/OU/C), the key algorithm and the chain information are not listed; there is no chain tab.
The Certificate Adding Form
A new client certificate is added onto the TR7 device by following the Certificates & PKI → Client Certificates → Add steps.
The Client Certificates Certificate Adding Form
INFO
Certificate Name Required
The name of the record is entered. The name identifies the record in the list, in the certificate selection in the Backend Service and health check forms and in the logs, and it must be unique on the device; when the same name is entered, the form gives the Name is used warning.
INFO
How to add Default: Issue from an internal CA
- Issue from an internal CA: the certificate and the key are produced with an internal CA on TR7; the identity fields are seen.
- Import an existing certificate: an existing certificate and key are imported as PEM; the content fields are seen.
Issue from an internal CA
INFO
Issuing CA Required
The issuing internal CAs that are defined on the Certificate Authorities (CA) screen, whose area of use is client and that have a key and a certificate are listed. The root CAs, the CAs with server usage and the CAs whose enrollment is pending (that have not been signed yet) are not present in the list. A selection can be made only from the list; if there is no suitable CA, it must first be defined on the CA screen.
INFO
Certificate Profile Required
The profiles with Client / mTLS usage on the Certificate Profiles screen are listed; the profile determines the validity period, the key algorithm and the EKU values. A selection can be made only from the list.
INFO
Person or Device (CN) Required
The subject name of the certificate; at most 128 characters. Letters, digits, a space and the . - _ ( ) ' characters can be used; when another character is entered, the form gives the Contains characters that are not allowed in a certificate subject warning.
INFO
E-mail Addresses
The e-mail addresses that will be written to the certificate as a SAN. The values are entered line by line; a new line is added with the Add link below the field. A value whose format is invalid is rejected by the server and the certificate is not produced. It is optional.
INFO
Windows Logon Names (UPN)
The Windows logon names (user@domain) that will be written to the certificate as a SAN. The values are entered line by line; a new line is added with the Add link below the field. A value whose format is invalid is rejected by the server and the certificate is not produced. It is optional.
INFO
Organization (O)
The organization name in the subject; at most 128 characters, the same character rule as Person or Device (CN) applies. It is optional.
INFO
Organizational Unit (OU)
The unit name in the subject; at most 128 characters, the same character rule as Person or Device (CN) applies. It is optional.
INFO
Country (C)
The two-letter country code in the subject (TR); the placeholder of the field shows the TR value. When a value other than two letters is entered, the form gives the Country must be a 2-letter code (e.g. TR) warning. It is optional.
INFO
Staff / Asset Number
The personnel or asset number that will be written to the serialNumber field of the subject; at most 64 characters, the same character rule as the CN. It is optional.
Import an existing certificate
The Fields in the Import an Existing Certificate Selection
INFO
Certificate (PEM) Required
The PEM content of the certificate (-----BEGIN CERTIFICATE-----); it can also be uploaded by a file being dragged into the field (at most 64 KB; the DER and PKCS#7 formats are accepted and converted to PEM).
INFO
Private Key (PEM) Required
The PEM content of the private key of the certificate (-----BEGIN PRIVATE KEY-----). The key must match the certificate; if it does not match, the importing is rejected.
INFO
Key Passphrase (if encrypted)
If the private key is password protected, its password is entered.
The Fields Present in Both Selections
The field and the button below take place at the end of the form independently of the How to add selection.
INFO
Allow Download Default: off
The key is bound to the user who creates the record and only the owner of the record can move this key; in the old records whose owner is not registered a change gives an error. Because the field does not take place in the editing form, the value cannot be changed from the interface after the record is created. In this version there is no downloading or exporting operation for the client certificates; the key does not leave the device.
INFO
Add
The certificate adding operation is completed by clicking the Add button. As long as there is a field that has not been validated in the form, the button stays passive; in the production, if the enrollment of the CA has not been completed or if the CA does not have the signing permission, the operation is rejected with an error message.
Operating Mechanism
INFO
- The internal CA production. The subject is written in the C/O/OU/CN/serialNumber order; the e-mails and the UPNs are added as a SAN, a domain name is not added. The period, the key algorithm and the EKU come from the selected profile; if Client Authentication is not in the profile, it is added. The serial number is produced randomly as 128 bits. The chain is written to the record with a reference to the selected CA and its parent CAs (intermediate: the signing CA; root: the CA at the top of the hierarchy if it is of the root type, otherwise empty); the key is stored encrypted on the device. For the certificates produced on this screen a production record is not written to the Issued Certificates (Internal PKI) tab and an automatic renewal is not done.
- The importing. The certificate is converted to PEM, the key with a password is opened and it is validated that the pair matches; the source is saved as Imported. The validity date is read from the certificate; the subject and account fields are not carried into the list.
- Being applied to the configuration. The certificate selected in the Backend Service is bound to that vService in a single file together with the intermediate and root certificates and the key, and it is offered in the Backend Service connection. The health check offers the certificate with its intermediate certificates. When the selection changes, the related vService is restarted.
- The selection priority. When the Client Certificate to present (mTLS) field is left as None in the health check (it is shown as From the backend in the check preview), the certificate of the Backend Service is used; the certificate selected in the check takes precedence over that of the Backend Service. The Backend Service and check selectors list first the records of this screen and then the certificates on the SSL/TLS Certificates screen.
- The period and the notification. The color in the list is determined according to the 30 day threshold; for the client certificates a period notification is not produced and a renewal is not done.
- The cluster. The records are synchronized between the devices with the LB configuration together with their keys; the health check engine takes a copy of the collection.
- The logs. Adding, editing and deleting are tracked as the client certificate object on the User Logs screen.
Scope and Limits
INFO
- The permission. The screen is bound to the certificate permission area; in a user who does not have the permission the You don't have access to this page card is displayed instead of the page.
- The name is unique. A second record that carries the same name is not saved.
- The identity and the key cannot be changed. For a new identity or a new key a new record is produced.
- There is no renewal or exporting. The client certificates are not renewed by themselves; the Renew now (internal CA), Upload a re-signed certificate and PFX downloading operations are not present on this screen.
- The preconditions. For production from an internal CA an issuing CA with client usage and a Client / mTLS profile are needed; the form does not add these inline.
- There is no PFX in the importing. There is no PFX uploading field in the form and the private key is entered as PEM; the DER and PKCS#7 files dragged into the certificate field are accepted by being converted to PEM.
- There is no usage count. The Used in card and the Usage Filter do not show usage in this collection; the confirmation window does not list the usage locations before the deletion.
- It is not offered in the vServices. The records are not listed in the Certificate field of the vServices or in the TLS security profiles; the administrator certificates that are used for logging in to the management interface with a certificate are a separate mechanism.
Usage Locations
Old configurations
Both the Backend Service and the health check selector list the SSL/TLS Certificates records as well after this collection; during the resolution the client certificates are looked at first, and if it is not found, the server certificates. For this reason the old configurations in which a server certificate has been selected in the field continue to work.
The Backend Service Connection (mTLS)
In the Client Certificate presented to backend (mTLS) field of a Backend Service whose SSL is on, on the Backend Services screen, None, the client certificates on this screen and then the certificates on the SSL/TLS Certificates screen are listed. The selected certificate is offered in every TLS connection TR7 establishes to that Backend Service; in order for the Backend Service to be able to validate TR7, it must trust the CA that produces the certificate.
Health Checks
The same list is offered in the Client Certificate to present (mTLS) field of the health checks of the HTTPS, TCPS, SMTP (while STARTTLS is on), SMTPS, FTPS and LDAPS types. When the field is left as None (it is shown as From the backend in the check preview), the check uses the certificate of the Backend Service it is bound to; in the checks that are not bound to a Backend Service (GTM) the certificate is given only from this field. The certificate is sent only when the other side asks for it.
