tenants

Author: rodber

api/4/tenants.md

@@ -12,18 +12,27 @@ The Tenants API **requires** a key which can be generated using the [Tenants CLI
 
 ## Request signing
 
-Requests to the Tenants API **must** be signed by passing the `X-Signature` header containing the request signature.
+All requests to the Tenants API **must** include an `X-Signature` header containing an HMAC SHA256 signature of the request body.
 
 ```plain
-X-Signature: request_signature_here
+X-Signature: your_hmac_sha256_signature
 ```
 
-Signatures must be generated using the raw request body string and the [Tenants Private Key](../../application/configuration/multitenancy.md#tenants-key-pair), with base64 encoding.
+Generate the signature by hashing the raw request body (as a string) with `CHEVERETO_TENANTS_API_SIGNING_SECRET` using HMAC SHA256. The output must be in hexadecimal format.
 
+<code-group>
+<code-block title="PHP">
 ```php
-$signed = $privateKey->sign($body);
-$signature = base64_encode($signed);
+$signature = hash_hmac('sha256', $body, 'your_request_secret');
 ```
+</code-block>
+
+<code-block title="Shell">
+```sh
+echo -n 'body string' | openssl dgst -sha256 -hmac 'your_request_secret' -r | awk '{print $1}'
+```
+</code-block>
+</code-group>
 
 ## `/_/api/4/tenants`
 

application/configuration/configuring.md

@@ -147,8 +147,8 @@ return [
     'CHEVERETO_TENANT' => '',
     'CHEVERETO_TENANT_ENFORCED' => '{}',
     'CHEVERETO_TENANTS_API_ALLOW_LIST' => '',
-    'CHEVERETO_TENANTS_PUBLIC_KEY' => '',
-    'CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET' => '',
+    'CHEVERETO_TENANTS_API_KEY_SECRET' => '',
+    'CHEVERETO_TENANTS_API_REQUEST_SECRET' => '',
     'CHEVERETO_XRDEBUG_HOST' => 'localhost',
     'CHEVERETO_XRDEBUG_HTTPS' => '0',
     'CHEVERETO_XRDEBUG_KEY' => '',

application/configuration/environment.md

@@ -137,16 +137,16 @@ Environment variables for configuring the service provider.
 
 Environment variables for configuring multi-tenancy.
 
-| Variable                                 | Example                         |
-| ---------------------------------------- | ------------------------------- |
-| CHEVERETO_TENANTS_PUBLIC_KEY             | your_tenants_public_key         |
-| CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET | your_tenants_api_signing_secret |
-| CHEVERETO_TENANTS_API_ALLOW_LIST         | 200.200.200.200,10.0.0.0/24     |
-| CHEVERETO_TENANT_ENFORCED                | {"CHEVERETO_MAX_USERS":"100"}   |
-| CHEVERETO_TENANT                         | tenant1                         |
-
-* `CHEVERETO_TENANTS_PUBLIC_KEY` is used to sign requests to the [Tenants API](../../api/4/tenants.md).
-* `CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET` is used to verify requests coming from a known [Tenants API](../../api/4/tenants.md) key.
+| Variable                             | Example                       |
+| ------------------------------------ | ----------------------------- |
+| CHEVERETO_TENANTS_API_REQUEST_SECRET | your_request_secret           |
+| CHEVERETO_TENANTS_API_KEY_SECRET     | your_key_secret               |
+| CHEVERETO_TENANTS_API_ALLOW_LIST     | 200.200.200.200,10.0.0.0/24   |
+| CHEVERETO_TENANT_ENFORCED            | {"CHEVERETO_MAX_USERS":"100"} |
+| CHEVERETO_TENANT                     | tenant1                       |
+
+* `CHEVERETO_TENANTS_API_REQUEST_SECRET` is used to sign requests to the [Tenants API](../../api/4/tenants.md).
+* `CHEVERETO_TENANTS_API_KEY_SECRET` is used to verify requests coming from a known [Tenants API](../../api/4/tenants.md) key.
 * `CHEVERETO_TENANTS_API_ALLOW_LIST` is used to restrict access to the [Tenants API](../../api/4/tenants.md) by IP address or network.
 * `CHEVERETO_TENANT_ENFORCED` is a JSON object that defines which variables will be enforced (overridden) for the multi-tenant context.
 * `CHEVERETO_TENANT` is intended to be used to pass the current tenant context for CLI.

application/configuration/multitenancy.md

@@ -36,21 +36,10 @@ CHEVERETO_ENABLE_TENANTS=1
 CHEVERETO_ENCRYPTION_KEY=your_encryption_key
 CHEVERETO_PROVIDER_NAME=your_provider_name
 CHEVERETO_PROVIDER_URL=your_provider_url
+CHEVERETO_TENANTS_API_REQUEST_SECRET=your_request_secret
 ```
 
-### Tenants key pair
-
-If you need to use the [Tenants API](../../api/4/tenants.md), you will require a key pair. You must set a Tenants public key for verifying signed requests.
-
-```plain
-CHEVERETO_TENANTS_PUBLIC_KEY=your_tenants_public_key
-```
-
-To generate a key pair, you can use `ssh-keygen`:
-
-```sh
-ssh-keygen -t ed25519 -C "your_email@example.com" -f tenants_key
-```
+* `CHEVERETO_TENANTS_API_REQUEST_SECRET` is required to verify signed requests to the [Tenants API](../../api/4/tenants.md).
 
 ### SaaS context
 
@@ -150,11 +139,11 @@ app/bin/tenants -C api:key:delete --name "My Key"
 
 Access to the [Tenants API](../../api/4/tenants.md) can be restricted by IP address or network range using `CHEVERETO_TENANTS_API_ALLOW_LIST`.
 
-All API keys are cryptographically signed with `CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET`. Only keys generated through the [Tenants CLI](../../application/reference/cli.md#create-tenants-api-key) contain valid signatures and will be accepted by the API.
+All API keys are cryptographically signed with `CHEVERETO_TENANTS_API_KEY_SECRET`. Only keys generated through the [Tenants CLI](../../application/reference/cli.md#create-tenants-api-key) contain valid signatures and will be accepted by the API.
 
 ```plain
 CHEVERETO_TENANTS_API_ALLOW_LIST="200.200.200.200,10.0.0.0/24,203.0.113.0/28"
-CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET=your_tenants_api_signing_secret
+CHEVERETO_TENANTS_API_KEY_SECRET=your_tenants_api_signing_secret
 ```
 
 ## Managing tenant plans

introduction/changelog/4.4.md

@@ -22,15 +22,15 @@ This variable allows defining a JSON object with environment variables that will
 
 When running Chevereto in multi-tenant mode, this variable specifies the target tenant for command-line interface (CLI) operations. It should be set to the unique tenant ID of the desired tenant.
 
-`CHEVERETO_TENANTS_PUBLIC_KEY`
+`CHEVERETO_TENANTS_API_REQUEST_SECRET`
 
-This variable is required to verify signed requests to the [Tenants API](../../api/4/tenants.md). It should contain the public key corresponding to the private key used for signing requests.
+This variable is required to verify signed requests to the [Tenants API](../../api/4/tenants.md). It should contain the secret used for signing requests.
 
 `CHEVERETO_TENANTS_API_ALLOW_LIST`
 
 This variable allows restricting access to the [Tenants API](../../api/4/tenants.md) by specifying a comma-separated list of allowed IP addresses or networks. Only requests originating from these sources will be permitted to access the API.
 
-`CHEVERETO_TENANTS_API_KEY_SIGNING_SECRET`
+`CHEVERETO_TENANTS_API_KEY_SECRET`
 
 This variable is used to verify requests coming from a known [Tenants API](../../api/4/tenants.md) key.