URL Validation
Available since 1.43.0
Overview
Beginning in version 1.43.0 FusionAuth provides support for wildcards in OAuth 2.0 redirect URLs and origin URLs. This document provides details on where wildcards are allowed in configured values and the valid replacement patterns for wildcards in each position.
URL Validation Policy
In order to validate allowed authorized redirect and origin URLs containing wildcards, the URL validation setting must be configured to Allow wildcards under Applications -> Edit Application -> OAuth.
See the Application API or Application OAuth Configuration for details.
Allowed Wildcard Positions
In order to maintain security while allowing the flexibility of wildcards, FusionAuth limits the position and number of wildcards that are allowed in the configured authorized redirect and origin URLs. The asterisk character, *, is the wildcard character.
Domain
The domain of a configured URL allows 0 or 1 wildcards in the domain portion of the URL. Wildcards are not allowed if the host is specified by an IP address. If the domain contains a wildcard, it must meet all of the following requirements:
- The domain must contain at least three segments.
- The wildcard may only appear in the host portion of the domain (left-most subdomain).
- The wildcard can be a full or partial replacement of the host.
The following table provides some examples of valid and invalid wildcard patterns.
Domain Wildcards
| Example | Valid | Reason |
|---|---|---|
https://*.example.com | ||
https://blah*.example.com | ||
https://*.com | The domain only contains two segments | |
https://auth.*.com | The wildcard does not appear in the host | |
https://*mid*.example.com | The domain contains multiple wildcards | |
https://*.168.1.1 | Wildcards are not allowed with IP addresses |
Port
The port number can be specified as a wildcard. There is no partial wildcard support for the port number.
Port Wildcards
| Example | Valid | Reason |
|---|---|---|
https://example.com:* | ||
https://example.com:4* | Partial wildcards are not allowed for the port number |
Path Segments
Wildcards are allowed in path segments with the following restrictions:
- There can be no more than one wildcard per path segment.
- The wildcard can be a full or partial replacement of the path segment.
The following table provides some examples of valid and invalid wildcard patterns in the path.
Path Wildcards
| Example | Valid | Reason |
|---|---|---|
https://example.com/path/*/resource | ||
https://example.com/p*/to/resource | ||
https://example.com/*/par*tial/* | ||
https://example.com/path/*mid*/resource | The path segment contains multiple wildcards |
Query String Values
Wildcards are allowed in query string values with the following restrictions:
- Partial wildcards are not allowed for query string values.
Wildcards are not allowed in query string names. The following table provides some examples of valid and invalid wildcard patterns in the query string.
Query String Wildcards
| Example | Valid | Reason |
|---|---|---|
https://example.com?foo=* | ||
https://example.com?foo=*&bar=*&baz=blah | ||
https://example.com?foo=par*tial | Partial wildcard replacement is not allowed for query string values | |
https://example.com?*=blah | Wildcards are not allowed in query string names |
Wildcard Replacement Patterns
The position where wildcards are allowed in configured values is just one half of the puzzle. Wildcards in each portion of the URL have different rules for the replacement values. Please note that allowed replacement values may not produce a valid URL. This section provides details on the allowed replacements for wildcards in each portion of the URL. Each wildcard in the configured value must match one or more characters. Matches against empty strings will fail.
Domain
Replacements for wildcards in the domain portion of the URL must not contain ., :, /, or ? characters. The following table lists examples of valid and invalid replacements for valid wildcard patterns.
Domain wildcard replacement
| Pattern | Value | Valid | Reason |
|---|---|---|---|
https://*.example.com | https://login.example.com | ||
https://auth*.example.com | https://auth2.example.com | ||
https://auth*.example.com | https://auth.example.com | The value does not contain a character to replace the * | |
https://*.example.com | https://auth.customer.example.com | The replacement contains a . character |
Port
Replacement values for wildcards in the port portion of the URL must consist of one or more decimal digits.
Port wildcard replacement
| Pattern | Value | Valid | Reason |
|---|---|---|---|
https://example.com:* | https://example.com:2012 | ||
https://example.com: | https://example.com:80b | The replacement value contains a non-numeric character |
Path Segments
Replacement values for wildcards in a path segment of the URL must not contain / or ? characters.
Path segment wildcard replacement
| Pattern | Value | Valid | Reason |
|---|---|---|---|
https://example.com/path/*/resource | https://example.com/path/to/resource | ||
https://example.com/p*/to/resource | https://example.com/path/to/resource | ||
https://example.com/*/par*tial/* | https://example.com/path/partotial/resource | ||
https://example.com/path/*/resource | https://example.com/path/to/the/resource | The replacement value contains a / | |
https://example.com/path/* | https://example.com/path/resource?foo=bar | The replacement value contains a ? | |
https://example.com/*/par*tial/* | https://example.com/path/partial/resource | The segment partial does not contain a replacement character for the wildcard |
Query String Values
Replacement values for query string values must not contain the & character.
Query string value wildcard replacement
| Pattern | Value | Valid | Reason |
|---|---|---|---|
https://example.com?foo=* | https://example.com?foo=bar | ||
https://example.com?foo=* | https://example.com?foo=bar&baz=blah | The replacement value contains an & character | |
https://example.com?foo=* | https://example.com?baz=blah&foo=bar | The replacement value contains an extra query string parameter |