Certificates in GridOS

All integrations to Connect cluster require a valid certificate. Only certificates issued or signed by the organization’s trusted Certificate Authorities (CAs) are accepted by the server. The organization’s trusted CA must be registered in Connect and the Client Certificates must be issued by that CA.

TLS

The key difference between TLS and mTLS is how certificates are exchanged. In TLS, only the server presents a certificate, whereas in mTLS, both the server and the client present certificates.

Connect Cluster CA Certificate

All Connect APIs require the Connect Cluster CA certificate, which can be copied from the Agent view in the GridOS Connect Console. Add this certificate to the trust store of any client (such as SDK Deployer or Connect Agent) that calls the Connect APIs.

GridOS Connect Console Agent configuration

mTLS

While TLS authenticates only the server, mTLS extends this process by also authenticating the client.

With mTLS, the server verifies the client’s certificate against a trusted Client Certificate Authority (CA), ensuring that only the trusted systems or applications can connect.

The Client CA Certificate is registered in the Connect platform. It is used to verify the client certificates presented by agents, applications, or other integrations.

Only certificates issued or signed by the organization’s trusted CA are accepted by the server. This creates a secure, two-way trust between Connect and your systems, protecting the platform from unauthorized access.

Client CA Certificate

You must upload the client-ca-cert to the GridOS Connect Console. The client-ca-cert is needed for the GridOS Connect main cluster server to verify the client-cert when the Agent is communicating with the Connect main cluster. Use these steps to upload the client-ca-cert:

Navigate to your GridOS Connect Console.
Select Certificates from the left navigation menu.
Select CREATE CERTIFICATE in the top right corner.
Select UPLOAD FILE, and select your client-ca-cert PEM file.
Select CREATE.

You have now uploaded your Client CA Certificate to GridOS Connect.

View Client CA Certificate

To view the client CA certificate details, navigate to the Connect UI console, select the Certificates from the left navigation menu, and select the certificate using the info icon next to it.

The PEM tab shows the Base64-encoded certificate. The lines -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- indicate the start and end of the certificate data.
Switch to the Details tab to see all certificate parameters.
Click Download to save the certificate.

Create Client CA Certificate

Customers are not expected to create their own client CA certificate. Refer to your organization’s PKI (Public Key Infrastructure) practices for more information on certificate management.

If your organization doesn’t have a client CA certificate (client-ca-cert), create one using the script below:

openssl genrsa -out ca.key 2048
openssl req -new -sha256 -key ca.key -out ca.csr -subj "/CN=ROOTCA"
cat << EOF > ca-ext.cnf
[ca_ext]
basicConstraints = critical,CA:true
keyUsage = critical, keyCertSign, cRLSign
subjectKeyIdentifier = hash
EOF
openssl x509 -req -days 3650 \
  -sha256 \
  -in ca.csr \
  -signkey ca.key \
  -out ca.crt \
  -extfile ca-ext.cnf \
  -extensions ca_ext

The ca.crt file is the client-ca-cert (PEM file). You need to upload this file to the Connect Console.
Store the ca.key file securely. This key is required to sign the client certificate.
Both ca.crt and ca.key are required when generating and signing a client certificate.

Client Certificate

The client-cert must be signed by the customer using the client-ca-cert. Currently, we only support private CA’s and not public CA’s like Let’s Encrypt, GoDaddy, etc. There are many ways to create a client certificate key pair (client-cert and client-private-key).

To generate a client certificate for Agent or Flow Access (mTLS) integration, follow the instructions in their respective sections:

For Agent integration, see Generate Client Certificate for Agents.
For Flow Access integration, see Generate Client Certificate for Flow Access.

Client Certificate for Agents

The Connect Agent uses mTLS for authentication between the Agent and the GridOS Connect main cluster.

The client certificate used by the Agent must meet the following requirements:

The client-cert subject field contains the organization (O field) with the exact same owner/org ID used for your Connect deployment. This same value is used for the required deployer parameters.
The client-cert subject field contains the organizational unit (OU field) with the exact string literal: Connect Deployment.
The client-cert subject field contains the common name (CN field) with the exact string matching the Agent ID you created earlier.
The signed client-cert and client-private-key must be stored in separate files to be used later on.

To generateclient certificate and private key, signed using the CA private key, see the code example:

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/O=<YOUR-GRIDOS-CONNECT-ORG>/OU=Connect Deployment/CN=<YOUR-CONNECT-AGENT-ID>"
cat << EOF > client-ext.cnf
[req]
distinguished_name = req_distinguished_name
[req_distinguished_name]
[client_ext]
keyUsage = critical, digitalSignature
extendedKeyUsage = clientAuth
EOF
openssl x509 -req \
  -in client.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -out client.crt \
  -days 365 \
  -sha256 \
  -extfile client-ext.cnf \
  -extensions client_ext

Save the client.key and client.crt securely. You need to include these parameters in the agent configurations. The client.crt file is the client-cert PEM file.
This client-ext.cnf and client.csr files can be deleted after the client-cert is created.

Be sure to replace the placeholders <YOUR-GRIDOS-CONNECT-ORG> and <YOUR-CONNECT-AGENT-ID> with the proper values. The GridOS connect organization is the same as the owner-id used for the SDK deployer and the Agent ID.

To verify the client-cert, use the command:

openssl verify -CAfile ca.crt client.crt

In summary, in context of the mTLS configuration, the server is the Connect Management API hosted on the GridOS Connect main cluster and the client is the Connect Agent.

The following configurations are required for Connect Agent mTLS configuration:

The server’s public certificate authority (CA) root certificate, referred to as the server-ca-cert. See Connect Cluster CA Certificate for more information.
The public client certificate to be used by the Connect Agent, referred to as the client-cert.
The client private key used by the Connect Agent, corresponding to the public client certificate, referred to as the client-private-key.
The public certificate authority for the issuer of the client-cert, referred to as the client-ca-cert.

The private keys, i.e the files in these examples with the .key suffix, are sensitive information. The private key for the client certificate must only be available to the Connect Agent administrator.

Flow Access using mTLS

Use the credential type, mutual TLS (mTLS) to authenticate and authorize requests.

mTLS is a certificate-based authentication method that secures access to flows in GridOS. Unlike Basic Auth or API keys, mTLS requires both the client and the server to present valid certificates during the TLS handshake.

If your organization wants to send data to your Flow service using mTLS, the client certificate must meet the following requirements:

The client-cert subject field contains the organization (O field) with the exact same owner/org ID used for your Connect deployment. This same value is used for the required deployer parameters.
The client-cert subject field contains the organizational unit (OU field) with the exact string literal: Connect Service Account.
The client-cert subject field contains the common name (CN field) with the exact string matching <serviceAccountId> of the Service Account with the mTLS credential type.

To generate a client certificate that includes the subject attributes mentioned above, see the code example:

openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj "/O=<YOUR-ORG-ID>/OU=<CONNECT-SERVICE-ACCOUNT>/CN=<YOUR-SERVICE-ACCOUNT-ID>"
cat << EOF > client-ext.cnf
[req]
distinguished_name = req_distinguished_name
[req_distinguished_name]
[client_ext]
keyUsage = critical, digitalSignature
extendedKeyUsage = clientAuth
EOF
openssl x509 -req \
  -in client.csr \
  -CA ca.crt \
  -CAkey ca.key \
  -CAcreateserial \
  -out client.crt \
  -days 365 \
  -sha256 \
  -extfile client-ext.cnf \
  -extensions client_ext

Save the client.key and client.crt securely, you need to include this in your client.
This client-ext.cnf and client.csr files can be deleted after the client-cert is created.

The client certificate must be signed by a Certificate Authority (CA). Before a client certificate can be used, the Certificate Authority (CA) that signed it must be registered in your system. Registering a CA allows GridOS Connect to trust any client certificates issued by that CA.

Client Certificate Validation Rules

When the client connects to the flow service:

A request for flow endpoints will be rejected if they do not provide a client certificate that is signed by one of the organization trusted CAs.
If the client certificate is signed by an unknown CA, the request is rejected.
If the client certificate is not authenticated as an existing mTLS Service Account, the request will be rejected.
If the CA is registered but the Organization, Organization Unit, or Service Account ID doesn’t match, the request will be rejected.
If the client certificate is signed by the registered CA and matches the Organization Unit and the Service Account, the request will be accepted.

mTLS service accounts cannot be converted to or from other account types. Make sure you select the correct credential type when creating the service account.

Identity Check & Authentication

Once validated, the flow service extracts the identity from the client certificate. It verifies that the identity points to the correct Service Account.

If it matches, the client is authenticated and sends payloads to the flow. If a request is accepted, it will be forwarded to the flow-server.

Authentication: Performed by validating the client certificate against the CA.
Authorization: Once authenticated, the Connect cluster checks whether the client has the right permission to access the target flow.

Maintain Certificates

Managing your created and uploaded certificates is critical to maintain security.

Renewal

Renew your client certificates in the following cases:

When Client Certificate expires:
When your client certificate expires, use the same ca.crt file from your client CA certificate to create a new client certificate for Agents or client certificate for Flow Access (mTLS).
When Client CA Certificate expires:
When the client CA certificate expires, create a new Client CA certificate and upload it to GridOS Connect before creating any new client certificates.

Was this page helpful?