Skip to content

docs: document opt-in safeUrlSchemes configuration parameter (CP: 24) #5792

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mcollovati wants to merge 1 commit into
base: v24
Choose a base branch
from
Open

docs: document opt-in safeUrlSchemes configuration parameter (CP: 24) #5792

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions articles/flow/configuration/properties.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -353,6 +353,12 @@
|`false`
|Build

|`safeUrlSchemes`
|`vaadin.safeUrlSchemes`
|Comma-separated list of URL schemes that are considered safe in URLs passed to `Anchor.setHref()`, `IFrame.setSrc()`, and `Page.open()`. URLs whose scheme isn't in the list are rejected with an `IllegalArgumentException`. Relative URLs are always accepted. This validation is opt-in: when the parameter isn't set, every scheme is accepted. An entry of `*` also marks every scheme as safe, disabling the validation. Starting with Vaadin 25.2, this validation is instead enabled by default, accepting the `http`, `https`, `mailto`, `tel`, and `ftp` schemes. URLs with unsafe schemes can still be set through the dedicated unsafe setters, such as `Anchor.setUnsafeHref()`.

Check warning on line 358 in articles/flow/configuration/properties.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/configuration/properties.adoc", "range": {"start": {"line": 358, "column": 431}}}, "severity": "WARNING"}
|`*` (validation disabled)
|Runtime

|`syncIdCheck`
|`vaadin.syncIdCheck`
|Enables synchronized ID checking. The synchronized ID is used to handle situations in which the client sends a message to a connector that has been removed from the server. It's set to `true`, by default. You should only disable it if your application doesn't need to stay synchronized, and suffers from a bad network connection.
Expand Down
12 changes: 12 additions & 0 deletions articles/flow/security/advanced-topics/vulnerabilities.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,18 @@
----


=== Unsafe URL Schemes

URLs using a script-capable scheme, such as `javascript:`, are another common XSS vector. Vaadin can validate URLs passed to `Anchor.setHref(String)`, `IFrame.setSrc(String)`, and `Page.open(String)` against a list of safe schemes, rejecting URLs whose scheme isn't considered safe with an `IllegalArgumentException`. Relative URLs have no scheme and are always accepted.

This validation is opt-in and disabled by default, so every URL scheme is accepted unless you enable it. To turn it on, set the `safeUrlSchemes` configuration parameter to a comma-separated list of safe schemes -- for example, `http,https,mailto,tel,ftp`. An entry of `*` marks every scheme as safe, disabling the validation. See <<{articles}/flow/configuration/properties#,Configuration Properties>> for how to set the parameter.

[NOTE]
Starting with Vaadin 25.2, this validation is enabled by default, accepting the `http`, `https`, `mailto`, `tel`, and `ftp` schemes. In earlier versions it's disabled by default and every scheme is accepted. When upgrading to Vaadin 25.2 or later, URLs with other schemes -- such as `javascript:` -- start to be rejected unless you configure `safeUrlSchemes` accordingly or switch to the unsafe setters.

Check warning on line 164 in articles/flow/security/advanced-topics/vulnerabilities.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/security/advanced-topics/vulnerabilities.adoc", "range": {"start": {"line": 164, "column": 227}}}, "severity": "WARNING"}

Check warning on line 164 in articles/flow/security/advanced-topics/vulnerabilities.adoc

View workflow job for this annotation

GitHub Actions / lint 

[vale] reported by reviewdog 🐶
[Vaadin.Versions] Don't refer to a specific Vaadin version.

Raw Output:
{"message": "[Vaadin.Versions] Don't refer to a specific Vaadin version.", "location": {"path": "articles/flow/security/advanced-topics/vulnerabilities.adoc", "range": {"start": {"line": 164, "column": 15}}}, "severity": "WARNING"}

If a URL is fully under your control and known to be safe, you can bypass the validation for that URL with the dedicated unsafe setters: `Anchor.setUnsafeHref(String)`, `IFrame.setUnsafeSrc(String)`, and `Page.openUnsafe(String)`.


=== Running Custom JavaScript

Sometimes you may need to run custom scripts inside the application. Running any script is an inherently unsafe operation. Scripts have full access to the entire client side. It's especially dangerous if the script is stored somewhere other than in the application code and loaded dynamically:
Expand Down
Loading