From 6eb6832bc41ac9449ef18d6fc55da92a16faff13 Mon Sep 17 00:00:00 2001 From: itsvishwa Date: Thu, 25 Jun 2026 11:41:50 +0530 Subject: [PATCH 1/3] Revamp ICP documentation across core different areas --- en/docs/manage/icp/access-control.md | 1 + en/docs/manage/icp/encrypt-secrets.md | 123 ++++++++++++------ en/docs/manage/icp/manage-environments.md | 4 +- en/docs/manage/icp/manage-integrations.md | 24 ++-- en/docs/manage/icp/manage-projects.md | 2 +- en/docs/manage/icp/manage-runtimes.md | 6 +- en/docs/manage/icp/reverse-proxy.md | 2 +- .../icp/user-stores/default-user-store.md | 32 +++-- .../manage/icp/user-stores/ldap-user-store.md | 21 +-- 9 files changed, 131 insertions(+), 84 deletions(-) diff --git a/en/docs/manage/icp/access-control.md b/en/docs/manage/icp/access-control.md index 403c518a7bd..a1eea9347fd 100644 --- a/en/docs/manage/icp/access-control.md +++ b/en/docs/manage/icp/access-control.md @@ -141,6 +141,7 @@ Go to the organization **Access control** and open the **Users** tab. Each user | **Reset password** | Opens a dialog to set a new password | | **Unlock account** | Re-enables a locked account | | **Revoke sessions** | Terminates all active sessions (disabled for your own account) | +| **Delete user** | Permanently removes the user | ## Reference diff --git a/en/docs/manage/icp/encrypt-secrets.md b/en/docs/manage/icp/encrypt-secrets.md index 93258776f09..837eb7f8271 100644 --- a/en/docs/manage/icp/encrypt-secrets.md +++ b/en/docs/manage/icp/encrypt-secrets.md @@ -6,7 +6,7 @@ keywords: [wso2 integrator, icp, cipher tool, encrypt, secrets, manage] # Encrypt Secrets with the Cipher Tool -The Integration Control Plane (ICP) ships with a cipher tool that lets you encrypt sensitive configuration values — such as passwords, JWT signing secrets, and SSO client secrets — before storing them in `deployment.toml`. At startup, ICP decrypts these values automatically using the private key in its keystore. +The Integration Control Plane (ICP) ships with a cipher tool that lets you encrypt sensitive configuration values (such as passwords, JWT signing secrets, and SSO client secrets) before storing them in `deployment.toml`. At startup, ICP decrypts these values automatically using the private key in its keystore. ## Prerequisites @@ -15,7 +15,7 @@ The Integration Control Plane (ICP) ships with a cipher tool that lets you encry ## Encryptable configuration fields -Only the following fields in `deployment.toml` support encryption. Attempting to use `$secret{alias}` for any other field will have no effect. +Only the following configuration keys in `deployment.toml` support encryption (use of any other key has no effect). You will replace each plaintext value with a `$secret{alias}` reference in a later step. **Fields stored under `[icp_server.secrets]`:** @@ -43,9 +43,55 @@ Only the following fields in `deployment.toml` support encryption. Attempting to | `dbUser` | Primary database username | | `dbPassword` | Primary database password | -## Encrypt a secret +## Step 1: Generate a keystore -Run the cipher tool from the ICP installation directory without any flags for the interactive mode. +Generate a new PKCS12 keystore using the Java `keytool` command: + +:::note +The keystore generated by this command uses a **self-signed certificate**. For a keystore used solely for local secret encryption and decryption, this is functionally sufficient in production. However, if your organization's security policy or compliance requirements mandate CA-issued certificates, use a CA-backed keystore instead. If you already have a suitable keystore, skip this step. +::: + +```bash +keytool -genkeypair -alias -keyalg RSA -keysize 2048 -validity 3650 -storetype PKCS12 -keystore .p12 -storepass -keypass -dname "CN=localhost, OU=Security, O=MyOrg, L=City, ST=State, C=US" +``` + +Replace the placeholders before running the command: + +| Placeholder | Description | +|-------------|-------------| +| `` | Name to identify the key inside the keystore | +| `` | Output filename for the `.p12` file | +| `` | Password to open/access the keystore | +| `` | Password for the private key itself | + +:::warning +Replace all placeholders with your own values before running the command. +::: + +## Step 2: Configure the cipher tool + +The cipher tool and ICP support multiple keystore types. PKCS12 (`.p12`) is the recommended format, but JKS and other standard Java keystore types are also supported. Adjust the type values in the steps below to match your keystore format. + +1. Copy your keystore file into the `conf/security/` directory of your ICP installation. +2. Open `conf/cipher-standalone-config.properties` and update the following properties to point to your keystore: + +```properties +primary.key.location=conf/security/ +primary.key.type= +primary.key.alias= +``` + +| Property | Description | +|---|---| +| `primary.key.location` | Path to the keystore file relative to the ICP installation directory | +| `primary.key.type` | Keystore format: `PKCS12` for `.p12` files, `JKS` for Java Keystore files | +| `primary.key.alias` | Alias used to identify the key entry inside the keystore | + +These settings tell the cipher tool which keystore to use when encrypting values. + +## Step 3: Encrypt a secret + +Run the cipher tool from the ICP installation directory: **Linux/macOS:** ```bash @@ -61,7 +107,7 @@ The tool loads the keystore, prompts for the keystore password and the plaintext ```bash Encrypting using Primary KeyStore. -{type: PKCS12, alias: localhost, path: conf/security/keystore.p12} +{type: , alias: , path: conf/security/} [Please Enter Primary KeyStore Password of Carbon Server : ] @@ -76,9 +122,9 @@ Encrypted value is : ... ``` -Copy the encrypted value — you will need it in the next step. Repeat this for every secret you want to encrypt. +Copy the encrypted value, as you will need it in the next step. Repeat this for every secret you want to encrypt. -## Update deployment.toml +## Step 4: Update deployment.toml with ciphertext references For each secret you encrypted, make two changes to `conf/deployment.toml`: @@ -87,19 +133,16 @@ For each secret you encrypted, make two changes to `conf/deployment.toml`: The alias can be any descriptive name, but using the configuration key name as the alias is the clearest convention. -**Fields from the [Encryptable configuration fields](#encryptable-configuration-fields) table above go into their respective secrets tables:** - ```toml # Ciphertext references for server configurables -# References scattered throughout the main configuration -keystorePassword = "$secret{keystorePassword}" -ssoClientSecret = "$secret{ssoClientSecret}" +keystorePassword = "$secret{keystorePassword}" +ssoClientSecret = "$secret{ssoClientSecret}" ldapConnectionPassword = "$secret{ldapConnectionPassword}" # Ciphertexts for server configurables [icp_server.secrets] -keystorePassword = "RIbyQ0Te..." -ssoClientSecret = "duNHb..." +keystorePassword = "RIbyQ0Te..." +ssoClientSecret = "duNHb..." ldapConnectionPassword = "P8/7g6rkGB..." # Ciphertext references for database configurables @@ -114,43 +157,39 @@ dbPassword = "ZH84B2a1..." ``` :::note -Every value in a secrets table must be a ciphertext produced by the cipher tool. ICP will fail if a plaintext value is found there. +Every value in a secrets table must be a ciphertext produced by the cipher tool. ICP will fail to start if a plaintext value is found there. ::: -## How ICP decrypts secrets at startup - -For each configuration field that contains a `$secret{alias}` reference, ICP retrieves the corresponding ciphertext from the secrets table, decrypts it using the private key in the cipher keystore, and uses the resulting plaintext value for the rest of the server lifetime. Decryption happens once during server startup. - -## Cipher keystore configuration +## Step 5: Point ICP to your keystore -By default, the cipher tool and ICP use the same keystore: - -| Setting | Default | -|---|---| -| Keystore path | `conf/security/keystore.p12` | -| Keystore alias | `` | -| Keystore password | `` | -| Private key password | `` | - -All four settings can be overridden in `deployment.toml` under `[icp_server.utils]`. The keystore passwords can additionally be set via environment variables, which take precedence over the `deployment.toml` values. - -**Option 1 — deployment.toml:** +Add the following block to `conf/deployment.toml` so that ICP uses your keystore to decrypt secrets at startup: ```toml [icp_server.utils] -cipherKeystorePath = "conf/security/my-keystore.p12" -cipherKeystoreAlias = "my-alias" -cipherKeystorePassword = "my-keystore-password" -cipherPrivateKeyPassword = "my-private-key-password" +cipherKeystorePath = "" +cipherKeystoreAlias = "" +cipherKeystorePassword = "" +cipherPrivateKeyPassword = "" ``` -**Option 2 — environment variables (passwords only):** +| Property | Description | +|---|---| +| `cipherKeystorePath` | Full path to the keystore file | +| `cipherKeystoreAlias` | Alias of the key entry inside the keystore | +| `cipherKeystorePassword` | Password to open the keystore | +| `cipherPrivateKeyPassword` | Password for the private key entry | + +:::note +These values must match exactly what you used when generating or obtaining the keystore and what you configured in `cipher-standalone-config.properties` in Step 2. If they differ, ICP will fail to decrypt the secrets at startup. +::: + +Alternatively, the keystore passwords can be provided as environment variables, which take precedence over the `deployment.toml` values: ```bash -export ICP_CIPHER_KEYSTORE_PASSWORD="" -export ICP_PRIVATE_KEY_PASSWORD="" +export ICP_CIPHER_KEYSTORE_PASSWORD="" +export ICP_PRIVATE_KEY_PASSWORD="" ``` -:::note -These settings must match the keystore that was used when encrypting the values with the cipher tool. If they differ, ICP will fail to decrypt the secrets at startup. -::: +## How ICP decrypts secrets at startup + +For each configuration field that contains a `$secret{alias}` reference, ICP retrieves the corresponding ciphertext from the secrets table, decrypts it using the private key in the cipher keystore, and uses the resulting plaintext value for the rest of the server lifetime. Decryption happens once during server startup. diff --git a/en/docs/manage/icp/manage-environments.md b/en/docs/manage/icp/manage-environments.md index f7b54b307f0..2025d04ac73 100644 --- a/en/docs/manage/icp/manage-environments.md +++ b/en/docs/manage/icp/manage-environments.md @@ -30,11 +30,11 @@ The environments page shows a table with the following columns: | **Created** | Relative timestamp (e.g. *31 days ago*) | | **Actions** | **Edit** (pencil) and **Delete** (trash) icons | -Use the search bar to filter environments by name. Pagination controls appear at the bottom when the list exceeds one page. +Use the search bar to filter environments across all columns. Pagination controls are visible at the bottom of the table. ## Create an environment -1. On the environments page, click **+ Create**. +1. On the environments page, click **+ Create Environment**. 2. Fill in the **Create Environment** form: | Field | Required | Description | diff --git a/en/docs/manage/icp/manage-integrations.md b/en/docs/manage/icp/manage-integrations.md index 44fa6cd2ca7..0288cd72042 100644 --- a/en/docs/manage/icp/manage-integrations.md +++ b/en/docs/manage/icp/manage-integrations.md @@ -15,8 +15,6 @@ An integration in ICP represents a deployable Ballerina or MI application that r | Field | Required | Description | |-------|----------|-------------| - | **Organization** | Auto | Pre-filled with the current organization. Read-only when navigating from a project. | - | **Project** | Auto | Pre-filled with the current project. Change via the dropdown if needed. | | **Display Name** | Yes | Human-readable name shown in the console (e.g. `Order Create`) | | **Name** | Auto | URL-safe slug derived from the display name. Click the edit icon to override. | | **Integration Type** | Yes | **Default profile** (Ballerina) or **MI** (Micro Integrator). Defaults to default profile. | @@ -30,13 +28,13 @@ The integration appears in the project's integrations table on success. The integration overview shows one environment card per environment. Each card displays: -- Environment name and runtime count badge (e.g. *0 runtimes* or *1/1 Online*). +- Environment name and runtime count badge (e.g. *0/1 Offline* or *1/1 Online*). - A refresh icon to reload runtime status. - **Entry Points** tab listing the services exposed by the integration. - **Supporting Artifacts** tab showing additional artifacts when present. - **+ Add Runtime** link when no runtimes are registered yet. -When no runtimes are connected, the card shows: *"No runtimes registered for this environment."* +When no runtimes are connected, the card shows: *"No entry points found for this integration. Add runtime to get started."* ### Integration sidebar @@ -74,10 +72,10 @@ The **Logs** page shows runtime log entries when both a connected runtime and Op When operational, the page provides: -- Environment filter -- Log level filter (INFO, WARN, ERROR, DEBUG) -- Time range selector -- Log entries with timestamps, levels, and messages +- **Filtering**: Environment, log level (INFO, WARN, ERROR, DEBUG), time range, and a keyword search bar +- **Display controls**: Sort order (Newest first / Oldest first), auto-fetch toggle for automatic reload, and an entry count showing how many entries are loaded +- **Actions**: Refresh button for manual reload and a download button to export log entries +- **Log entries**: Each entry shows a timestamp, level, and message ### Loggers @@ -113,10 +111,10 @@ The **Metrics** page shows request performance data when both a connected runtim When operational, the page provides: -- Summary cards: Total Requests, Error Count, Error Percentage, and P95 Latency -- Requests Per Minute chart -- Request Latency chart (average, P50, P95, P99) -- Most Used APIs table with per-endpoint request counts and average response times +- **Summary cards**: Total Requests, Error Count, Error Percentage, and P95 Latency +- **Overview charts**: Requests Per Minute and Request Latency (average, P50, P95, P99) +- **Most Used APIs**: Table with per-endpoint request counts and average response times +- **Statistics of APIs**: Section with an API filter dropdown, showing Requests Per Minute, Average Request Latency, Successful Requests by API, and Failed Requests by API charts ### Listeners @@ -129,7 +127,7 @@ Ballerina listeners (HTTP, TCP, and other transport listeners) appear in the **E 1. Open the integration and go to **Overview**. 2. In the environment card, click the **Entry Points** tab. 3. Click the listener you want to control. The listener detail panel opens on the right. -4. Use the toggle in the panel to start or stop the listener. +4. Use the toggle (State) in the panel to start or stop the listener. 5. A confirmation dialog appears. Click **Enable** or **Disable** to confirm. ICP sends a `START` or `STOP` command to every runtime associated with the listener. The listener state updates to **RUNNING** or **STOPPED** once the runtimes acknowledge the command. diff --git a/en/docs/manage/icp/manage-projects.md b/en/docs/manage/icp/manage-projects.md index 6a9ba29627a..88a3dbbaa01 100644 --- a/en/docs/manage/icp/manage-projects.md +++ b/en/docs/manage/icp/manage-projects.md @@ -62,7 +62,7 @@ Clicking a project card opens the project home. It shows all integrations belong The page includes: - Project avatar, display name, and description at the top. -- An **Integrations** table with **Name**, **Description**, **Type**, and **Last Updated** columns. +- An **Integrations** table with **Name**, **Description**, **Type**, **Last Updated** and **Actions** columns. - A **+ Create Integration** button to add a new integration to the project. - An **Integration Types** summary card on the right showing the count by type (Default, MI, and Total). diff --git a/en/docs/manage/icp/manage-runtimes.md b/en/docs/manage/icp/manage-runtimes.md index 2119034b803..fcd29805507 100644 --- a/en/docs/manage/icp/manage-runtimes.md +++ b/en/docs/manage/icp/manage-runtimes.md @@ -27,7 +27,7 @@ Runtimes are grouped by environment. Each environment section shows: | **Type** | Profile type: default profile or MI | | **Component** | Integration name this runtime belongs to | | **Status** | Current state: **RUNNING**, OFFLINE, or similar | -| **Version** | Runtime version, or "Not reported" if unavailable | +| **Version** | Runtime version, or "-" if unavailable | | **Platform** | Ballerina runtime version (e.g. `Ballerina 2201.13.2`) | | **OS** | Operating system of the host machine | | **Registration time** | Timestamp of first connection to ICP | @@ -43,8 +43,8 @@ Click **+ Add Runtime** on an environment section to generate a secret and get a ## Manage secrets 1. Navigate to the **Runtimes** section at the integration level, then click **Manage Secrets** on any environment section. -2. The secrets panel opens showing unbound secrets for that environment. Unbound secrets are those not yet claimed by any runtime. -3. If all secrets are already in use, the panel shows: *"No unbound secrets for this environment."* +2. The secrets panel opens showing all secrets for that environment - both bound (claimed by a runtime) and unbound (not yet claimed by any runtime). +3. If there are no secrets, the panel shows: *"No bound secrets for this integration in this environment."* 4. Click the delete icon next to a secret to revoke it. ## Scope differences diff --git a/en/docs/manage/icp/reverse-proxy.md b/en/docs/manage/icp/reverse-proxy.md index 56b00f8b301..69180016534 100644 --- a/en/docs/manage/icp/reverse-proxy.md +++ b/en/docs/manage/icp/reverse-proxy.md @@ -18,7 +18,7 @@ backendAuthBaseUrl = "https://icp.example.com/auth" backendObservabilityEndpoint = "https://icp.example.com/icp/observability" ``` -These values default to `https://localhost:9446`. ICP automatically propagates them to the console frontend on startup, so `www/config.json` does not need to be edited manually. Restart ICP after saving the file. +If not set, these values default to `https://localhost:9446`. When ICP starts, it reads these settings from `conf/deployment.toml` and propagates them into the console frontend automatically (you do not need to edit `www/config.json` directly). Restart ICP for the changes to take effect. ## Update runtime connections diff --git a/en/docs/manage/icp/user-stores/default-user-store.md b/en/docs/manage/icp/user-stores/default-user-store.md index b139b3dfa52..59c4ec12fda 100644 --- a/en/docs/manage/icp/user-stores/default-user-store.md +++ b/en/docs/manage/icp/user-stores/default-user-store.md @@ -5,12 +5,10 @@ description: Configure the ICP built-in credentials database — connect an exte # Built-in User Store -The built-in user store keeps user credentials — password hashes, salts, and per-user attributes such as failed-login counters — in a dedicated **credentials database**, separate from the main ICP database that holds projects, environments, and integration metadata. +The built-in user store keeps user credentials (password hashes, salts, and per-user attributes such as failed-login counters) in a dedicated **credentials database**, separate from the main ICP database that holds projects, environments, and integration metadata. By default both databases use the embedded H2 engine, writing to `/bin/database/`. For production, switch the credentials database to PostgreSQL, MySQL, or MSSQL. ---- - ## Default Setup (H2) No configuration is needed. ICP creates the H2 credentials database automatically on first start, initializes the schema, and seeds an `admin` user with password `admin`. @@ -27,13 +25,24 @@ The default `admin` / `admin` credentials are publicly known. Change the passwor ## Connecting an External Database -### Step 1 — Create the database and user +### Step 1: Create the database and user Create a dedicated database and user on the database server. The user needs `CREATE`, `INSERT`, `UPDATE`, `DELETE`, and `SELECT` privileges on the credentials database. -### Step 2 — Initialize the schema +**PostgreSQL example:** + +```sql +CREATE DATABASE credentials_db; +CREATE USER WITH PASSWORD ''; +GRANT CONNECT ON DATABASE credentials_db TO ; +\c credentials_db +GRANT USAGE, CREATE ON SCHEMA public TO ; +ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ; +``` + +### Step 2: Initialize the schema -Run the appropriate init script to create the `user_credentials` and `user_attributes` tables and seed the default `admin` user. The scripts are included in the ICP distribution: +Run the appropriate init script to create the `user_credentials` and `user_attributes` tables and seed the default `admin` user. The scripts are located in the ICP installation directory: | Database | Init script | | ---------- | -------------------------------------------- | @@ -44,8 +53,7 @@ Run the appropriate init script to create the `user_credentials` and `user_attri Example for PostgreSQL: ```bash -psql -h -U -d \ - -f db-scripts/credentials_postgresql_init.sql +psql -h -U -d credentials_db -f db-scripts/credentials_postgresql_init.sql ``` The init script seeds the `admin` user with a bcrypt hash of the default password `admin`. @@ -54,17 +62,17 @@ The init script seeds the `admin` user with a bcrypt hash of the default passwor The default `admin` / `admin` credentials are publicly known. Change the password immediately after first login via **Profile** > **Change Password**. ::: -### Step 3 — Configure deployment.toml +### Step 3: Configure deployment.toml Add the `credentialsDb*` keys as **top-level entries** in `/conf/deployment.toml`, before any `[section]` header: ```toml credentialsDbType = "postgresql" -credentialsDbHost = "db.example.com" +credentialsDbHost = "" credentialsDbPort = 5432 credentialsDbName = "credentials_db" -credentialsDbUser = "icp_user" -credentialsDbPassword = "changeme" +credentialsDbUser = "" +credentialsDbPassword = "" ``` :::note diff --git a/en/docs/manage/icp/user-stores/ldap-user-store.md b/en/docs/manage/icp/user-stores/ldap-user-store.md index 25501d08a97..cbec623e5f9 100644 --- a/en/docs/manage/icp/user-stores/ldap-user-store.md +++ b/en/docs/manage/icp/user-stores/ldap-user-store.md @@ -17,13 +17,13 @@ ICP can authenticate users against an external LDAP directory instead of the bui All LDAP settings are top-level keys in `conf/deployment.toml`. Only `ldapUserStoreEnabled = true` is strictly required to activate the adapter; all other keys have defaults. -### Activate the adapter +### Step 1: Activate the adapter ```toml ldapUserStoreEnabled = true ``` -### Server connection +### Step 2: Configure the server connection ```toml ldapHostName = "ldap.example.com" # default: localhost @@ -35,14 +35,14 @@ ldapConnectionName = "uid=admin,ou=system" ldapConnectionPassword = "secret" ``` -### User search +### Step 3: Configure user search | Key | Default | Description | | --- | ------- | ----------- | | `ldapUserSearchBase` | `ou=Users,dc=wso2,dc=org` | Base DN for user searches | | `ldapUserNameAttribute` | `uid` | Attribute that holds the login username | | `ldapUserSearchFilter` | `(&(objectClass=person)(uid=?))` | Filter to locate a user; `?` is replaced with the username | -| `ldapUserDNPattern` | _(empty)_ | Optional shortcut — construct the DN directly without a search (see below) | +| `ldapUserDNPattern` | _(empty)_ | Optional shortcut to construct the DN directly without a search (see below) | | `ldapDisplayNameAttribute` | _(empty)_ | Attribute used as the display name in ICP; leave empty to use the username | **`ldapUserDNPattern`** avoids a search round-trip by constructing the DN from the username directly. Use `{0}` as the placeholder: @@ -53,11 +53,11 @@ ldapUserDNPattern = "uid={0},ou=Users,dc=wso2,dc=org" If the pattern is set, `ldapUserSearchFilter` and the admin bind are not used for authentication (though they are still used for group lookup if `ldapMemberOfAttribute` is not set). -### Group / role lookup +### Step 4: Configure group and role lookup -ICP reads groups to determine whether a user should be granted super-admin. Two strategies are supported. +ICP reads groups solely to determine whether a user should be granted super-admin access. All other access control is managed through ICP's own user management. Two strategies are supported. -#### Strategy A — `memberOf` (Active Directory and some standard LDAP servers) +#### Strategy A: `memberOf` (Active Directory and some standard LDAP servers) The user entry contains a `memberOf` attribute that lists the DNs of every group the user belongs to. This is the most efficient strategy. @@ -67,7 +67,7 @@ ldapMemberOfAttribute = "memberOf" When this is set, the group-search settings below are ignored. -#### Strategy B — Group membership search (standard LDAP) +#### Strategy B: Group membership search (standard LDAP) ICP searches the group subtree for entries whose membership attribute contains the user's DN. @@ -86,7 +86,7 @@ ldapMembershipAttribute = "memberUid" Set `ldapReadGroups = false` to skip group lookup entirely (no user will receive super-admin via LDAP roles). -### Admin role mapping +### Step 5: Configure admin role mapping List the LDAP group names (the value of `ldapGroupNameAttribute`, not the full DN) whose members should become ICP super-admins on first login: @@ -96,6 +96,7 @@ ldapAdminRoles = ["icp-admins", "administrators"] The comparison is **case-sensitive**. A user is placed in the ICP *Super Admins* group the **first time they log in** with a matching role. Subsequent role changes in LDAP are not reflected automatically. + ### TLS (LDAPS) For production deployments, enable TLS: @@ -195,7 +196,7 @@ On login the adapter: 1. Resolves the user's LDAP Distinguished Name (DN) — either directly from a pattern or via a directory search. 2. Authenticates the user by attempting an LDAP bind with their DN and password. 3. Reads the user's group memberships from the directory. -4. If any group matches a configured admin role, the user is granted ICP super-admin **on first login** (by adding them to the built-in *Super Admins* group). +4. If any group matches a configured admin role, the user is granted ICP super-admin (by adding them to the built-in *Super Admins* group). This happens only on the user's **first login** and is not re-evaluated on subsequent logins. 5. Returns a stable, deterministic user ID (UUID v5 derived from the username and search base) so the same LDAP user always maps to the same ICP user record. ## Troubleshooting From d96387a14837aa8413e649845d5becc3815ae9ab Mon Sep 17 00:00:00 2001 From: itsvishwa Date: Fri, 3 Jul 2026 10:49:31 +0530 Subject: [PATCH 2/3] Addressed review comments --- en/docs/manage/icp/encrypt-secrets.md | 10 +++++----- en/docs/manage/icp/manage-integrations.md | 2 +- en/docs/manage/icp/reverse-proxy.md | 4 +++- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/en/docs/manage/icp/encrypt-secrets.md b/en/docs/manage/icp/encrypt-secrets.md index 837eb7f8271..5fcde69b744 100644 --- a/en/docs/manage/icp/encrypt-secrets.md +++ b/en/docs/manage/icp/encrypt-secrets.md @@ -70,7 +70,7 @@ Replace all placeholders with your own values before running the command. ## Step 2: Configure the cipher tool -The cipher tool and ICP support multiple keystore types. PKCS12 (`.p12`) is the recommended format, but JKS and other standard Java keystore types are also supported. Adjust the type values in the steps below to match your keystore format. +The cipher tool and ICP support both PKCS12 (`.p12`) and JKS keystore types, with PKCS12 being the recommended format. Adjust the type values in the steps below to match your keystore format. 1. Copy your keystore file into the `conf/security/` directory of your ICP installation. 2. Open `conf/cipher-standalone-config.properties` and update the following properties to point to your keystore: @@ -179,10 +179,6 @@ cipherPrivateKeyPassword = "" | `cipherKeystorePassword` | Password to open the keystore | | `cipherPrivateKeyPassword` | Password for the private key entry | -:::note -These values must match exactly what you used when generating or obtaining the keystore and what you configured in `cipher-standalone-config.properties` in Step 2. If they differ, ICP will fail to decrypt the secrets at startup. -::: - Alternatively, the keystore passwords can be provided as environment variables, which take precedence over the `deployment.toml` values: ```bash @@ -190,6 +186,10 @@ export ICP_CIPHER_KEYSTORE_PASSWORD="" export ICP_PRIVATE_KEY_PASSWORD="" ``` +:::note +For simplicity, this guide points ICP to the same keystore used by the cipher tool in Step 2. This is not required: ICP can use a different keystore file, path, or alias, as long as it contains the same key pair. Secrets are encrypted with the public key, so ICP needs the matching private key to decrypt them. If the key pairs differ, ICP will fail to decrypt the secrets at startup. +::: + ## How ICP decrypts secrets at startup For each configuration field that contains a `$secret{alias}` reference, ICP retrieves the corresponding ciphertext from the secrets table, decrypts it using the private key in the cipher keystore, and uses the resulting plaintext value for the rest of the server lifetime. Decryption happens once during server startup. diff --git a/en/docs/manage/icp/manage-integrations.md b/en/docs/manage/icp/manage-integrations.md index 0288cd72042..84eca6be424 100644 --- a/en/docs/manage/icp/manage-integrations.md +++ b/en/docs/manage/icp/manage-integrations.md @@ -113,7 +113,7 @@ When operational, the page provides: - **Summary cards**: Total Requests, Error Count, Error Percentage, and P95 Latency - **Overview charts**: Requests Per Minute and Request Latency (average, P50, P95, P99) -- **Most Used APIs**: Table with per-endpoint request counts and average response times +- **Most Used APIs**: Table with per-endpoint request counts, error counts, and average response times - **Statistics of APIs**: Section with an API filter dropdown, showing Requests Per Minute, Average Request Latency, Successful Requests by API, and Failed Requests by API charts ### Listeners diff --git a/en/docs/manage/icp/reverse-proxy.md b/en/docs/manage/icp/reverse-proxy.md index 69180016534..a22451e0614 100644 --- a/en/docs/manage/icp/reverse-proxy.md +++ b/en/docs/manage/icp/reverse-proxy.md @@ -18,7 +18,9 @@ backendAuthBaseUrl = "https://icp.example.com/auth" backendObservabilityEndpoint = "https://icp.example.com/icp/observability" ``` -If not set, these values default to `https://localhost:9446`. When ICP starts, it reads these settings from `conf/deployment.toml` and propagates them into the console frontend automatically (you do not need to edit `www/config.json` directly). Restart ICP for the changes to take effect. +If not set, these values default to the values shown above under `https://localhost:9446/...`. + +When ICP starts, it reads these settings from `conf/deployment.toml` and propagates them into the console frontend automatically (you do not need to edit `www/config.json` directly). Restart ICP for the changes to take effect. ## Update runtime connections From 30f8cc848753461e97e5ef86f3f72f084946c68b Mon Sep 17 00:00:00 2001 From: itsvishwa Date: Fri, 3 Jul 2026 11:02:11 +0530 Subject: [PATCH 3/3] Update message for no secrets in secrets panel for clarity --- en/docs/manage/icp/manage-runtimes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/en/docs/manage/icp/manage-runtimes.md b/en/docs/manage/icp/manage-runtimes.md index fcd29805507..75973f4e11b 100644 --- a/en/docs/manage/icp/manage-runtimes.md +++ b/en/docs/manage/icp/manage-runtimes.md @@ -44,7 +44,7 @@ Click **+ Add Runtime** on an environment section to generate a secret and get a 1. Navigate to the **Runtimes** section at the integration level, then click **Manage Secrets** on any environment section. 2. The secrets panel opens showing all secrets for that environment - both bound (claimed by a runtime) and unbound (not yet claimed by any runtime). -3. If there are no secrets, the panel shows: *"No bound secrets for this integration in this environment."* +3. If there are no secrets, the panel shows: *"No secrets for this integration in this environment."* 4. Click the delete icon next to a secret to revoke it. ## Scope differences