Page Summary

outlined_flag

• Allowlists are used to pre-approve specific URLs that a script or add-on can access, which helps protect user data.

• Allowlists are optional for test deployments but required for versioned deployments.

• Allowlists are used when fetching information from external locations or opening/displaying external URLs in response to a user action.

• You must include a list of validhttps:// URL prefixes with a full domain and non-empty path in the manifest file to define an allowlist.

• You can use a single wildcard (*) as a leading prefix to match subdomains in your allowlist URL prefixes.

You use allowlists to designate specific URLs that are pre-approved for accessby your script or add-on. Allowlists help protect userdata; when you define an allowlist, script projects can't access URLs that havenot been added to the allowlist.

This field is optional when you install a test deployment, but is required whenyou create a versioned deployment.

You use allowlists when your script or add-on performsthe following actions:

• Retrieves or fetches information from an external location (such as HTTPSendpoints) using the Apps ScriptUrlFetchservice. To allowlist URLs for fetching, include theurlFetchWhitelist field in your manifest file.
• Opens or displays a URL in response to a user action (Required forGoogle Workspace add-ons that open or display URLs that are external toGoogle). To allowlist URLs for opening, include theaddOns.common.openLinkUrlPrefixes field in yourmanifest file.

Note:Whitelist, as used inurlFetchWhitelist, is a deprecated term that is synonymous with and replaced byallowlist. For more information, seeWriting inclusive documentation.

Adding prefixes to your allowlist

When you specify allowlists in your manifest file (by including either theaddOns.common.openLinkUrlPrefixes orurlFetchWhitelist field), you mustinclude a list of URL prefixes. The prefixes you add to the manifest mustsatisfy the following requirements:

• Each prefix must be a valid URL.
• Each prefix must usehttps://, nothttp://.
• Each prefix must have a full domain.
• Each prefix must have a non-empty path. For example,https://www.google.com/is valid buthttps://www.google.com is not.
• You can usewildcards to match URL subdomain prefixes.
• A single* wildcard can be used in theaddOns.common.openLinkUrlPrefixesfield to match all links, but this is not recommended as it can expose auser's data to risk and can prolong theadd-on review process. Onlyuse a wildcard if your add-on functionality requires it.

When determining if a URL matches a prefix in the allowlist, the following rulesapply:

• Path matching is case-sensitive.
• If the prefix is identical to the URL, it is a match.
• If the URL is the same or a child of the prefix, it is a match.

For example, the prefixhttps://example.com/foo matches the following URLs:

• https://example.com/foo
• https://example.com/foo/
• https://example.com/foo/bar
• https://example.com/foo?bar
• https://example.com/foo#bar

Using wildcards

You can use a single wildcard character (*) to match a subdomain for both theurlFetchWhitelistandaddOns.common.openLinkUrlPrefixesfields. You can't use more than one wildcard to match multiple subdomains, andthe wildcard must represent the leading prefix of the URL.

For example, the prefixhttps://*.example.com/foo matches the followingURLs:

• https://subdomain.example.com/foo
• https://any.number.of.subdomains.example.com/foo

The prefixhttps://*.example.com/foodoesn't match the followingURLs:

• https://subdomain.example.com/bar (suffix mismatch)
• https://example.com/foo (at least one subdomain must be present)

Some of the prefix rules are enforced when you try to save your manifest. Forexample, the following prefixes cause an error if they are present in yourmanifest when you attempt to save:

• https://*.*.example.com/foo (multiple wildcards are forbidden)
• https://subdomain.*.example.com/foo(wildcards must be used as a leading prefix)