docs: add multi-tenancy administration guide

docs/administration/multi-tenancy.md

@@ -0,0 +1,104 @@
+# Multi-tenancy
+
+This page explains how to configure and manage multi-tenancy in OpenAEV, enabling multiple isolated workspaces on a single platform instance.
+
+!!! tip "Enterprise Edition"
+
+    Multi-tenancy is an **OpenAEV Enterprise Edition** feature. A valid EE license is required to create and manage tenants.
+    See [Enterprise Edition](enterprise.md) for activation instructions.
+
+---
+
+## What is multi-tenancy?
+
+Multi-tenancy allows a single OpenAEV instance to host multiple **isolated workspaces**, called tenants. Each tenant has its own data, users, roles, groups, integrations, and infrastructure, completely separated from other tenants on the same platform.
+
+## Why use multi-tenancy?
+
+Multi-tenancy is the recommended deployment model for:
+
+- **MSSPs** managing multiple customers from a single platform
+- **Large organizations** isolating business units or subsidiaries
+
+It reduces operational overhead by centralizing infrastructure while guaranteeing strict data isolation between tenants.
+
+---
+
+## Concepts
+
+### Tenant
+
+A tenant is a fully isolated workspace within the OpenAEV platform. It contains:
+
+- Its own **users, groups, and roles**
+- Its own **scenarios, simulations, and atomic tests**
+- Its own **assets, teams, and players**
+- Its own **integrations** (injectors, collectors, executors)
+
+Data from one tenant is never visible to users of another tenant.
+
+### Platform level vs. Tenant level
+
+OpenAEV distinguishes two levels of administration:
+
+- The **platform level** is where you manage tenants, platform-wide users, roles, and groups. Platform administrators operate at this level to create tenants, assign users across tenants, and configure global settings.
+- The **tenant level** is where day-to-day work happens: scenarios, simulations, assets, findings, integrations. Each tenant has its own users, groups, and roles that are independent from other tenants.
+
+A user or group can exist at both levels. For example, a platform administrator manages tenants globally but must be explicitly added to a tenant group to access that tenant's data.
+
+---
+
+## Managing tenants
+
+Manage tenants from **Settings → Tenants**. You need the `Manage platform settings` capability (platform administrator).
+
+From this page you can create, edit, and delete tenants. When you create a tenant, it is immediately active and all built-in integrations (injectors, collectors) are automatically registered for it.
+
+### Soft-delete and reactivation
+
+Tenant deletion is a **soft-delete** operation. The tenant and all its data are retained for **30 days** before permanent purge. During this period, you can reactivate the tenant from the same page.
+
+!!! danger "Permanent deletion after 30 days"
+
+    After 30 days, the tenant and **all its data** (scenarios, simulations, assets, findings, documents) are permanently purged and cannot be recovered.
+
+---
+
+## Users and access in a multi-tenant setup
+
+### Assigning users to a tenant
+
+You assign a user to a tenant directly from the tenant's user management. Once assigned, the user's permissions within that tenant are determined by the groups and roles they belong to in that tenant context.
+
+A user can belong to **multiple tenants** simultaneously. Permissions are evaluated independently in each tenant context.
+
+---
+
+## SSO and tenant mapping
+
+When using Single Sign-On (OpenID Connect or SAML2), you can automatically assign users to a specific tenant at login using the `tenant_id` parameter.
+
+### Configuration
+
+Add the following property for your SSO provider registration:
+
+| Parameter | Environment variable | Description |
+|---|---|---|
+| `openaev.provider.{registrationId}.tenant_id` | `OPENAEV_PROVIDER_{registrationId}_TENANT_ID` | Tenant ID to assign users to when they log in via this SSO provider |
+
+### Example
+
+Map an Azure AD SAML2 provider to a specific tenant:
+
+```properties
+OPENAEV_PROVIDER_AZURE_TENANT_ID=<your-tenant-uuid>
+```
+
+---
+
+## What's next?
+
+- [Users and RBAC](users-and-rbac.md) — Configure roles and capabilities within a tenant
+- [Enterprise Edition](enterprise.md) — Activate your EE license
+- [Authentication](../deployment/authentication.md) — Set up SSO providers for tenant mapping
+- [Hub](hub.md) — Manage platform-wide resources shared across tenants

docs/deployment/configuration.md

@@ -73,13 +73,15 @@ certificates in the folder are public PEM-armoured (*.pem), DER-encoded X509 cer
 
 #### XTM Suite: OpenCTI
 
-| Parameter                           | Environment variable                | Default value | Description                                                                                                                           |
-|:------------------------------------|:------------------------------------|:--------------|:--------------------------------------------------------------------------------------------------------------------------------------|
-| openaev.xtm.opencti.enable          | OPENAEV_XTM_OPENCTI_ENABLE          | false         | Enable integration with OpenCTI                                                                                                       |
-| openaev.xtm.opencti.url             | OPENAEV_XTM_OPENCTI_URL             |               | OpenCTI URL                                                                                                                           |
-| openaev.xtm.opencti.api_url         | OPENAEV_XTM_OPENCTI_API_URL         |               | OpenCTI API URL, it will completely override the OpenCTI URL, otherwise the default url will be `openaev.xtm.opencti.url` + '/graphql' |
-| openaev.xtm.opencti.token           | OPENAEV_XTM_OPENCTI_TOKEN           |               | OpenCTI token                                                                                                                         |
-| openaev.xtm.opencti.disable-display | OPENAEV_XTM_OPENCTI_DISABLE-DISPLAY | `false`       | Disable OpenCTI in the UI                                                                                                             |
+Each OpenCTI connection is scoped to an OpenAEV tenant, identified by its UUID (`{id}`).
+
+| Parameter                                    | Environment variable                         | Default value | Description                                                                                                                                    |
+|:---------------------------------------------|:---------------------------------------------|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------------|
+| openaev.xtm.opencti.{id}.enable              | OPENAEV_XTM_OPENCTI_{id}_ENABLE              | false         | Enable this OpenCTI connection                                                                                                                 |
+| openaev.xtm.opencti.{id}.url                 | OPENAEV_XTM_OPENCTI_{id}_URL                 |               | OpenCTI instance URL                                                                                                                           |
+| openaev.xtm.opencti.{id}.api_url             | OPENAEV_XTM_OPENCTI_{id}_API_URL             |               | OpenCTI API URL — completely overrides the base URL. Defaults to `openaev.xtm.opencti.{id}.url` + `/graphql`                                   |
+| openaev.xtm.opencti.{id}.token               | OPENAEV_XTM_OPENCTI_{id}_TOKEN               |               | OpenCTI API token                                                                                                                              |
+| openaev.xtm.opencti.{id}.disable-display     | OPENAEV_XTM_OPENCTI_{id}_DISABLE-DISPLAY     | `false`       | Hide this OpenCTI instance in the UI                                                                                                           |
 
 #### XTM Suite: XTM Hub
 

docs/usage/xtm-suite-connector.md

@@ -1,32 +1,92 @@
 # XTM Suite: automated enrichment of Security Coverage
 
-!!! tip "Under construction"
-
-    We are doing our best to complete this page. If you want to participate, don't hesitate to join the [Filigran Community on Slack](https://community.filigran.io) or submit your pull request on the [Github doc repository](https://github.com/OpenAEV-Platform/docs).
+OpenAEV enables other products from the XTM Suite to benefit from a comprehensive Security Coverage enrichment for a given Adversarial Exposure scenario.
+This means that OpenAEV can be triggered via an XTM Suite product to execute a scenario based on a desired threat profile, and results from the scenario execution — such as Detection rate, Prevention rate — are returned to the triggering product for ingestion.
 
+## What is this?
 
-OpenAEV enables other products from the XTM Suite to benefit from a comprehensive Security Coverage enrichment for a given Adversarial Exposure scenario.
-This means that OpenAEV can be triggered via an XTM Suite product to execute a scenario based on a desired scenario, and results from the scenario execution such as Detection rate, Prevention rate... can
-be returned to the triggering product for ingestion.
+The XTM Suite connector allows OpenAEV to communicate bidirectionally with other Filigran products. When enabled, OpenAEV exposes its validation results (detection rate, prevention rate, etc.) to the connected product, providing automated security posture assessments.
 
 This feature is currently available for the following product:
 
-* OpenCTI
+* **OpenCTI** — Threat intelligence platform
+
+## Why use it?
+
+- **Automated feedback loop**: Security Coverage results from OpenAEV simulations are automatically pushed back to OpenCTI, enriching threat intelligence with real validation data.
+- **Continuous posture assessment**: Trigger scenario executions directly from OpenCTI to validate your defenses against specific threats.
+- **Unified visibility**: View detection and prevention rates alongside threat intelligence in a single platform.
 
 ## Automated enrichment for OpenCTI
 
-### Ensuring an up and running OpenCTI instance
-This feature requires an active OpenCTI instance. Refer to the [OpenCTI documentation](https://docs.opencti.io/latest/) for enabling this instance.
+### Prerequisites
+
+This feature requires:
+
+1. An active **OpenCTI instance** (v6.x or later recommended). Refer to the [OpenCTI documentation](https://docs.opencti.io/latest/) for deployment instructions.
+2. The **OpenAEV platform** configured and running with at least one scenario ready to execute.
+
+Once the OpenCTI instance is up and running, gather the following information:
+
+| Item | Description |
+|:-----|:------------|
+| OpenCTI URL | The instance's full domain name (e.g., `https://opencti.domain.example`) |
+| API Token | A valid API token with sufficient privileges (see [Configuring the Connector API token](https://docs.opencti.io/latest/deployment/connectors/#connector-token)) |
+
+### How to enable the connector
+
+#### Step 1: Configure OpenAEV to connect to OpenCTI
+
+Each OpenCTI connection is scoped to an OpenAEV **tenant**, identified by its UUID (`{id}`). This allows each tenant in a [multi-tenant deployment](../../administration/multi-tenancy.md) to have its own OpenCTI integration.
+
+Set the following parameters in your OpenAEV deployment:
+
+```properties
+openaev.xtm.opencti.{id}.enable=true
+openaev.xtm.opencti.{id}.url=https://opencti.domain.example
+openaev.xtm.opencti.{id}.token=<your-opencti-api-token>
+```
 
-Once the OpenCTI instance is up and running, make sure to obtain these two settings:
+Or as environment variables:
 
-* The instance's full domain name (i.e. _https://opencti.domain.example_)
-* A valid API Token associated with an account with sufficient privileges (refer to: [Configuring the Connector API token](https://docs.opencti.io/latest/deployment/connectors/#connector-token))
+```properties
+OPENAEV_XTM_OPENCTI_{id}_ENABLE=true
+OPENAEV_XTM_OPENCTI_{id}_URL=https://opencti.domain.example
+OPENAEV_XTM_OPENCTI_{id}_TOKEN=<your-opencti-api-token>
+```
 
-### Enabling the Security Coverage connector in OpenAEV
-Make sure you set a value for all mandatory configuration keys, following the [Configuration documentation for the Security Coverage Connector](../deployment/configuration.md#xtm-suite-opencti).
+!!! tip "What is `{id}`?"
+
+    The `{id}` is the **OpenAEV tenant UUID** (e.g., `2cffad3a-0001-4078-b0e2-ef74274022c3`). You can find it in the platform administration under tenant settings.
+
+!!! tip "API URL override"
+
+    You only need to set `api_url` if your GraphQL endpoint differs from the default `<url>/graphql` (e.g., behind a reverse proxy with a custom path).
+
+#### Step 2: Restart OpenAEV
+
+After updating the configuration, restart the OpenAEV platform for the changes to take effect.
+
+#### Step 3: Verify the connector in OpenCTI
+
+The connector is now up and running and should be visible in OpenCTI as **OpenAEV Coverage**.
 
-### Use OpenCTI to trigger security coverage enrichments seamlessly
-The connector is now up and running and should be visible in OpenCTI as _OpenAEV Coverage_.
 ![Active OpenAEV Coverage connector in OpenCTI](assets/active_openaev_connector_in_opencti.png)
-Refer to the [OpenCTI documentation](https://docs.opencti.io/latest/) for how to trigger the enabled connector to get automated enriched security posture assessments with OpenAEV.
+
+### Trigger security coverage enrichments from OpenCTI
+
+Once the connector appears in OpenCTI, you can trigger it to run security coverage enrichments. Refer to the [OpenCTI documentation](https://docs.opencti.io/latest/) for how to trigger the enabled connector to get automated enriched security posture assessments with OpenAEV.
+
+## Example workflow
+
+1. A threat analyst identifies a new intrusion set in **OpenCTI**.
+2. The analyst triggers the **OpenAEV Coverage** connector on the associated Security Coverage object.
+3. OpenAEV receives the request, maps it to an existing scenario, and executes the simulation.
+4. Results (detection rate, prevention rate, findings) are pushed back to OpenCTI as enrichment data.
+5. The analyst sees the updated security posture directly in the OpenCTI interface.
+
+## What's next?
+
+- [Scenario Generation from OpenCTI Security Coverage](scenario/security-coverage.md) — Automatically create OpenAEV scenarios from OpenCTI Security Coverage objects.
+- [Configuration reference](../deployment/configuration.md#xtm-suite-opencti) — Full list of configuration parameters.
+- [Scenarios and Simulations](scenarios-and-simulations.md) — Understand how scenarios and simulations work in OpenAEV.

mkdocs.yml

@@ -200,6 +200,7 @@ nav:
   - Administration:
     - Introduction: administration/introduction.md
     - Enterprise edition: administration/enterprise.md
+    - Multi-tenancy: administration/multi-tenancy.md
     - Platform settings:
       - Parameters: administration/parameters.md
       - Security: