From dd54af2edf85684d7948bfad27d4befa07b2df5e Mon Sep 17 00:00:00 2001 From: Hasini Samarathunga Date: Wed, 7 Jan 2026 11:42:29 +0530 Subject: [PATCH] Add Custom Header Filter documentation to supported versions --- .../docs/references/custom-header-filter.md | 3 + en/asgardeo/mkdocs.yml | 1 + .../6.1.0/docs/deploy/custom-header-filter.md | 89 +++++++++++++++ en/identity-server/6.1.0/mkdocs.yml | 1 + .../deploy/configure/custom-header-filter.md | 3 + en/identity-server/7.1.0/mkdocs.yml | 1 + .../deploy/configure/custom-header-filter.md | 3 + en/identity-server/7.2.0/mkdocs.yml | 1 + .../deploy/configure/custom-header-filter.md | 3 + en/identity-server/next/mkdocs.yml | 1 + .../deploy/configure/custom-header-filter.md | 101 ++++++++++++++++++ 11 files changed, 207 insertions(+) create mode 100644 en/asgardeo/docs/references/custom-header-filter.md create mode 100644 en/identity-server/6.1.0/docs/deploy/custom-header-filter.md create mode 100644 en/identity-server/7.1.0/docs/deploy/configure/custom-header-filter.md create mode 100644 en/identity-server/7.2.0/docs/deploy/configure/custom-header-filter.md create mode 100644 en/identity-server/next/docs/deploy/configure/custom-header-filter.md create mode 100644 en/includes/deploy/configure/custom-header-filter.md diff --git a/en/asgardeo/docs/references/custom-header-filter.md b/en/asgardeo/docs/references/custom-header-filter.md new file mode 100644 index 0000000000..109a759338 --- /dev/null +++ b/en/asgardeo/docs/references/custom-header-filter.md @@ -0,0 +1,3 @@ +{% set host_name = "api.asgardeo.io" %} +{% set root_organization_path = "{root_organization_name}" %} +{% include "../../../includes/deploy/configure/custom-header-filter.md" %} diff --git a/en/asgardeo/mkdocs.yml b/en/asgardeo/mkdocs.yml index 6b947ff658..46541064c5 100644 --- a/en/asgardeo/mkdocs.yml +++ b/en/asgardeo/mkdocs.yml @@ -734,6 +734,7 @@ nav: - Remote agent properties: references/remote-user-store/remote-user-store-properties.md - Authorization policies for apps: references/authorization-policies-for-apps.md - Configure Cross Origin Resource Sharing (CORS): references/configure-cors.md + - Custom Header Filter: references/custom-header-filter.md - Email templates: references/email-templates.md - SMS templates: references/sms-templates.md - Service extensions: diff --git a/en/identity-server/6.1.0/docs/deploy/custom-header-filter.md b/en/identity-server/6.1.0/docs/deploy/custom-header-filter.md new file mode 100644 index 0000000000..6153b39ec5 --- /dev/null +++ b/en/identity-server/6.1.0/docs/deploy/custom-header-filter.md @@ -0,0 +1,89 @@ +# Configure custom headers using a custom header filter + +The Custom Header Filter adds custom HTTP headers to WSO2 Identity Server's own web applications. You can use this to add security headers, such as Content-Security-Policy (CSP) headers, to WSO2 Identity Server web applications like Console, Authentication Endpoint, Account Recovery Endpoint, and My Account. + +!!! info + If you want to add custom headers to login pages for your applications, you can add the header to the server response via the custom header filter. This applies to the Authentication Endpoint that the applications use for login flows. + +!!! warning "Known limitations" + + WSO2 Identity Server web applications do not fully support CSP headers with `unsafe-inline` and `unsafe-eval` directives due to code base limitations. + +## Prerequisites + +See [Using the Configuration Management REST APIs]({{base_path}}/develop/using-the-configuration-management-rest-apis/) for prerequisites and general architecture. + +## Enable custom header filter + +Add the following configuration to the `/repository/conf/deployment.toml` file: + +```toml +[custom_header_filter] +enable = true +``` + +Restart the server for the changes to take effect. + +## Configure custom headers + +Follow these steps to configure custom headers for the web applications. + +### Step 1: Register the custom-headers resource type + +Create a resource type named `custom-headers` to enable custom header configurations for the server. + +```bash +curl -k -X POST https://localhost:9443/api/identity/config-mgt/v1.0/resource-type \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Basic YWRtaW46YWRtaW4=" \ + -d '{ + "name": "custom-headers", + "description": "This is the resource type for custom header resources." + }' +``` + +### Step 2: Create custom headers for a web application + +Create a new configuration with custom headers for the web application. + +The following example adds a `Content-Security-Policy` header to the `console` application: + +```bash +curl -k -X POST hhttps://localhost:9443/t/{root_organization_name}/api/identity/config-mgt/v1.0/resource/custom-headers \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Basic YWRtaW46YWRtaW4=" \ + -d '{ + "name": "console", + "attributes": [ + { + "key": "Content-Security-Policy", + "value": "default-src '\''self'\''; script-src '\''self'\''; style-src '\''self'\''" + } + ] + }' +``` + +!!! note + Replace `console` with the web application name: + + - `console` - Admin Console + - `authenticationendpoint` - Authentication Endpoint + - `accountrecoveryendpoint` - Account Recovery Endpoint + - `myaccount` - My Account Portal + +### Optional Step: Add headers to an existing web application + +Add additional headers to a web application that already has custom header configurations. + +```bash +curl -k -X POST https://localhost:9443/t/{root_organization_name}/api/identity/config-mgt/v1.0/resource/custom-headers/console \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Basic YWRtaW46YWRtaW4=" \ + -d '{ + "key": "X-Frame-Options", + "value": "DENY" + }' +``` diff --git a/en/identity-server/6.1.0/mkdocs.yml b/en/identity-server/6.1.0/mkdocs.yml index e8f1b69e4b..5bb3268671 100644 --- a/en/identity-server/6.1.0/mkdocs.yml +++ b/en/identity-server/6.1.0/mkdocs.yml @@ -418,6 +418,7 @@ nav: - Customize Email Templates: guides/tenants/customize-automated-mails.md - Tenant Loading Policy: guides/tenants/configure-the-tenant-loading-policy.md - CORS : deploy/configure-cors.md + - Custom Header Filter: deploy/custom-header-filter.md - reCAPTCHA: deploy/configure-recaptcha.md - Secure: - Mitigate Attacks: diff --git a/en/identity-server/7.1.0/docs/deploy/configure/custom-header-filter.md b/en/identity-server/7.1.0/docs/deploy/configure/custom-header-filter.md new file mode 100644 index 0000000000..b56118ae9b --- /dev/null +++ b/en/identity-server/7.1.0/docs/deploy/configure/custom-header-filter.md @@ -0,0 +1,3 @@ +{% set host_name = "localhost:9443" %} +{% set root_organization_path = "{root_organization_name}" %} +{% include "../../../../../includes/deploy/configure/custom-header-filter.md" %} diff --git a/en/identity-server/7.1.0/mkdocs.yml b/en/identity-server/7.1.0/mkdocs.yml index da75d647b3..45a5bf2167 100644 --- a/en/identity-server/7.1.0/mkdocs.yml +++ b/en/identity-server/7.1.0/mkdocs.yml @@ -843,6 +843,7 @@ nav: - Remove References to Deleted User Identities: deploy/configure/databases/remove-references-to-deleted-user-identities.md - Session persistence: deploy/configure/session-persistence.md - Cross-Origin Resource Sharing (CORS): deploy/configure/configure-cors.md + - Custom Header Filter: deploy/configure/custom-header-filter.md - Clock tolerance: deploy/configure/clock-tolerance.md - Cookie consent banner: deploy/configure/cookie-consent-banner.md - Email sending module: deploy/configure/email-sending-module.md diff --git a/en/identity-server/7.2.0/docs/deploy/configure/custom-header-filter.md b/en/identity-server/7.2.0/docs/deploy/configure/custom-header-filter.md new file mode 100644 index 0000000000..d40e52fa1b --- /dev/null +++ b/en/identity-server/7.2.0/docs/deploy/configure/custom-header-filter.md @@ -0,0 +1,3 @@ +{% set host_name = "localhost:9443" %} +{% set root_organization_path = "{root_organization_handle}" %} +{% include "../../../../../includes/deploy/configure/custom-header-filter.md" %} diff --git a/en/identity-server/7.2.0/mkdocs.yml b/en/identity-server/7.2.0/mkdocs.yml index 222984b093..555bb3829c 100644 --- a/en/identity-server/7.2.0/mkdocs.yml +++ b/en/identity-server/7.2.0/mkdocs.yml @@ -902,6 +902,7 @@ nav: - Remove References to Deleted User Identities: deploy/configure/databases/remove-references-to-deleted-user-identities.md - Session persistence: deploy/configure/session-persistence.md - Cross-Origin Resource Sharing (CORS): deploy/configure/configure-cors.md + - Custom Header Filter: deploy/configure/custom-header-filter.md - Clock tolerance: deploy/configure/clock-tolerance.md - Cookie consent banner: deploy/configure/cookie-consent-banner.md - Secure: diff --git a/en/identity-server/next/docs/deploy/configure/custom-header-filter.md b/en/identity-server/next/docs/deploy/configure/custom-header-filter.md new file mode 100644 index 0000000000..d40e52fa1b --- /dev/null +++ b/en/identity-server/next/docs/deploy/configure/custom-header-filter.md @@ -0,0 +1,3 @@ +{% set host_name = "localhost:9443" %} +{% set root_organization_path = "{root_organization_handle}" %} +{% include "../../../../../includes/deploy/configure/custom-header-filter.md" %} diff --git a/en/identity-server/next/mkdocs.yml b/en/identity-server/next/mkdocs.yml index 1e0e15aeb4..75b6c2a994 100644 --- a/en/identity-server/next/mkdocs.yml +++ b/en/identity-server/next/mkdocs.yml @@ -903,6 +903,7 @@ nav: - Remove References to Deleted User Identities: deploy/configure/databases/remove-references-to-deleted-user-identities.md - Session persistence: deploy/configure/session-persistence.md - Cross-Origin Resource Sharing (CORS): deploy/configure/configure-cors.md + - Custom Header Filter: deploy/configure/custom-header-filter.md - Clock tolerance: deploy/configure/clock-tolerance.md - Cookie consent banner: deploy/configure/cookie-consent-banner.md - Secure: diff --git a/en/includes/deploy/configure/custom-header-filter.md b/en/includes/deploy/configure/custom-header-filter.md new file mode 100644 index 0000000000..a5c2a87ed5 --- /dev/null +++ b/en/includes/deploy/configure/custom-header-filter.md @@ -0,0 +1,101 @@ +# Configure custom headers using a custom header filter + +The Custom Header Filter adds custom HTTP headers to {{product_name}}'s own web applications. You can use this to add security headers, such as Content-Security-Policy (CSP) headers, to {{product_name}} web applications like Console, Authentication Endpoint, Account Recovery Endpoint, and My Account. + +!!! info + If you want to add custom headers to login pages for your applications, you can add the header to the server response via the custom header filter. This applies to the Authentication Endpoint that the applications use for login flows. + +!!! warning "Known limitations" + + {{product_name}} web applications do not fully support CSP headers with `unsafe-inline` and `unsafe-eval` directives due to code base limitations. + +{% if product_name == "WSO2 Identity Server" %} + +## Prerequisites + +See [Using the Configuration Management REST APIs]({{base_path}}/develop/using-the-configuration-management-rest-apis/) for prerequisites and general architecture. + +## Enable custom header filter + +Add the following configuration to the `/repository/conf/deployment.toml` file: + +```toml +[custom_header_filter] +enable = true +``` + +Restart the server for the changes to take effect. + +{% endif %} + +## Configure custom headers + +Follow these steps to configure custom headers for the web applications. + +{% if product_name == "WSO2 Identity Server" %} + +### Step 1: Register the custom-headers resource type + +Create a resource type named `custom-headers` to enable custom header configurations for the server. + +```bash +curl -k -X POST https://{{ host_name }}/api/identity/config-mgt/v1.0/resource-type \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {bearer_token}" \ + -d '{ + "name": "custom-headers", + "description": "This is the resource type for custom header resources." + }' +``` + +### Step 2: Create custom headers for a web application + +{% else %} + +### Step 1: Create custom headers for a web application + +{% endif %} + +Create a new configuration with custom headers for the web application. + +The following example adds a `Content-Security-Policy` header to the `console` application: + +```bash +curl -k -X POST https://{{ host_name }}/t/{{ root_organization_path }}/api/identity/config-mgt/v1.0/resource/custom-headers \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {bearer_token}" \ + -d '{ + "name": "console", + "attributes": [ + { + "key": "Content-Security-Policy", + "value": "default-src '\''self'\''; script-src '\''self'\''; style-src '\''self'\''" + } + ] + }' +``` + +!!! note + Replace `console` with the web application name: + + - `console` - Admin Console + - `authenticationendpoint` - Authentication Endpoint + - `accountrecoveryendpoint` - Account Recovery Endpoint + - `myaccount` - My Account Portal + +### Optional Step: Add headers to an existing web application + +Add additional headers to a web application that already has custom header configurations. + +```bash +curl -k -X POST https://{{ host_name }}/t/{{ root_organization_path }}/api/identity/config-mgt/v1.0/resource/custom-headers/console \ + -H "accept: application/json" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer {bearer_token}" \ + -d '{ + "key": "X-Frame-Options", + "value": "DENY" + }' +```