|
| 1 | +# Configure custom headers using a custom header filter |
| 2 | + |
| 3 | +The custom header filter adds custom HTTP headers to WSO2 Identity Server's own web applications. Use this to add security headers like Content-Security-Policy (CSP) to web apps. Supported apps include console, authentication endpoint, account recovery endpoint, and My Account portal. |
| 4 | + |
| 5 | +!!! info |
| 6 | + Add custom headers to your application's login pages by configuring the authentication endpoint. This applies the headers to login flows your applications use. |
| 7 | + |
| 8 | +!!! warning "Known limitations" |
| 9 | + |
| 10 | + WSO2 Identity Server web applications do not fully support CSP headers with `unsafe-inline` and `unsafe-eval` directives. |
| 11 | + |
| 12 | +{% if product_name == "WSO2 Identity Server" %} |
| 13 | + |
| 14 | +## Prerequisites |
| 15 | + |
| 16 | +See [Using the Configuration Management REST APIs]({{base_path}}/apis/use-the-configuration-management-rest-apis/) for prerequisites and general architecture. |
| 17 | + |
| 18 | +## Enable custom header filter |
| 19 | + |
| 20 | +Add the following configuration to the `<IS_HOME>/repository/conf/deployment.toml` file: |
| 21 | + |
| 22 | +```toml |
| 23 | +[custom_header_filter] |
| 24 | +enable = true |
| 25 | +``` |
| 26 | + |
| 27 | +Restart the server for the changes to take effect. |
| 28 | + |
| 29 | +{% if custom_header_min_version is defined %} |
| 30 | +!!! info |
| 31 | + This feature is available out of the box as an update in WSO2 Identity Server {{ is_version }} from update level **{{ custom_header_min_version }}** (Updates 2.0 model). See the instructions on [updating WSO2 products](https://updates.docs.wso2.com/en/latest/). |
| 32 | + |
| 33 | + If you don't have this update level, build the feature manually: |
| 34 | + |
| 35 | + 1. Clone the [identity-carbon-auth-rest](https://github.com/wso2-extensions/identity-carbon-auth-rest) repository. |
| 36 | + 2. Build the project using Java 11 or Java 17. |
| 37 | + 3. Copy `org.wso2.carbon.identity.custom.header.filter-${project.version}.jar` to the `<IS_HOME>/repository/components/dropins` directory. |
| 38 | +{% endif %} |
| 39 | + |
| 40 | +{% endif %} |
| 41 | + |
| 42 | +## Configure custom headers |
| 43 | + |
| 44 | +Follow these steps to configure custom headers for the web applications. |
| 45 | + |
| 46 | +{% if product_name == "WSO2 Identity Server" %} |
| 47 | + |
| 48 | +### Step 1: Register the custom-headers resource type |
| 49 | + |
| 50 | +Create a resource type named `custom-headers` to enable custom header configurations for the server. |
| 51 | + |
| 52 | +```bash |
| 53 | +curl -k -X POST https://{{ host_name }}/api/identity/config-mgt/v1.0/resource-type \ |
| 54 | + -H "accept: application/json" \ |
| 55 | + -H "Content-Type: application/json" \ |
| 56 | + -H "Authorization: Bearer {bearer_token}" \ |
| 57 | + -d '{ |
| 58 | + "name": "custom-headers", |
| 59 | + "description": "This is the resource type for custom header resources." |
| 60 | + }' |
| 61 | +``` |
| 62 | + |
| 63 | +### Step 2: Create custom headers for a web application |
| 64 | + |
| 65 | +{% else %} |
| 66 | + |
| 67 | +### Step 1: Create custom headers for a web application |
| 68 | + |
| 69 | +{% endif %} |
| 70 | + |
| 71 | +Create a new configuration with custom headers for the web application. |
| 72 | + |
| 73 | +The following example adds a `Content-Security-Policy` header to the `console` application: |
| 74 | + |
| 75 | +```bash |
| 76 | +curl -k -X POST https://{{ host_name }}/t/{{ root_organization_path }}/api/identity/config-mgt/v1.0/resource/custom-headers \ |
| 77 | + -H "accept: application/json" \ |
| 78 | + -H "Content-Type: application/json" \ |
| 79 | + -H "Authorization: Bearer {bearer_token}" \ |
| 80 | + -d '{ |
| 81 | + "name": <APP_NAME>, |
| 82 | + "attributes": [ |
| 83 | + { |
| 84 | + "key": "Content-Security-Policy", |
| 85 | + "value": "default-src '\''self'\''; script-src '\''self'\''; style-src '\''self'\''" |
| 86 | + } |
| 87 | + ] |
| 88 | + }' |
| 89 | +``` |
| 90 | + |
| 91 | +!!! note |
| 92 | + Replace `<APP_NAME>` with the web application name: |
| 93 | + |
| 94 | + - `console` - Admin Console |
| 95 | + - `authenticationendpoint` - Authentication endpoint |
| 96 | + - `accountrecoveryendpoint` - Account recovery endpoint |
| 97 | + - `myaccount` - My Account portal |
| 98 | + |
| 99 | +### Optional step: Add headers to an existing web application |
| 100 | + |
| 101 | +Add more headers to web applications with existing custom header configurations. |
| 102 | + |
| 103 | +```bash |
| 104 | +curl -k -X POST https://{{ host_name }}/t/{{ root_organization_path }}/api/identity/config-mgt/v1.0/resource/custom-headers/console \ |
| 105 | + -H "accept: application/json" \ |
| 106 | + -H "Content-Type: application/json" \ |
| 107 | + -H "Authorization: Bearer {bearer_token}" \ |
| 108 | + -d '{ |
| 109 | + "key": "X-Frame-Options", |
| 110 | + "value": "DENY" |
| 111 | + }' |
| 112 | +``` |
0 commit comments