- 6 minutes to read

ArticleSecurityPolicy - System Parameter

New 7.12

ArticleSecurityPolicy is a JSON System Parameter that decides which security checks Nodinite runs on the HTML of Articles, of Markdown values such as Custom Metadata, and of User Notifications, as the last step before the HTML reaches a browser. The Article editor and the previews follow the same policy.

An Article whose Microsoft Teams link shows as plain text; ArticleSecurityPolicy opened from the System Parameters list, msteams added to UnsafeLinks.AllowedSchemes, Save; after a reload the same Article shows a working link, animated walkthrough (7.12)
Animated walkthrough: the Article Contoso Orders: on-call contacts links to the on-call channel in Microsoft Teams. The msteams scheme isn't allowed, so the link shows as plain text. Adding msteams to UnsafeLinks.AllowedSchemes and saving turns it into a link after a reload.

At a Glance

Property Value
Key ArticleSecurityPolicy
Data type json
Default Every check on (see the example)
Read by Web API and Web Client
Takes effect Within about a minute; no restart needed. The Web Client keeps the policy for 30 seconds and the Web API for 15.
Status ✅ Active
Since Nodinite 7.12

The ArticleSecurityPolicy edit page with its JSON value in a taller box, the Scripts, EventHandlers and UnsafeLinks checks on, and Save in the page toolbar (7.12)
The ArticleSecurityPolicy System Parameter after an upgrade: every check is on. The value field is dragged taller to show the JSON.

How It Works

Every time an Article, a Markdown value, or a User Notification is sent to a browser, Nodinite cleans its HTML with the checks this policy has switched on. Only an Administrator can change the value, and the JSON is checked when you save it.

  • The stored text doesn't change by reading it. The cleaning happens on the way out. When you open an HTML Article in the editor and save it, the cleaned text is stored, and the editor doesn't show that as a pending change. The earlier text stays in the Revision History.
  • Values filled in by Macros are cleaned too.
  • Exports and the MCP Endpoint are not cleaned this way. They are downloads and text for tools, so they only keep the protection against script tags.
  • No setting makes a script tag run. With the Scripts check off, a script tag shows as text. With Enabled off at the root, script tags are still removed; only the other checks stop.

What each check removes:

Check Removes
Scripts Script tags.
EventHandlers Attributes such as onerror and onclick.
UnsafeLinks Links whose address scheme is not in AllowedSchemes. A pasted image stored as a data address is always kept.
Iframes Frames from sites that are not in AllowedSites.
Svg Inline SVG elements and attributes that are not in AllowedElements and AllowedAttributes.
Styles Style blocks, and inline style properties that are not known CSS properties. AdditionalProperties keeps more.
OtherMarkup Everything else Articles have no use for, such as forms, buttons, object and embed. AdditionalElements and AdditionalAttributes keep more.

What Changes for Existing Content

  • Rendered Articles and Markdown Custom Metadata no longer keep event handlers, unsafe links, style blocks, forms and buttons, object and embed elements, unknown attributes, inline SVG beyond svg and path, or iframes from other sites than the three listed.
  • Videos from YouTube and Vimeo keep embedding. Video links from other sites, such as music.yandex.ru and ok.ru, stop embedding until you add the site to AllowedSites.
  • Script tags disappear from the page instead of showing as text.

Value Format

Property Type Default Meaning
Enabled (root) boolean true false turns the other checks off. Script tags are still removed.
Scripts.Enabled boolean true Remove script tags.
EventHandlers.Enabled boolean true Remove event handler attributes.
UnsafeLinks.Enabled boolean true Keep only links with an allowed scheme.
UnsafeLinks.AllowedSchemes string array http, https, mailto, tel, ftp, file The address schemes links may use.
Iframes.Enabled boolean true Keep only frames from allowed sites.
Iframes.AllowedSites string array www.youtube.com, www.youtube-nocookie.com, player.vimeo.com Plain host names whose frames are kept.
Svg.Enabled boolean true Limit inline SVG.
Svg.AllowedElements string array svg, path SVG elements that are kept.
Svg.AllowedAttributes string array viewBox, version, width, height, aria-hidden, d SVG attributes that are kept.
Styles.Enabled boolean true Remove style blocks and unknown inline style properties.
Styles.AdditionalProperties string array empty Extra CSS properties to keep in inline styles.
OtherMarkup.Enabled boolean true Remove other markup Articles have no use for.
OtherMarkup.AdditionalElements string array empty Extra elements to keep.
OtherMarkup.AdditionalAttributes string array empty Extra attributes to keep.

The value is refused on save when:

  • a list names a script element, an event handler, srcdoc, foreignObject, SVG animation, use or href;
  • UnsafeLinks.AllowedSchemes names javascript, vbscript or data;
  • OtherMarkup.AdditionalElements names noscript, template, frame, frameset, svg, math, base, meta or link;
  • an entry has the wrong shape for its list: a scheme, a plain host name, a CSS property name, or an element or attribute name;
  • the value is empty (the Web API answers 400 Empty string is not allowed).

Example, with every check on:

{
  "Enabled": true,
  "Scripts": { "Enabled": true },
  "EventHandlers": { "Enabled": true },
  "UnsafeLinks": {
    "AllowedSchemes": [ "http", "https", "mailto", "tel", "ftp", "file" ],
    "Enabled": true
  },
  "Iframes": {
    "AllowedSites": [ "www.youtube.com", "www.youtube-nocookie.com", "player.vimeo.com" ],
    "Enabled": true
  },
  "Svg": {
    "AllowedElements": [ "svg", "path" ],
    "AllowedAttributes": [ "viewBox", "version", "width", "height", "aria-hidden", "d" ],
    "Enabled": true
  },
  "Styles": {
    "AdditionalProperties": [],
    "Enabled": true
  },
  "OtherMarkup": {
    "AdditionalElements": [],
    "AdditionalAttributes": [],
    "Enabled": true
  }
}

Choosing a Value

  • Keep every check on. Articles are written by many people and read by everyone with access, so the policy is what keeps one bad paste from running in a reader's browser.
  • To let a link type through, add its scheme to UnsafeLinks.AllowedSchemes, for example msteams for Microsoft Teams links, as in the walkthrough above. Don't turn the UnsafeLinks check off.
  • To embed videos from another site, add its host name to Iframes.AllowedSites, for example music.yandex.ru. Don't turn the Iframes check off.
  • When an Article needs one more CSS property or element, add it to the matching Additional… list instead of turning a check off.

Frequently Asked Questions

Why did my embedded video disappear?

Its site is not in Iframes.AllowedSites. YouTube and Vimeo are allowed by default; add the plain host name of any other site.

Why did my Article lose markup after I saved it?

The editor shows the cleaned HTML, and saving stores it. The markup the policy removed is gone from the new revision; the earlier text is still in the Revision History.

Next Steps