Secure Connection Service Setup

Beta Preview

Secure Connections is a beta preview feature in the April 2026 release. General availability (GA) is scheduled for the May 2026 release, available after May 29th, 2026.

The Secure Connection Service (SCS) is deployed as part of the istari-platform Helm chart and follows the same configuration pattern as the other platform services. This document covers the deployment prerequisites that must be in place before administrators can configure connections in the UI.

The relevant directory in the chart is istari-platform/templates/secure-connection.

Audience: IT administrators and platform operators responsible for installing and upgrading the Istari Platform. For the in-product administrator workflow (creating Sending and Receiving Connections, managing transform rules, etc.), see Secure Connections (Admin Guide).

---

Prerequisites

Zitadel

Using the Istari Zitadel Configurator

The Istari Zitadel Configurator automates the entire manual process described below: creating the SCS role, granting it to the main organization, and setting up the SCS machine user and associated grants.

If you are running the Configurator, you can skip the manual Zitadel sections that follow.

Create the SCS role

1. Open the Istari organization in Zitadel.
2. Go to Projects and select the Istari project.
3. In the left-hand menu, click Roles.
4. Add a new role with the name rss_service_user.

Grant the role to the main organization

1. From the Istari project (steps 1 and 2 above), select Grants.
2. Click the Istari main organization in the list of grants.
3. In the right-hand panel showing the organization and grants, click the edit (pencil) icon.
4. Confirm that the rss_service_user grant created in the previous step is selected, then click Change.

Create the SCS machine user

Create the service user:

1. Open the Istari organization in Zitadel.
2. From the top menu, select Users, then Service Users, and click + New.
3. Enter the machine username and display name.
4. Under Access Token Type, select JWT.
5. Click Create.

Generate and download the key:

6. From the new service user page, click Keys in the left-hand menu.
7. Click + New.
8. Confirm the type is set to JSON.
9. Optionally set an expiration date, or leave it blank for no expiration.
10. Click Add.
11. Click Download to save the key. Store this key securely; it is required later when configuring SCS secrets.

Grant the SCS role to the machine user

1. Open the Istari organization in Zitadel.
2. From the top menu, select Authorizations.
3. Click + New.
4. Under Select users, choose the SCS service user you just created.
5. Under Search for a project, select the Istari project shown as Granted project.
6. Click Continue.
7. Confirm that the rss_service_user role is selected and click Save.

SCS Database

SCS requires a dedicated PostgreSQL database with All privileges on the public schema. This access should be separate from the credentials used by other services.

---

S3 Bucket Management

Each connection requires two storage locations: an Inbox and an Outbox. These are typically two separate buckets, though a single bucket with two distinct prefixes is also supported.

Bucket Naming

Bucket names are flexible but must match the value provided in the corresponding environment variable (see below). Internally, Istari follows the convention:

[environment]-[service]-to-[scs-client-name]-{inbox|outbox}

Examples:

• dev-secure-connection-to-stage-inbox
• dev-secure-connection-to-stage-outbox

Environment Variables

Static Keys and Secrets

Each storage bucket requires the following variables:

Environment Variable	AWS (S3) Value	Azure (Blob Storage) Value	Description
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__ACCESS_KEY	AWS access key	Azure storage admin user	Authentication key/user
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__SECRET_KEY	AWS secret key	Azure storage admin password	Authentication secret
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__ENDPOINT_URL	AWS endpoint URL	Azure storage account domain	Service endpoint
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__NAME	S3 bucket name	Azure blob container name	Storage container name
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__SCHEME	"s3"	"wasbs"	Storage protocol scheme
FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__REGION	Specific S3 region (optional) or empty	Empty	Storage region

Example:

# Inbox object store

FILE_SERVICE_OBJECT_STORES__INBOX__ACCESS_KEY=istaridigital
FILE_SERVICE_OBJECT_STORES__INBOX__ENDPOINT_URL=https://istaridigital.blob.core.windows.net
FILE_SERVICE_OBJECT_STORES__INBOX__NAME=dev-secure-connection-to-aws-inbox
FILE_SERVICE_OBJECT_STORES__INBOX__REGION=""
FILE_SERVICE_OBJECT_STORES__INBOX__SCHEME=wasbs
FILE_SERVICE_OBJECT_STORES__INBOX__SECRET_KEY="secret"

# Outbox object store

FILE_SERVICE_OBJECT_STORES__OUTBOX__ACCESS_KEY=istaridigital
FILE_SERVICE_OBJECT_STORES__OUTBOX__ENDPOINT_URL=https://istaridigital.blob.core.windows.net
FILE_SERVICE_OBJECT_STORES__OUTBOX__NAME=dev-secure-connection-to-aws-outbox
FILE_SERVICE_OBJECT_STORES__OUTBOX__REGION=""
FILE_SERVICE_OBJECT_STORES__OUTBOX__SCHEME=wasbs
FILE_SERVICE_OBJECT_STORES__OUTBOX__SECRET_KEY="secret"

Important: These variables must be shared between the Registry Service (RS) and SCS. The recommended pattern is to define them once in a single Kubernetes secret and mount it on both services using the extraEnvSecrets array.

Pod Identities

When using Pod Identities (or node roles), you can omit the following variables:

• FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__ACCESS_KEY
• FILE_SERVICE_OBJECT_STORES__[VIRTUAL_NAME]__SECRET_KEY

Important: Both the Registry Service and SCS still need to be granted the proper IAM access to the buckets when using Pod Identities.

---

SCS-Specific Environment Variables

The bucket variables above use the FILE_SERVICE_ prefix. SCS itself requires its own variables, prefixed with ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_.

Master Key

Critical: Master Key Immutability

Once the Master Key is created and deployed to both SCS and the Registry Service, it cannot be changed without significant service interruption and potential data loss or corruption. The key is integral to secure communication and data encryption.

It is strongly recommended that the Master Key be created and stored in a dedicated secret vault to ensure proper auditing and access control.

Minimum length: The Master Key must be at least 32 characters long. SCS and the Registry Service will refuse to start with a shorter value.

Cloud Provider	Recommended Vault Solution	Environment Variable Source
AWS	AWS Secrets Manager or AWS KMS	Secrets Manager / KMS integration with Kubernetes (e.g. via the CSI driver)
Azure	Azure Key Vault	Key Vault integration with Kubernetes (e.g. via the Azure Key Vault CSI provider)

The Master Key value must be the same in both services, but the variable name differs:

• In the SCS secret: ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_MASTER_SECRET
• In the Registry Service secret: FILE_SERVICE_REMOTE_MASTER_SECRET

You can mount this secret on both services using extraEnvSecrets rather than duplicating the value across multiple service-specific secrets.

Zitadel Variables

Environment Variable	Description
ISTARI_DIGITAL_REGISTRY_SERVICE_ZITADEL_DOMAIN	Domain of the Zitadel instance used by the Registry Service. Must match FILE_SERVICE_ZITADEL_DOMAIN in the Registry Service secret.
ISTARI_DIGITAL_REGISTRY_SERVICE_ZITADEL_PROJECT_ID	ID of the Zitadel project associated with the Registry Service. Must match FILE_SERVICE_ZITADEL_PROJECT_ID in the Registry Service secret.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_PROJECT_GRANT_ID	ID of the project grant used by SCS. Must match FILE_SERVICE_ZITADEL_PROJECT_GRANT_ID in the Registry Service secret.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_PROJECT_ID	ID of the Zitadel project associated with SCS. Must match FILE_SERVICE_ZITADEL_PROJECT_ID in the Registry Service secret.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_ZITADEL_DOMAIN	Domain of the Zitadel instance used by SCS. Must match FILE_SERVICE_ZITADEL_DOMAIN in the Registry Service secret.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_ZITADEL_JWKS_URL	JWKS URL for Zitadel token validation. Must match FILE_SERVICE_ZITADEL_JWKS_URL in the Registry Service secret.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_ZITADEL_ROLE_NAME	Name of the required Zitadel role for SCS: rss_service_user.
ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_ZITADEL_SECRET	Base64-encoded JSON key content for the SCS machine user (downloaded during the Zitadel setup steps above).

Database

Set the database connection string:

• ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_DATABASE_URL

The value must follow the standard PostgreSQL connection string format:

postgres://[user]:[password]@[postgres-server]:5432/[database]

Other Service Variables

SCS requires the following routing variables:

• ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_HOST=0.0.0.0
• ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_PORT=8000

The log level can optionally be configured:

• ISTARI_DIGITAL_SECURE_CONNECTION_SERVICE_LOG_LEVEL=INFO

---

Deployment

See the istari-platform chart values.yaml for the full list of default values for the secureConnection block.

A minimal deployment override looks like this:

secureConnection:
  # Registry for the remote-share-service image.
  registry: "istaridigital.jfrog.io/main-docker-local"

  # Image and tag are explicitly set, overriding chart defaults.
  # Update these manually when upgrading remote-share-service.
  image: "remote-share-service"
  tag: "10.15.2"

  # Inline environment variables.
  env: []

  # Primary SCS environment secret.
  secretName: secure-connection-service-main-env

  # Additional secrets to mount on the SCS pod.
  extraEnvSecrets:
    - secure-connection-service-zitadel-env
    - secure-connection-service-buckets-env
    - secure-connection-service-master-key

---

Next Steps

Once SCS is deployed and healthy:

• Organization administrators can begin configuring Sending and Receiving Connections in the UI. See Secure Connections (Admin Guide).
• For sync failures, authentication errors, and other operational issues, see Debugging Secure Connections.