How to Connect to Fluid Topics Using mTLS - Fluid Topics - Latest

Mutual TLS (mTLS) is an authentication method used by Fluid Topics to secure incoming API calls.

To implement mTLS in an environment, it is necessary to provide a certificate authority delivered by an internal certificate authority (CA). Once the CA created, it is possible to generate as many client certificate as necessary.

It is necessary to use a certificate issued by an internal CA, rather than from a public CA, because their function is fundamentally different. Public CAs are intended for server authentication, while an internal CA is used to check the identity of the user or application accessing an API.

The procedure for mTLS connection requires actions from a user and a CA administrator.

The following steps are for the CA administrator:

• Generate a CA certificate
• Sign a certificate signing request

The following steps are for the user:

• Create a certificate signing request
• Connect via mTLS

To establish trust between client applications and Fluid Topics, it is necessary to generate a certification authority (CA). This CA allows the creation of client mTLS certificates.

As a CA administrator, run the commands below in a terminal to generate a CA:

1. Run the following command to set environment variables:

   export SUBJECT="/C={YourCountry}/ST={YourStateOrProvince}/L={YourLocationOrCity}/O={YourOrganizationName}/CN={CertificateCommonName}"
   

2. Run the following command to define the $PREFIX variable:

   export PREFIX="{certificate-usage}"
   

3. Run the following command to generate the CA:

   openssl req -x509 -newkey rsa:4096 -keyout ./${PREFIX}-mtls-private-key-root-ca.key \
   -out ./${PREFIX}-mtls-root-ca.pem -sha256 -days 3650 -nodes -subj "$SUBJECT"
   

This script generates a .key file and a .pem file, located in the current working directory. Send the .pem file to a Fluid Topics representative for deployment.

Below in an example for a fictional company called "Any Org" based in London, England. The use case is connecting Salesforce to Fluid Topics.

1. Set environment variables:

   export SUBJECT="/C=UK/ST=England/L=London/O=Any Org/CN=sftofluid-prod-mtls"
   

2. Define the $PREFIX variable:

   export PREFIX="sftofluid-prod"
   

3. Generate the CA certificate:

   openssl req -x509 -newkey rsa:4096 -keyout ./${PREFIX}
   -mtls-private-key-root-ca.key \
   -out ./${PREFIX}-mtls-root-ca.pem -sha256 -days 3650 -nodes -subj "$SUBJECT"
   

Once the .pem file generated and shared, it is possible to create a certificate signing request (CSR) for each user or application that needs to connect to Fluid Topics via mTLS.

As a user, run the commands below in a terminal to generate a CSR:

1. Run the following command to set environment variables:

   export SUBJECT="/C={YourCountry}/ST={YourStateOrProvince}/L={YourLocationOrCity}/O={YourOrganization Name}/OU={YourOrganizationalUnitOrDepartment}/CN={CertificateCommonName}"
   

2. Run the following command to define the CSR's name:

   export NAME={TheUsersName}
   

3. Run the following command to create a directory for the CSR:

   mkdir ./user-certificate
   

4. Run the following command to generate a private key:

   openssl genrsa -out ./user-certificate/$NAME.private.key 2048
   

5. Run the following command to generate the certificate signing request:

   openssl req -new -sha256 -key ./user-certificate/$NAME.private.key -subj "$SUBJECT" -out ./user-certificate/$NAME.csr
   

The script generates a .private.key file and a .csr file, located in the current working directory. Send the .csr file to the CA administrator who previously generated the CA certificate.

Below is an example of how the preceding script could be modified using a fake company called "Any Org" based in London, England, for the user John Doe in the engineering department:

1. Set environment variables:

   export SUBJECT="/C=UK/ST=England/L=London/O=Any Org/OU=Any Org Engineering/CN=John-Doe"
   

2. Define the CSR's name:

   export NAME="johndoe"
   

3. Create a directory for the CSR:

   mkdir ./user-certificate
   

4. Generate a private key:

   openssl genrsa -out ./user-certificate/$NAME.private.key 2048
   

5. Generate a certificate signing request:

   openssl req -new -sha256 -key ./user-certificate/$NAME.private.key -subj "$SUBJECT" -out ./user-certificate/$NAME.csr
   

The CA administrator can sign the certificate signing request (CSR) and share the signed certificate (CRT) with the user as follows:

1. Run the following command to define the validity period of the certificate:

   export VALIDITY={number of days}
   

2. Run the following command to define the name of the signed certificate (use the same name as the CSR):

   export NAME="{username}"
   

3. Run the following command to generate a certificate (.crt file):

   openssl x509 -req -CAcreateserial \
   
   -in /path/to/$NAME.csr \
   
   -CA /path/to/{PREFIX}-mtls-root-ca.pem \
   
   -CAkey /path/to/{PREFIX}-mtls-private-key-root-ca.key \
   
   -out /path/to/$NAME.crt \
   
   -days {VALIDITY} -sha256
   

4. Run the following command to remove the CSR:

   rm /path/to/$NAME.csr
   

After creating the signed certificate in .crt format, the CA administrator sends it to the user. The user can then pair the .crt file with a personal private key to connect via mTLS.

Below in an example for the following fictional values:

• The user is named "John Doe", and The johndoe.csr file is located in the /Users/admin/Documents directory.
• The organization's CA certificate is named sftofluid-prod-mtls-root-ca.pem and is located in /Users/admin/Documents.
• The private key is named sftofluid-prod-mtls-private-key-root-ca.key and is located in /Users/admin/Documents.
• The intended output name of the file is johndoe.crt and its destination is /Users/admin/Documents/.
• The intended validity period is 2 years.

Run the following commands:

1. Define the validity period of the certificate:

   export VALIDITY=730
   

2. Define the name of the signed certificate:

   export NAME="johndoe"
   

3. Generate a CRT:

   openssl x509 -req -CAcreateserial \
   -in /path/to/$NAME.csr \
   -CA /Users/admin/Documents/sftofluid-mtls-root-ca.pem \
   -CAkey /Users/admin/Documents/sftofluid-mtls-private-key-root-ca.key \
   -out /Users/admin/Documents/$NAME.crt \
   -days {VALIDITY} -sha256
   

4. Remove the CSR:

   rm /Users/admin/Documents/$NAME.csr
   

After receiving a signed certificate (.crt) from the CA administrator, pairing it with a private key (.private.key) allows connection to the Fluid Topics API via mTLS.

Run the following commands to create an API call to Fluid Topics via mTLS:

1. Run the following command to define the API endpoint:

   export API_URL="{https://xxxx-api.fluidtopics.net/api/khub/locales}"
   

2. Run the following command to define the $API_KEY variable.

   export API_KEY="{MY_API_KEY}"
   

3. Run the following command to establish an mTLS connection:

   curl $API_URL \
   
   --header "Authorization: Bearer $API_KEY" \
   
   --header "Content-Type: application/json" \
   
   --cert /path/to/certificate.crt \
   
   --key /path/to/private.key
   

Below in an example in which the use case is to list all the maps in a Fluid Topics portal using the johndoe.crt certificate, located in /Users/john/Documents. The private key is named johndoe.private.key and is also saved in /Users/john/Documents:

1. Define the endpoint:

   export API_URL="https://anyorg-api.fluidtopics.net/api/khub/maps"
   

2. Define the API key variable:

   export API_KEY="QAvt9wRiNb4FbJ4xupng0o2T968jnA1t"
   

3. Establish mTLS connection:

   curl $API_URL \
   --header "Authorization: Bearer $API_KEY" \
   --header "Content-Type: application/json" \
   --cert /Users/john/Documents/johndoe.crt \
   --key /Users/john/Documents/johndoe.private.key