71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
# Cygnus cloud client
|
|
|
|
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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|