Certificates
Your system uses SSL to provide security for the Admin App. To enable SSL security, you need a valid SSL server certificate or chain of certificates.
Your system comes with its own self-signed SSL server certificate, which is generated and installed automatically when the system is installed. This certificate is not automatically trusted by web browsers.
You can choose to trust this self-signed certificate to replace the certificate with either one from a certificate authority (CA) or one that you create yourself. You can also have the system generate and install a new self-signed SSL server certificate. You do this, for example, if the current certificate is close to expiring and you are waiting to retrieve a new one from your CA.
Viewing installed certificates
You can use the REST API, CLI, and Admin App to view information about:
- The system certificate. This is the certificate used to secure communications for your system's applications, CLIs, and REST APIs.
- Data source certificates. These are the certificates retrieved from the systems that your system has connected to using a data connection.
For each certificate, you can view:
- The distinguished name of the certificate
- The date and time when the certificate goes (or went) into effect
- The date and time when the certificate expires (or expired)
Procedure
Select the Configuration window.
Click Certificates.
The System tab displays the currently active system certificate.To view the data source certificates, select the Client tab.
Related CLI commands
listCertificates
getCertificate
getSystemCertificate
Related REST API methods
GET /certificates
GET /certificates/system
GET /certificates/{subjectDn}
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Adding data source certificates
For your system to retrieve documents from a data source that uses SSL-protected communication, it must accept the certificate from the data source. Your system prompts you to accept a data source certificate when testing the connection to the data source. You can also upload data source certificates manually.
Retrieving data source certificates automatically
Procedure
Click Configuration.
Click Data Connections window.
Click the data connection you want.
Click Test.
If the system can connect to the data source, you are prompted to accept its certificate.
Click Accept and Add Certificate.
Uploading data source certificates manually
Procedure
Retrieve the SSL certificate from your data source.
In the Admin App, click Configuration.
Click Certificates.
On the Client tab, click Upload Client Certificate.
Drag the certificate file into the Upload Certificate box.
Related CLI commands
testDataSource
createCertificate
Related REST API methods
POST /datasources/test
POST /certificates
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Changing the system certificate
By default, your system includes a self-signed certificate when the system is first installed.
You cannot delete the currently installed certificate. However, you can replace it by:
- Installing a new PKCS12 certificate
- Generating and installing a new self-signed certificate
- Generating a certificate signing request (CSR) and installing the certificate you receive in response to this request
System certificate considerations
Keep the following in mind when configuring SSL certificates for your system, especially if you are configuring the system to use one or more certificates that you create yourself:
- Do not allow any of the SSL certificates to expire.
- Adhere to the established best practices for setting up SSL certificates. For example, if
you are using wildcards to identify hostnames in an SSL certificate, a wildcard should
appear only at the beginning of the hostname, not in the middle.
For information on SSL best practices, see http://tools.ietf.org/html/rfc5280 and http://tools.ietf.org/html/rfc6125.
- Ensure that the DNS name for the system matches the name defined in the certificate.
- When configuring a certificate chain, ensure that all intermediate issuers have the appropriate signing authority permissions so that the entire chain is signed.
Installing a certificate you created
You can create an SSL server certificate by using a third-party tool such as OpenSSL. When creating the certificate, you specify two passwords, one for the PKCS12 object containing the certificate and one for the private key for the certificate. To use the certificate with your system, these passwords must be the same.
When you create your own SSL server certificate, you can choose to have that certificate signed by a certificate authority (CA). In this case, the CA you use may provide you with one or more intermediate certificates. These certificates are used in conjunction with the SSL server certificate you created to establish a certificate chain, which is an ordered list of certificates in which each certificate is trusted by the next.
To preserve the chain of trust among the certificates, you need to upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see your CA.
To install your certificates:
Procedure
Select the Configuration window.
Click Certificates.
Click Update System Certificate.
On the PKCS12 window, drag your certificate into the Upload Certificate Chain box.
In the PKCS12 Password field, type the password for your certificate.
Drag the certificate into the Upload Certificate Chain box.
Click Continue.
Click Accept.
Related CLI commands
uploadPKCS12Certificate
applyCertificateChanges
Related REST API methods
POST /certificates/system/pkcs12
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Installing a new self-signed certificate
Your system can generate and install a new self-signed SSL server certificate. The new certificate is good for five years.
Procedure
Select the Configuration window.
Click Certificates.
Click Update System Certificate.
Select the Self-Signed window.
Click Continue.
Your system generates a new self-signed server certificate.Click Accept.
Your system installs the new certificate.To continue using the Admin App, log out and then log back in.
Related CLI commands
generateSelfSignedCertificate
applyCertificateChanges
Related REST API methods
POST /certificates/system/selfsigned
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Creating a CSR and installing the returned certificate
SSL server certificates are available from several trusted sources. To obtain a certificate created by a certificate authority (CA), you need to create a certificate signing request (CSR) and give it to the CA. The CA then generates the requested certificate and makes it available to you.
Creating a certificate signing request
You can create a CSR using the Admin App or a third-party tool. When you use the Admin App, the system securely stores the private key needed for installing the returned certificate, so you don’t need to save the key yourself.
It's best to verify what information is required with the CA that you plan to use.
Procedure
Select the Configuration window.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Choose Generate a new certificate signing request and click Continue.
Fill in the following as needed:
- In the box Common Name (CN), type the DNS name of the system preceded by an asterisk (*) and a period (.) (for example, *.system.example.com).
The Common Name (CN) is required.
- In the box Organizational Unit (OU), type the name of the organizational unit that uses the system (for example, the name of a division or a name under which the company does business).
- In the box Organization (O), type the full legal name of the organization.
- In the box Location (L), type the name of the city in which the organization's headquarters are located.
- In the box State/Province (ST), type the full name of the state or province in which the organization's headquarters are located.
- In the box Country (C), type the two-letter ISO 3166-1 abbreviation for the country in which the organization's headquarters are located (for example, US for the United States).
- In the box Common Name (CN), type the DNS name of the system preceded by an asterisk (*) and a period (.) (for example, *.system.example.com).
Click Generate CSR.
The page displays the generated certificate request.Copy and paste the request text into a file and send that file to the CA.
Related CLI commands
generateCSR
Related REST API methods
PUT /certificates/system/csr
You can get help on specific REST API methods for the Admin App at REST API - Admin.
Installing the certificates returned for a system-generated CSR
In response to a CSR, your CA gives you an SSL server certificate and any required intermediate certificates. These certificates are used in conjunction with the SSL server certificate to establish a certificate chain, an ordered list of certificates in which each certificate is trusted by the next. You need to upload and install these certificates on your system.
To preserve the chain of trust among the certificates, you need to upload the certificates in the correct order. That is, each certificate you upload must be immediately followed by the certificate that signs it. For information on the correct order for the certificate chain, see your CA.
Procedure
Select the Configuration window.
Click Certificates.
Select the System tab.
Click Update System Certificate.
Select the CSR window.
Select the I already generated a CSR and obtained a signed certificate option and then click Continue.
Drag the certificate into the Upload certificate obtained from Certificate Authority box.
Click Accept.
Related CLI commands
uploadCSR
applyCertificateChanges
Related REST API methods
POST /certificates/system/csr
POST /certificates/system
You can get help on specific REST API methods for the Admin App at REST API - Admin.