This module is the reusable on-premises gateway client for Cygnus cloud APIs. It obtains a short-lived machine access token, encrypts login credentials with the cloud login public key, and calls the cloud identity API over WebFlux.

On-premises identity configuration

Cloud login is required by the on-premises application. Configure these as environment variables or JVM system properties:

Setting	Purpose
`CYGNUS_CLOUD_BASE_URL`	Cloud gateway/API base URL
`CYGNUS_TOKEN_URL`	OAuth 2.0 machine-token endpoint
`CYGNUS_CLIENT_ID`	Provisioned customer/client identifier
`CYGNUS_INSTALLATION_ID`	Unique on-premises installation identifier
`CYGNUS_CLIENT_ASSERTION`	Provisioned encrypted assertion or `file:/secure/path/assertion.jwt`
`CYGNUS_LOGIN_KEY_ID`	Cloud login encryption-key identifier
`CYGNUS_LOGIN_PUBLIC_KEY`	X.509 RSA public key location
`CYGNUS_CLOUD_REQUEST_TIMEOUT`	Request timeout, for example `PT10S`
Do not store private keys, client assertions, passwords, or production URLs in
source control.

Provision a machine assertion

The assertion is a signed JWT nested inside an RSA-OAEP-256/AES-256-GCM JWE. It is valid for one year; the access token obtained with it is short-lived.

For local development, the repository setup script automates prerequisite checks, the full Maven verification, directory creation, all three cloud key pairs, the installation key pair, config/clients.yml, and the encrypted machine assertion:

./scripts/setup-local-communication.sh

The script interactively asks for the customer identifier, installation identifier, cloud URL, and whether to run the full verification. Customer and installation identifiers cannot contain spaces; the customer identifier is used for its directory and signing-key filenames. New customers are appended to config/clients.yml without replacing existing customers.

It preserves existing private keys and assertions. Set CYGNUS_SETUP_FORCE_ASSERTION=true only when the assertion needs to be regenerated. The manual provisioning commands follow.

Generate the installation signing key:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -out client-signing-private.pem
openssl pkey -in client-signing-private.pem -pubout \
  -out client-signing-public.pem

Generate the assertion after the cloud assertion-encryption public key has been securely delivered:

mvn -pl cygnus-cloud-client exec:java \
  -Dexec.mainClass=com.cygnus.client.provisioning.MachineAssertionGenerator \
  -Dexec.args="customer-a site-01 https://cloud.example.com/oauth2/token \
client-signing-private.pem cloud-assertion-public.pem machine-assertion.jwt"

Copy only client-signing-public.pem into that customer's cloud-side client configuration. Keep the private key and generated assertion on the on-premises server with owner-only filesystem permissions.