Versions Compared

Old Version 6

changes.mady.by.user Jeff Pierce

Saved on

compared with

New Version Current

changes.mady.by.user Smita Nair

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Warning

...

Removal notice:

The URL user and URL user password parameters were removed in 5.8.5 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.

In general, the configuration settings affect how certain parameters of the app's macros work.

After installing HTML for Confluence, navigate to the HTML for Confluence Configuration screen:

  1. Log in with the System Administrator's global permission.

  2. Select Image Added > Manage apps.

  3. Either search for HTML for Confluence or scroll to Bob Swift Configuration, and click HTML to view app configuration.

Tip

Try this for older Confluence versions

  1. Navigate to Image Added >Settings > Atlassian Marketplace on the sidebar.

  2. Scroll to Bob Swift Configuration and click HTML to view the configuration page.

The following configuration tabs are available:

Anchor
html_57_config_global
html_57_config_global
Global Configuration

Use the toggles to enable or disable the Global Configuration settings.

...

The parameters to be set are as follows:

Parameter

Default

Description

Disable secure processing

Off

Enable this option to allow XSLT macro to use all XSLT features including

external entity resolution.Restrict URL accessNot selected (default)With version 5.3.0, a new configuration parameter, Restrict URL access is available. This parameter controls whether or not the url parameter on the HTML for Confluence macro must conform to the Confluence Whitelist provided whitelisting is enabled.

substituting XML entity references with their actual values. This helps to control secure XSL processing. By default, this option is disabled. Available since version 5.1.0.

Restrict URL access

Off

Enable this option to restrict access to remote locations through the Location parameters in the Html-bobswift and XSLT macros. The specified URLs in the macro editors must conform to the Confluence Whitelist; provided, whitelisting is enabled. Available since version 5.3.0.

Confluence allows the administrator to turn on whitelisting to restrict incoming and outgoing connections to only those connections that are configured in the Whitelist settings. If enabled, the URL parameter of the HTML for Confluence macros is also restricted to the URLs that are configured in the Whitelist settings for Confluence only.

Important!

There is a known issue encountered on Confluence 8.7 and above. If this option is disabled and the Confluence whitelist is enabled, the URL content cannot be accessed. Administrators must enable the Dnet.request.allow.all.hosts=true in <yourConfluenceInstance>/bin/setenv.sh to resolve the issue.

Allow JavaScript

On

Enable this option to use Javascript in the HTML for Confluence macros. If enabled, the usage of Javascript in the macros is not restricted and thus, users must be advised about the potential security issues if this feature is not used correctly. If disabled, this option to prevent users from using JavaScript in the HTML for Confluence macros. Available since version 5.4.0.

Note

You can also control Javascript usage on pages that are using the HTML for Confluence macros by enabling the relevant entries in the Macro Security for Confluence Configuration page.

By enabling this option the url parameter for the HTML for Confluence macro is also restricted to only URLs that are configured in the Whitelist settings for Confluence

Refer toMacro Security Configuration to understand how to enable macros and the Macro Security section for information specific to HTML for Confluence macros.

Blacklist domains

Off

Enable this option to blacklist certain domains. By default, this option is disabled for backward compatibility. Available since version 5.6.0.

If enabled, and if a request from any of these sites is received, an error message is displayed. However, if users still need to access a blacklisted site, they must contact their administrator to disable this option. 

Note

If this option is disabled, access to all domains is permitted!

Click the link named listed (in the description beneath the option) to view a pre-defined list of the most commonly blacklisted domains in a pop-up window. The following sites are blacklisted:

  • 10.0.0.0/8

  • 100.64.0.0/10

  • 127.0.0.0/8

  • 169.254.0.0/16

  • 172.16.0.0/12

  • 192.168.0.0/16

  • 192.0.0.0/24

  • 198.18.0.0/15

  • 255.255.255.255/32

  • 0.0.0.0/32

  • 192.0.2.0/24

  • 192.88.99.0/24

  • 198.51.100.0/24

  • 203.0.113.0/24

  • 224.0.0.0/4

  • 240.0.0.0/4

Blacklist domain values

Pre-defined set of domains

Enter a comma separated list of domains to be blacklisted. This field is enabled only if the Blacklist domains parameter is enabled.

Domains can be added, updated or deleted from the pre-defined entries that are given in the listed link of the Blacklist domains parameter. Available since version 5.8.0. 

Note

If the Blacklist domains parameter is enabled and this text area is left blank, the macros intrinsically reverts back to the pre-defined values (given in the listed link of Blacklist domains) as blacklisted domains. Thus, access to the pre-defined domains is restricted once the Blacklist domains parameter is enabled.

Anchor
html_57_config_macroSecurity
html_57_config_macroSecurity
Apply restrictions through Macro Security for Confluence

Since release 5.7.0, the HTML macro name has changed from HTML to Html-bobswift to comply with Atlassian requirements. Existing pages that use the HTML macro name with the Macro Security macro are unaffected, and for any new macro additions to render HTML content, specify the same HTML configurations for the Html-bobswift macro name as given for the HTML macro. In such cases, parameters for both, HTML and Html-bobswift, macro names must be added in Macro Security for Confluence Configuration to render the HTML content on the pages correctly. Any entries made for the XSLT macro remain unaffected and hence, the entries made for this macro can be retained as-is in the Macro Security configuration. The macro parameters that must be specified in Macro Security for Confluence Configuration for any of the HTML for Confluence app macros are as follows:

For HTML macro:

  • Key: html
    Value: *ANY

  • Key: html.allowJavascript
    Value: *ANY

  • Key: html.profile.*
    Value: *ANY

For XSLT macro:

  • Key: xslt.profile.*
    Value: *ANY

  • Key: xslt
    Value: *ANY

As an administrator, you must manually add the following entries for the Html-bobswift macro name in Macro Security for Confluence Configuration > Secured macros:

For Html-bobswift macro:

  • Key: html-bobswift.profile.*
    Value: *ANY

  • Key: html-bobswift
    Value: *ANY

  • Key: html-bobswift.allowJavascript
    Value: *ANY

If any of these entries are not available in Macro Security for Confluence Configuration, a user gets an error message, "Security restricted macro with parameter 'profile' is not allowed. An edit restriction is required that matches the macro authorization list.". 

Anchor
html_57_config_profiles
html_57_config_profiles
Profiles

Profiles are a common set of parameters used to access content from external locations. Available since 5.7.0. 

Use profiles to:

  • Allow user authentication as required by some URLs to be hidden from page viewers and editors. Only Confluence administrators have access to this information.

  • Enable macro editors to quickly configure the macro by reusing a shared definition for URL access. 

  • Make lesser changes to page contents when base URLs are relocated as relative addressing is used in profiles. 

  • Macro configured URL (that is not a full URL) is appended to the profile provided URL. This absolute URL then points to the actual location of the content to be rendered.

Note

The base URL of the remote location to be accessed must be given in profiles, and the raw URL must be entered in the Location of HTML data or Location of XML data fields in the respective macros' editors. 

A raw URL is defined as the part of the URL following the domain information and includes the query string, if present. For example, in the URL string http://www.contoso.com/articles/recent.aspx, the raw URL is /articles/recent.aspx.

...

The page displays a list of profiles available for the macros. You can perform the following actions on this page:

  • Click (blue star) to edit the profile details.

  • Click Image Added to remove the profile.

To create a new profile, click Add Profile to open a pop-up window as:

...

Parameter

Description

Profile name

Enter a name for the profile. Profile names given here are populated in the Profile field in the macro editors.

Note

This name must be unique; else, the details specified overwrites the details of the existing profile. This may cause errors in pages where the profile is used.

Profile type

Specify whether this is a URL, GitLab, or GitHub address. The default option for this parameter is URL.

URL

Enter the URL of the remote location to be accessed. It is recommended to provide the base URL here. 

Note

A raw URL must be provided in Location of HTML data and Location of XML data in the respective macros' editors.

If the Profile type is either GitLab or GitHub, a default URL is displayed here that is editable.

User; Password

Enter the username and password, if required, to access the specified URL. 

Note

Specify either the User and Password parameters or the Access token, as an access token is also a means of user authentication. It is recommended to use either of the user authentication methods but not both.

Access token

Enter an access token or an API token for the application or service to be connected with. 

Note

If this parameter is specified, ensure that the User and Password parameters are left empty. It is recommended to use either of the user authentication methods but not both.

Each application has its own method of generating tokens. Access tokens or API tokens are a means of user authentication; so, if mentioned, this token is used for authentication instead of using user credentials.

  • Tokens are generated for a user after the application or service to be connected verifies the user's credentials. 

  • Enter the generated token here for a seamless connection between the app's macros and the application or service.

Here are some of the links associated with GitLab and GitHub applications to generate a personal access token:

URL parameters

Mention any extra parameters (for the query string) that must be appended to the specified URL here. 

Request headers

Displays the request headers created as per the given information. Request headers are name or value pairs that are added to the request. For example, GitHub requires the following request headers be specified: Authorization: token $accessToken, Accept:application/vnd.github.v3.raw

This field is automatically populated with a comma-separated list of name or value pairs using the provided information. If required, enter additional name or value pairs separated with commas.

Click Save profile to create the profile.

Anchor
html_58_config_migrate
html_58_config_migrate
Migrate to Confluence Cloud

Administrators trying to migrate from server/data center to cloud are encouraged to read the Pre-migration guide. The Pre-migration guide explains in detail what administrators have lookout for before starting the migration process. Once the pre-migration is completed, read the Migration guide to understand how the app can be migrated with little to no errors.

The Help us improve the product parameter was removed. We do not collect or transmit private user data or personally identifiable information. Refer to the Appfire Trust Center for EULA and other policies.