In this document, you will learn how to add a public and private SSL key, also called an SSL certificate and key, for use in a database sync in the Civis Platform. SSL Key Pairs are used to verify that the connection to the database is from a trusted and authorized source.
In order to add an SSL key and certificate, a user will need to first generate both of these files in PEM format. Doing so is outside the scope of this guide, and will depend on your database settings. Please work with the administrators of the database to which you wish to connect for guidance on how to do so.
Step 1: Add the SSL Keys to Platform
The first step is to add the public and private SSL Keys to Civis Platform as credentials. These credentials should be of type "Certificate".
Adding the Private Key to Platform
- Navigate to your “Credentials” page in the Platform UI, under the “Admin” dropdown.
The Location of the “Credentials” page in the Civis Platform UI, under the “Admin” dropdown in the top-right corner of the page. - Click on the “Create Credential” button in the top right corner.
- For the type of the new Credential, choose “Certificate”.
- The username field is unused for this type, so place any value there.
- Place the contents of your PEM file in the “password” field. The value should start with a line that says “-----BEGIN PRIVATE KEY-----”, and end with a line that says “-----END PRIVATE KEY-----”. There should be only a single entry (defined by text between the aforementioned delimiters) in this file.
- Leave the “Remote Host” dropdown blank.
When complete, your credential form for the private key should look something like this:
A sample private key configuration. The credential is of type "Certificate", and the password contains the certificate in PEM format.
Once you are satisfied, click “Save”.
Adding the Public Key to Platform
- Navigate to your “Credentials” page in the Platform UI, under the “Admin” dropdown.
The Location of the “Credentials” page in the Civis Platform UI, under the “Admin” dropdown in the top-right corner of the page. - Click on the “Create Credential” button in the top right corner.
- For the type of the new Credential, choose “Certificate”.
- The username field is unused for this type, so place any value there.
- Place the contents of your PEM file in the “password” field. The value should start with a line that says “-----BEGIN CERTIFICATE-----”, and end with a line that says “-----END CERTIFICATE-----”. There should be only a single entry (defined by text between the aforementioned delimiters) in this file.
- Leave the “Remote Host” dropdown blank.
When complete, your credential form for the public key should look something like this:
A sample public key configuration. The credential is of type "Certificate", and the password contains the certificate in PEM format.
Once you are satisfied, click “Save”.
Step 2: Verify Your Database URL
Now that the SSL keys are present in Civis Platform, you will also need to ensure that your database knows to establish an SSL connection. To do this, you may need to add additional parameters to your database URL in Civis Platform. This is, again, dependent on your database management system and the version of your database management system:
- For PostgreSQL: add “ssl=true”, “sslfactory=org.postgresql.ssl.DefaultJavaSSLFactory” and minimally “sslmode=require” depending on whether or not you’ve added server certificates. For more info, see Civis Documentation on Adding A Server Certificate and The PostgreSQL documentation. Note: adding a server certificate may be required.
Use of SSL keys is not currently supported for MySQL, Oracle, Redshift, Snowflake or SQL Server databases. Please contact Civis Support for more options with these databases.
Step 3: Use the Key Pair in the Import
Now that the keys have been added as credentials, they can be used in an import. First, create a new import, or navigate to an existing one. In the top configuration for the “Source” and “Destination”, where a database and credential can be picked, click the arrow to drop down more options for the appropriate database.
In the dropdown that says “Select SSL Key”, select the credential corresponding to your SSL Private key. In the dropdown that says “Select SSL Certificate”, select the credential corresponding to your SSL public key.
An example configuration will look like this:
A sample database sync source configuration using an SSL key and certificate. The Private key is selected from the dropdown which says "Select SSL Key" and the public key is selected from the dropdown which says "Select SSL Certificate".
Once the keys have been added, future runs of the database sync will use them in connections automatically.
Comments
0 comments
Please sign in to leave a comment.