Barracuda WAF-as-a-Service Universal Orchestrator Extension
Support
·
Installation
·
License
·
Related Integrations
## Overview
The Barracuda WAF-as-a-Service (WaaS) Orchestrator integrates Keyfactor Command with the Barracuda WaaS REST API (v4) to manage the TLS certificate configured on each WaaS application endpoint. One store type is provided, keyed on the WaaS application name.
### Store Types
| Store Type | WaaS resource | Private Key | Purpose |
|---|---|---|---|
| **BarracudaWaas** | `/applications/{app}/endpoints/` `certificate` block | Required | TLS certificate bound to a WaaS application endpoint |
One managed certificate per WaaS application. The alias of each managed certificate is the **WaaS application name**. (The per-store-type Supported Operations table and store-type creation instructions are auto-generated later in this README from `integration-manifest.json`.)
Reenrollment is unsupported because the v4 API exposes no CSR-generation endpoint. Create-Store is unsupported because WaaS applications are created through the portal, not via the orchestrator.
### Architecture
```mermaid
graph TB
subgraph "Keyfactor Environment"
KF[Keyfactor Command]
UO[Universal Orchestrator
with WaaS Extension]
end
subgraph "Client-Side Crypto"
KEY[Customer Container
RSA Public Key]
AES[Random AES-256 Key
per upload, x2 independent]
end
subgraph "Barracuda WaaS"
API[WaaS v4 REST API
Authorization: Bearer]
APP[Application]
EP[Endpoints Resource
ssl_certificate +
4 encrypted fields]
WAF[Customer WAF Container
holds RSA private key]
end
KF -->|Inventory / Add / Remove| UO
UO -->|wraps AES keys with| KEY
UO -->|encrypts PEM key with| AES
UO -->|"GET /applications/
GET /applications/{app}/endpoints/
PATCH /applications/{app}/endpoints/"| API
API -->|reads / writes| APP
APP --> EP
EP -->|delivers encrypted bundle to| WAF
WAF -->|decrypts using| KEY
style UO fill:#4CAF50,stroke:#2E7D32,color:#fff
style API fill:#2196F3,stroke:#1565C0,color:#fff
style KEY fill:#FF9800,stroke:#E65100,color:#fff
style EP fill:#9C27B0,stroke:#6A1B9A,color:#fff
```
#### Authentication
The orchestrator authenticates to the WaaS v4 API with a **static Bearer token** (`Authorization: Bearer `). Tokens are generated in the Barracuda WaaS portal. The older v2 session-token-with-`auth-api:`-header flow is not supported by this orchestrator.
#### Cryptographic Envelope (Add)
A v4 PATCH to `/applications/{app}/endpoints/` with `use_automatic=false` requires four encrypted fields populated simultaneously:
- `encrypted_ssl_private_key` + `aes_key_encrypted`
- `ssl_private_key_customer_container` + `aes_key_customer_container`
Each pair is:
- A random **AES-256-CBC** (PKCS7-padded) ciphertext of the PEM private key, 16-byte random IV prepended, base64-encoded.
- The random AES key, wrapped under the customer's container RSA public key using **RSA-OAEP with SHA-256**, base64-encoded.
The orchestrator generates two independent AES keys + IVs per Add and wraps both AES keys with the same customer public key. OAEP's randomness makes the two bundles distinct, which is what the server expects. No Barracuda-side key is required client-side; the server validates the structure only.
#### Where each credential lives on the store
| Credential | Store field |
|---|---|
| WaaS v4 API base URL | `Client Machine` (built-in slot) |
| WaaS v4 Bearer API token | `Store Password` (built-in slot, PAM-eligible) |
| Customer container key name | `ContainerKeyName` custom property |
| Customer container public key PEM | `ContainerPublicKeyPem` custom property (PAM-eligible) |
The built-in slots match the standard Keyfactor orchestrator idiom — no custom properties for basic endpoint + token — which keeps the store configuration UI consistent with other orchestrators operators are used to.
#### PAM Support
Both the API token (via Store Password) and the container public key PEM (custom property) are PAM-eligible. Store either in a Keyfactor Command PAM integration and provide the PAM key reference in the corresponding field.
### Deployment modes
The orchestrator supports both WaaS deployment models and auto-selects based on store configuration:
| Mode | Selected when | What the orchestrator sends |
|---|---|---|
| **Shared-cloud** (default) | `ContainerKeyName` and `ContainerPublicKeyPem` are both blank | Plain `ssl_certificate` (PEM chain) + `ssl_private_key` (PEM). Barracuda's control plane encrypts the key server-side before storage. |
| **Isolated mode** (opt-in) | Both container store properties are populated | Full client-side crypto: 2 random AES keys encrypting the PEM key, both wrapped with the customer container public key via RSA-OAEP-SHA256. Barracuda's control plane never sees plaintext. |
Setting only one of the container properties is treated as a configuration error — both or neither.
### Per-Store-Type Add / Remove Behavior
**Add** opens the PKCS#12 with BouncyCastle and extracts the full cert chain (leaf + intermediates + root if present) as concatenated PEM plus the private key as PEM. The envelope differs by mode (see table above). Shipping the chain rather than just the leaf means clients don't need intermediates pre-cached to validate the TLS handshake. If the target endpoint already has a custom cert, `Overwrite=true` on the Management job is required.
**Remove** PATCHes the endpoint back to `use_automatic=true` and nulls all stored cert fields. Works identically for both modes. The endpoint resumes Barracuda's automatic certificate management (Let's Encrypt). There is no "delete cert" concept in v4 - Remove is always a restore-to-ACM.
### Inventory Behavior
The orchestrator walks every application visible to the API token (`GET /applications/`), reads the certificate block from each application's endpoints (`GET /applications/{app}/endpoints/`), and returns one `CurrentInventoryItem` per application that has a stored `ssl_certificate`. Endpoints on `use_automatic=true` with no stored cert are skipped. Entries are marked `PrivateKeyEntry=true` when a custom cert is configured, since the server stores the key material but never returns it on GET.
### Flow Logger
Every job wraps its steps in a `FlowLogger` that emits structured `[FLOW:]` traces at each step, records timing, and appends a final breadcrumb summary to the `JobResult.FailureMessage` on both success and failure. This gives operators a single scannable trail per job-history row - the same pattern used by the Barracuda WAF on-prem orchestrator.
## Compatibility
This integration is compatible with Keyfactor Universal Orchestrator version 10.4 and later.
## Support
The Barracuda WAF-as-a-Service Universal Orchestrator extension is supported by Keyfactor. If you require support for any issues or have feature request, please open a support ticket by either contacting your Keyfactor representative or via the Keyfactor Support Portal at https://support.keyfactor.com.
> If you want to contribute bug fixes or additional enhancements, use the **[Pull requests](../../pulls)** tab.
## Requirements & Prerequisites
Before installing the Barracuda WAF-as-a-Service Universal Orchestrator extension, we recommend that you install [kfutil](https://github.com/Keyfactor/kfutil). Kfutil is a command-line tool that simplifies the process of creating store types, installing extensions, and instantiating certificate stores in Keyfactor Command.
## BarracudaWaas Certificate Store Type
To use the Barracuda WAF-as-a-Service Universal Orchestrator extension, you **must** create the BarracudaWaas Certificate Store Type. This only needs to happen _once_ per Keyfactor Command instance.
##### 🔒 Barracuda WaaS Endpoint Certificate
**Purpose:**
Manages the TLS certificate configured on a Barracuda WAF-as-a-Service (WaaS) application's HTTPS endpoint. The v4 API embeds the certificate inside the endpoint resource (`/applications/{app}/endpoints/` → `certificate` block), so there is exactly one managed cert per WaaS application. The alias of each managed certificate is the **WaaS application name**.
**Usage Context:**
- Rotating the TLS certificate served for a WaaS-protected application
- Replacing Barracuda's automatic (Let's Encrypt) certificate with a cert issued by your own CA
- Inventorying the currently-deployed certificate for each application
**What this store manages:**
One TLS certificate per WaaS application. Alias = WaaS application name (case-sensitive, exact). List applications with `GET /v4/waasapi/applications/`.
#### Barracuda WaaS Endpoint Requirements
#### Reference URLs
| Use | URL |
|---|---|
| Admin portal (browser sign-in — generate API tokens, list apps, manage container keys) | `https://waas.barracudanetworks.com/` |
| REST API base | `https://api.waas.barracudanetworks.com/v4/waasapi` |
| Swagger UI (read-only API browser) | `https://api.waas.barracudanetworks.com/v4/swagger/` |
| SSO / auth backend (transparent — redirected to during portal sign-in) | `auth.barracudanetworks.com` |
#### Deployment mode — shared-cloud vs isolated
The orchestrator auto-selects the upload path at job time based on store configuration:
| Mode | Selected when | Notes |
|---|---|---|
| **Shared-cloud (default)** | `ContainerKeyName` and `ContainerPublicKeyPem` are both blank on the store | Works on any standard WaaS account including free trials. Plain PEM cert + key; Barracuda encrypts server-side. Covers the majority of WaaS customers. |
| **Isolated mode (opt-in)** | Both container properties are populated on the store | Only for tenants running dedicated WAF container pods with a registered Customer Container Encryption Key. The orchestrator client-side-encrypts the private key with AES-256-CBC under RSA-OAEP-SHA256 wrap using the customer's public key before upload. Barracuda's control plane never sees plaintext. |
If only one container property is populated, the job fails fast with an "either both or neither" error. Leave both blank if in doubt — the shared-cloud path is the safer default.
#### Verifying API access
```bash
curl -H "Authorization: Bearer " \
https://api.waas.barracudanetworks.com/v4/waasapi/applications/
```
Successful response is a JSON array of application summaries. `{"errors": "Invalid token"}` means you pasted a v2 session token; generate a v4 static Bearer token in the WaaS portal instead.
#### Container Encryption Key provisioning (isolated mode only)
Skip this section if you're using the default shared-cloud path.
1. Generate an RSA-2048 key pair locally. Keep the private key — Barracuda mounts it into your WAF container pod at provisioning time.
```bash
openssl genpkey -algorithm RSA -out container-priv.pem -pkeyopt rsa_keygen_bits:2048
openssl rsa -in container-priv.pem -pubout -out container-pub.pem
```
2. Register the **public** half with WaaS:
```bash
curl -X POST https://api.waas.barracudanetworks.com/v4/waasapi/containers_keys/ \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d "{\"name\":\"my-container-key\",\"encryption_key\":$(jq -Rs . < container-pub.pem)}"
```
3. On the Keyfactor store, set `ContainerKeyName` to the name from step 2 (e.g. `my-container-key`) and `ContainerPublicKeyPem` to the full PEM contents of `container-pub.pem`. Leave the Store Password field as your API token.
#### Supported Operations
| Operation | Is Supported |
|--------------|------------------------------------------------------------------------------------------------------------------------|
| Add | ✅ Checked |
| Remove | ✅ Checked |
| Discovery | 🔲 Unchecked |
| Reenrollment | 🔲 Unchecked |
| Create | 🔲 Unchecked |
#### Store Type Creation
##### Using kfutil:
`kfutil` is a custom CLI for the Keyfactor Command API and can be used to create certificate store types.
For more information on [kfutil](https://github.com/Keyfactor/kfutil) check out the [docs](https://github.com/Keyfactor/kfutil?tab=readme-ov-file#quickstart)
Click to expand BarracudaWaas kfutil details
##### Using online definition from GitHub:
This will reach out to GitHub and pull the latest store-type definition
```shell
# Barracuda WaaS Endpoint
kfutil store-types create BarracudaWaas
```
##### Offline creation using integration-manifest file:
If required, it is possible to create store types from the [integration-manifest.json](./integration-manifest.json) included in this repo.
You would first download the [integration-manifest.json](./integration-manifest.json) and then run the following command
in your offline environment.
```shell
kfutil store-types create --from-file integration-manifest.json
```
Click to expand manual BarracudaWaas details
Create a store type called `BarracudaWaas` with the attributes in the tables below:
##### Basic Tab
| Attribute | Value | Description |
| --------- | ----- | ----- |
| Name | Barracuda WaaS Endpoint | Display name for the store type (may be customized) |
| Short Name | BarracudaWaas | Short display name for the store type |
| Capability | BarracudaWaas | Store type name orchestrator will register with. Check the box to allow entry of value |
| Supports Add | ✅ Checked | Check the box. Indicates that the Store Type supports Management Add |
| Supports Remove | ✅ Checked | Check the box. Indicates that the Store Type supports Management Remove |
| Supports Discovery | 🔲 Unchecked | Indicates that the Store Type supports Discovery |
| Supports Reenrollment | 🔲 Unchecked | Indicates that the Store Type supports Reenrollment |
| Supports Create | 🔲 Unchecked | Indicates that the Store Type supports store creation |
| Needs Server | 🔲 Unchecked | Determines if a target server name is required when creating store |
| Blueprint Allowed | 🔲 Unchecked | Determines if store type may be included in an Orchestrator blueprint |
| Uses PowerShell | 🔲 Unchecked | Determines if underlying implementation is PowerShell |
| Requires Store Password | ✅ Checked | Enables users to optionally specify a store password when defining a Certificate Store. |
| Supports Entry Password | 🔲 Unchecked | Determines if an individual entry within a store can have a password. |
The Basic tab should look like this:
##### Advanced Tab
| Attribute | Value | Description |
| --------- | ----- | ----- |
| Supports Custom Alias | Required | Determines if an individual entry within a store can have a custom Alias. |
| Private Key Handling | Required | This determines if Keyfactor can send the private key associated with a certificate to the store. Required because IIS certificates without private keys would be invalid. |
| PFX Password Style | Default | 'Default' - PFX password is randomly generated, 'Custom' - PFX password may be specified when the enrollment job is created (Requires the Allow Custom Password application setting to be enabled.) |
The Advanced tab should look like this:
> For Keyfactor **Command versions 24.4 and later**, a Certificate Format dropdown is available with PFX and PEM options. Ensure that **PFX** is selected, as this determines the format of new and renewed certificates sent to the Orchestrator during a Management job. Currently, all Keyfactor-supported Orchestrator extensions support only PFX.
##### Custom Fields Tab
Custom fields operate at the certificate store level and are used to control how the orchestrator connects to the remote target server containing the certificate store to be managed. The following custom fields should be added to the store type:
| Name | Display Name | Description | Type | Default Value/Options | Required |
| ---- | ------------ | ---- | --------------------- | -------- | ----------- |
| ContainerKeyName | Customer Container Key Name (isolated mode only) | OPT-IN. Only populate this for isolated-mode (dedicated container deployment) WaaS tenants. Name of the Customer Container Encryption Key registered via 'POST /containers_keys/'. When this AND Customer Container Public Key are both populated, the orchestrator switches to isolated-mode (client-side-encrypted) upload. When blank, the orchestrator uses the simpler shared-cloud plain-PEM upload, which covers the ~90% of WaaS tenants that run on Barracuda's shared cloud infrastructure. | String | | 🔲 Unchecked |
| ContainerPublicKeyPem | Customer Container Public Key PEM (isolated mode only) | OPT-IN. Only populate this for isolated-mode WaaS tenants. SPKI RSA-2048 public key corresponding to the Customer Container Encryption Key. Must begin with '-----BEGIN PUBLIC KEY-----'. Used client-side to RSA-OAEP-wrap the random AES keys that encrypt the uploaded private key, so Barracuda's control plane never sees plaintext key material. Store in PAM if possible. Leave blank for shared-cloud tenants. | Secret | | 🔲 Unchecked |
| HttpTimeoutSeconds | HTTP Timeout (seconds) | Per-request timeout for calls to the WaaS API. Defaults to 60 seconds. | String | 60 | 🔲 Unchecked |
The Custom Fields tab should look like this:
###### Customer Container Key Name (isolated mode only)
OPT-IN. Only populate this for isolated-mode (dedicated container deployment) WaaS tenants. Name of the Customer Container Encryption Key registered via 'POST /containers_keys/'. When this AND Customer Container Public Key are both populated, the orchestrator switches to isolated-mode (client-side-encrypted) upload. When blank, the orchestrator uses the simpler shared-cloud plain-PEM upload, which covers the ~90% of WaaS tenants that run on Barracuda's shared cloud infrastructure.
###### Customer Container Public Key PEM (isolated mode only)
OPT-IN. Only populate this for isolated-mode WaaS tenants. SPKI RSA-2048 public key corresponding to the Customer Container Encryption Key. Must begin with '-----BEGIN PUBLIC KEY-----'. Used client-side to RSA-OAEP-wrap the random AES keys that encrypt the uploaded private key, so Barracuda's control plane never sees plaintext key material. Store in PAM if possible. Leave blank for shared-cloud tenants.
###### HTTP Timeout (seconds)
Per-request timeout for calls to the WaaS API. Defaults to 60 seconds.
Click to expand details
1. **Navigate to the _Certificate Stores_ page in Keyfactor Command.**
Log into Keyfactor Command, toggle the _Locations_ dropdown, and click _Certificate Stores_.
2. **Add a Certificate Store.**
Click the Add button to add a new Certificate Store. Use the table below to populate the **Attributes** in the **Add** form.
| Attribute | Description |
| --------- |---------------------------------------------------------|
| Category | Select "Barracuda WaaS Endpoint" or the customized certificate store name from the previous step. |
| Container | Optional container to associate certificate store with. |
| Client Machine | Barracuda WaaS v4 API base URL. Defaults to 'https://api.waas.barracudanetworks.com/v4/waasapi' for standard accounts; only change it if Barracuda has assigned your tenant a different endpoint. The orchestrator uses this as the root for every REST call. |
| Store Path | Not used for this integration. Set to '/' or leave at the default value. |
| Store Password | Password to use when reading/writing to store |
| Orchestrator | Select an approved orchestrator capable of managing `BarracudaWaas` certificates. Specifically, one with the `BarracudaWaas` capability. |
| ContainerKeyName | OPT-IN. Only populate this for isolated-mode (dedicated container deployment) WaaS tenants. Name of the Customer Container Encryption Key registered via 'POST /containers_keys/'. When this AND Customer Container Public Key are both populated, the orchestrator switches to isolated-mode (client-side-encrypted) upload. When blank, the orchestrator uses the simpler shared-cloud plain-PEM upload, which covers the ~90% of WaaS tenants that run on Barracuda's shared cloud infrastructure. |
| ContainerPublicKeyPem | OPT-IN. Only populate this for isolated-mode WaaS tenants. SPKI RSA-2048 public key corresponding to the Customer Container Encryption Key. Must begin with '-----BEGIN PUBLIC KEY-----'. Used client-side to RSA-OAEP-wrap the random AES keys that encrypt the uploaded private key, so Barracuda's control plane never sees plaintext key material. Store in PAM if possible. Leave blank for shared-cloud tenants. |
| HttpTimeoutSeconds | Per-request timeout for calls to the WaaS API. Defaults to 60 seconds. |
Click to expand details
1. **Generate a CSV template for the BarracudaWaas certificate store**
```shell
kfutil stores import generate-template --store-type-name BarracudaWaas --outpath BarracudaWaas.csv
```
2. **Populate the generated CSV file**
Open the CSV file, and reference the table below to populate parameters for each **Attribute**.
| Attribute | Description |
| --------- | ----------- |
| Category | Select "Barracuda WaaS Endpoint" or the customized certificate store name from the previous step. |
| Container | Optional container to associate certificate store with. |
| Client Machine | Barracuda WaaS v4 API base URL. Defaults to 'https://api.waas.barracudanetworks.com/v4/waasapi' for standard accounts; only change it if Barracuda has assigned your tenant a different endpoint. The orchestrator uses this as the root for every REST call. |
| Store Path | Not used for this integration. Set to '/' or leave at the default value. |
| Store Password | Password to use when reading/writing to store |
| Orchestrator | Select an approved orchestrator capable of managing `BarracudaWaas` certificates. Specifically, one with the `BarracudaWaas` capability. |
| Properties.ContainerKeyName | OPT-IN. Only populate this for isolated-mode (dedicated container deployment) WaaS tenants. Name of the Customer Container Encryption Key registered via 'POST /containers_keys/'. When this AND Customer Container Public Key are both populated, the orchestrator switches to isolated-mode (client-side-encrypted) upload. When blank, the orchestrator uses the simpler shared-cloud plain-PEM upload, which covers the ~90% of WaaS tenants that run on Barracuda's shared cloud infrastructure. |
| Properties.ContainerPublicKeyPem | OPT-IN. Only populate this for isolated-mode WaaS tenants. SPKI RSA-2048 public key corresponding to the Customer Container Encryption Key. Must begin with '-----BEGIN PUBLIC KEY-----'. Used client-side to RSA-OAEP-wrap the random AES keys that encrypt the uploaded private key, so Barracuda's control plane never sees plaintext key material. Store in PAM if possible. Leave blank for shared-cloud tenants. |
| Properties.HttpTimeoutSeconds | Per-request timeout for calls to the WaaS API. Defaults to 60 seconds. |
3. **Import the CSV file to create the certificate stores**
```shell
kfutil stores import csv --store-type-name BarracudaWaas --file BarracudaWaas.csv
```
Attributes eligible for retrieval by a PAM Provider on the Universal Orchestrator
If a PAM provider was installed _on the Universal Orchestrator_ in the [Installation](#Installation) section, the following parameters can be configured for retrieval _on the Universal Orchestrator_.
| Attribute | Description |
| --------- | ----------- |
| StorePassword | Password to use when reading/writing to store |
| ContainerPublicKeyPem | OPT-IN. Only populate this for isolated-mode WaaS tenants. SPKI RSA-2048 public key corresponding to the Customer Container Encryption Key. Must begin with '-----BEGIN PUBLIC KEY-----'. Used client-side to RSA-OAEP-wrap the random AES keys that encrypt the uploaded private key, so Barracuda's control plane never sees plaintext key material. Store in PAM if possible. Leave blank for shared-cloud tenants. |
Please refer to the **Universal Orchestrator (remote)** usage section ([PAM providers on the Keyfactor Integration Catalog](https://keyfactor.github.io/integrations-catalog/content/pam)) for your selected PAM provider for instructions on how to load attributes orchestrator-side.
> Any secret can be rendered by a PAM provider _installed on the Keyfactor Command server_. The above parameters are specific to attributes that can be fetched by an installed PAM provider running on the Universal Orchestrator server itself.