diff --git a/en/asgardeo/docs/guides/your-asgardeo/manage-environments/promote-configurations.md b/en/asgardeo/docs/guides/your-asgardeo/manage-environments/promote-configurations.md index f31c797918..6fc06e81aa 100644 --- a/en/asgardeo/docs/guides/your-asgardeo/manage-environments/promote-configurations.md +++ b/en/asgardeo/docs/guides/your-asgardeo/manage-environments/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/identity-server/5.11.0/docs/setup/promote-configurations.md b/en/identity-server/5.11.0/docs/setup/promote-configurations.md index f34326ea4f..b0425826ce 100644 --- a/en/identity-server/5.11.0/docs/setup/promote-configurations.md +++ b/en/identity-server/5.11.0/docs/setup/promote-configurations.md @@ -156,3 +156,30 @@ By default, IAM-CTL does not delete any resources during import. It can be confi IAM-CTL provides options to manage sensitive data securely. By default, secrets fields are masked. The **`EXCLUDE_SECRETS`** property can be used to override this behavior and include the secrets in the exported resources. Learn more about these configurations in the [tool configurations documentation](https://github.com/wso2-extensions/identity-tools-cli/blob/master/docs/cli-mode.md#tool-configurations). + +## Logging + +IAM-CTL uses a unified logging system that provides structured, filterable log output with resource context and an end-of-run summary after every export or import operation. + +### Log configuration + +Add a `LOGS` block to your `toolConfig.json` to configure logging behavior: + +#### `toolConfig.json` + +```json +{ + "LOGS": { + "LOG_LEVEL": "INFO", + "LOG_REQUEST_PAYLOADS": false + } +} +``` + +| Property | Values | Default | Description | +| ---------------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | +| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO` | Minimum log level to print. Messages below this level are suppressed. | +| `LOG_REQUEST_PAYLOADS` | `true`, `false` | `false` | When set to `true`, HTTP request bodies are logged at `DEBUG` level for POST and PUT requests. | + +!!! warning "Sensitive data in request payloads" + Request bodies may contain sensitive credentials (client secrets, passwords, access tokens). Enabling `LOG_REQUEST_PAYLOADS` will write these values to your log output. Only enable this option in secure, non-production environments, and ensure log files are adequately protected. diff --git a/en/identity-server/7.0.0/docs/deploy/promote-configurations.md b/en/identity-server/7.0.0/docs/deploy/promote-configurations.md index 97e9bc0985..091cb93f10 100644 --- a/en/identity-server/7.0.0/docs/deploy/promote-configurations.md +++ b/en/identity-server/7.0.0/docs/deploy/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/identity-server/7.1.0/docs/deploy/promote-configurations.md b/en/identity-server/7.1.0/docs/deploy/promote-configurations.md index da84ad8f88..6795ed7951 100644 --- a/en/identity-server/7.1.0/docs/deploy/promote-configurations.md +++ b/en/identity-server/7.1.0/docs/deploy/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/identity-server/7.2.0/docs/deploy/promote-configurations.md b/en/identity-server/7.2.0/docs/deploy/promote-configurations.md index 548dca5e21..085431566b 100644 --- a/en/identity-server/7.2.0/docs/deploy/promote-configurations.md +++ b/en/identity-server/7.2.0/docs/deploy/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/identity-server/7.3.0/docs/deploy/promote-configurations.md b/en/identity-server/7.3.0/docs/deploy/promote-configurations.md index 612f3a0ca2..d305bfddb5 100644 --- a/en/identity-server/7.3.0/docs/deploy/promote-configurations.md +++ b/en/identity-server/7.3.0/docs/deploy/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/identity-server/next/docs/deploy/promote-configurations.md b/en/identity-server/next/docs/deploy/promote-configurations.md index 612f3a0ca2..d305bfddb5 100644 --- a/en/identity-server/next/docs/deploy/promote-configurations.md +++ b/en/identity-server/next/docs/deploy/promote-configurations.md @@ -7,3 +7,5 @@ {% include "../../../../includes/deploy/ctl-tool/tool-setup-and-usage.md" %} {% include "../../../../includes/deploy/ctl-tool/propagate-between-child-organizations.md" %} {% include "../../../../includes/deploy/ctl-tool/customization-options.md" %} +{% include "../../../../includes/deploy/ctl-tool/logging.md" %} +{% include "../../../../includes/deploy/ctl-tool/resource-specific-notes.md" %} diff --git a/en/includes/deploy/ctl-tool/getting-started-7.x.md b/en/includes/deploy/ctl-tool/getting-started-7.x.md index 0a04940e3a..541799c36d 100644 --- a/en/includes/deploy/ctl-tool/getting-started-7.x.md +++ b/en/includes/deploy/ctl-tool/getting-started-7.x.md @@ -30,6 +30,68 @@ Follow the steps below to register an M2M application. Management --> Userstore Management API Create Userstore, Update Userstore, Delete Userstore, View Userstore + + Management --> API Resource Management API + Create API Resource, Update API Resource, Delete API Resource, View API Resource + + + Management --> OIDC Scope Management API + Create OIDC Scopes, Update OIDC Scopes, Delete OIDC Scopes, View OIDC Scopes + + + Management --> SCIM2 Roles V1/V2 API + Create Role, Update Role, Delete Role, View Role, Update Permissions of Role + + + Management --> Identity Governance Management API + View Identity Governance, Update Identity Governance + + + Management --> Validation Rules API + Update Validation Rule + + + Management --> Organization Management API + Create Organizations, Update Organizations, Delete Organizations, View Organizations + + + Management --> Branding Preference Management API + Update Branding Preference + + {% if server_version == "7.0" %} + + Management --> Email Template Management API v1/v2 + Create Email Template, Update Email Template, Delete Email Template, View Email Template + + {% endif %} + {% if product_name == "Asgardeo" or server_version >= "7.1" %} + + Management --> Notification Template Management API + Create Notification Template, Update Notification Template, Delete Notification Template, View Notification Template + + + Management --> Action Management API + Create Action, Update Action, Delete Action, View Action + + {% endif %} + {% if product_name == "Asgardeo" or server_version >= "7.2" %} + + Management --> Notification Sender Management API + Create Notification Senders, Update Notification Senders, Delete Notification Senders, View Notification Senders + + + Management --> Workflow Management API + Create Workflow, Update Workflow, Delete Workflow, View Workflow + + + Management --> Workflow Association Management API + Create Workflow Association, Update Workflow Association, Delete Workflow Association, View Workflow Association + + + Management --> Flow Management API + View Flow, Update Flow + + {% endif %} diff --git a/en/includes/deploy/ctl-tool/logging.md b/en/includes/deploy/ctl-tool/logging.md new file mode 100644 index 0000000000..95b643da44 --- /dev/null +++ b/en/includes/deploy/ctl-tool/logging.md @@ -0,0 +1,26 @@ +## Logging + +IAM-CTL uses a unified logging system that provides structured, filterable log output with resource context and an end-of-run summary after every export or import operation. + +### Log configuration + +Add a `LOGS` block to your `toolConfig.json` to configure logging behavior: + +=== "toolConfig.json" + + ```json + { + "LOGS": { + "LOG_LEVEL": "INFO", + "LOG_REQUEST_PAYLOADS": false + } + } + ``` + +| Property | Values | Default | Description | +| ---------------------- | -------------------------------- | ------- | ---------------------------------------------------------------------------------------------- | +| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR` | `INFO` | Minimum log level to print. Messages below this level are suppressed. | +| `LOG_REQUEST_PAYLOADS` | `true`, `false` | `false` | When set to `true`, HTTP request bodies are logged at `DEBUG` level for POST and PUT requests. | + +!!! warning "Sensitive data in request payloads" + Request bodies may contain sensitive credentials (client secrets, passwords, access tokens). Enabling `LOG_REQUEST_PAYLOADS` will write these values to your log output. Only enable this option in secure, non-production environments, and ensure log files are adequately protected. diff --git a/en/includes/deploy/ctl-tool/resource-specific-notes.md b/en/includes/deploy/ctl-tool/resource-specific-notes.md new file mode 100644 index 0000000000..6ff0e434db --- /dev/null +++ b/en/includes/deploy/ctl-tool/resource-specific-notes.md @@ -0,0 +1,82 @@ +## Resource-specific notes + +Note the following resource-type-specific behavior when using IAM-CTL. + +!!! note + IAM-CTL treats users and groups as dynamic configurations that are not portable across environments. When a resource contains embedded user or group data, IAM-CTL strips that data during export. As a result, import removes this data from the affected resource in the target environment. For resources that contain dynamic data, use IAM-CTL for initial resource creation only. Add the dynamic configurations manually, then exclude the resource in future imports using **`EXCLUDE`** to preserve the data. + +### Roles + +Users and groups assigned to roles are not exported or imported by IAM-CTL. + +### Claims + +Claim dialect names may contain characters that are not valid in file names (e.g., `http://wso2.org/oidc/claim`). IAM-CTL uses an escaped version of the dialect name as the file name (e.g., `http_wso2_org_oidc_claim`). When referencing a claim dialect in tool configurations such as **`EXCLUDE`** or keyword mappings, use the exact claim dialect name, not the escaped file name. + +### User stores + +When propagating user stores, do not exclude the local claim dialect (`http://wso2.org/claims`). Excluding it will prevent new claim attribute mappings of user stores from being propagated. + +### Applications + +When propagating applications, do not exclude roles. Excluding roles will prevent new application roles from being propagated. + +### Governance connectors + +Group-based password expiry rules of the password expiry connector are not exported by IAM-CTL. As a result, these rules will be removed from the connector on import, when **`ALLOW_DELETE`** is enabled. + +{% if product_name == "Asgardeo" or server_version >= "7.3" %} + +### Identity providers + +Outbound provisioning groups of outbound provisioning connectors are not exported by IAM-CTL. As a result, these groups will be removed from the identity provider on import. + +{% endif %} + +### Organizations + +{% if product_name != "Asgardeo" %} +When referencing organizations in tool configurations such as **`EXCLUDE`** or keyword mappings, use the organization handle as the resource name. +{% endif %} + +When IAM-CTL creates organizations using the management application credentials, no user is assigned as the creator. As a result, no user has access to the newly created organization after creation. You can [manually assign an organization admin]({{base_path}}/guides/organization-management/onboard-org-admins/self-service-approach/#maintain-admins-within-the-organization){:target="_blank"} after IAM-CTL creates the organization. + +{% if product_name != "Asgardeo" and server_version >= "7.0" and server_version < "7.3" %} + +To assign a creator at import time, configure **`CREATOR_ID`** and **`CREATOR_USERNAME`** under `ORGANIZATIONS` in `toolConfig.json`. + +=== "toolConfig.json" + ```json + { + "ORGANIZATIONS": { + "CREATOR_ID": "", + "CREATOR_USERNAME": "" + } + } + ``` + +When both values are set, IAM-CTL assigns the specified user as the organization creator on import. IAM-CTL strips these attributes on export and does not store them in the exported files, as they are environment-specific and not portable. + +{% endif %} + +### Branding + +Branding contains two sub-resource types: **Branding Preferences** and **Custom Texts**. When referencing branding in tool configurations such as **`EXCLUDE`** or keyword mappings, use the sub-resource type names as shown below. + +=== "toolConfig.json" + ```json + { + "EXCLUDE": ["BrandingPreferences"], + "CUSTOM_TEXTS": { + "EXCLUDE": ["screen1"] + } + } + ``` + +{% if product_name == "Asgardeo" or server_version >= "7.2" %} + +### Workflows + +Users included in approval steps are not exported by IAM-CTL. These users will be removed from the exported workflow, and any approval steps that contained only users will also be removed. As a result, these users and steps will be removed from the workflow on import. + +{% endif %} diff --git a/en/includes/deploy/ctl-tool/resource-types-7.x.md b/en/includes/deploy/ctl-tool/resource-types-7.x.md index 9b7cf18746..fb5867ccad 100644 --- a/en/includes/deploy/ctl-tool/resource-types-7.x.md +++ b/en/includes/deploy/ctl-tool/resource-types-7.x.md @@ -6,3 +6,21 @@ IAM-CTL provides support for propagating the following resource types among root - Identity Providers - Claims - User Stores +- API Resources +- OIDC Scopes +- Roles +- Email Templates +- Governance Connectors +- Validation Rules +- Organizations +- Branding +{% if product_name == "Asgardeo" or server_version >= "7.1" %} +- SMS Templates +- Actions +{% endif %} +{% if product_name == "Asgardeo" or server_version >= "7.2" %} +- Email Providers +- SMS Providers +- Workflows +- Flows +{% endif %}