Server-side custom template permissions

This document outlines the permissions for server-side custom templates.

Each permission is:

  • Checked by APIs that require them.
  • Automatically detected in sandboxed JavaScript, based on what APIs are used. This happens as edits are made in the custom template editor (for a fast feedback loop), and when code is compiled (to validate that the correct permissions are enforced).
  • Editable in the custom template editor, to make the permission more specific.
  • Queryable in sandboxed JavaScript via the queryPermission API.

access_bigquery

Display name: Accesses BigQuery

Description: Allows access to BigQuery on Google Cloud Platform.

Configuration: Option to allow specified project, dataset, and table combinations to be used with BigQuery. Setting a project ID configuration of GOOGLE_CLOUD_PROJECT will allow using the GOOGLE_CLOUD_PROJECT environment variable as the project ID when projectId is excluded from the BigQuery API parameter.

Required by: BigQuery

Query signature: queryPermission('access_bigquery', <operation>, <options>)

Notes: <operation> is a string and can have the following values:

  • write

<options> is an object containing the following items:

{
  'projectId': <project_id>,
  'datasetId': <dataset_id>,
  'tableId': <table_id>
}

Example code

const BigQuery = require('BigQuery');
const queryPermission = require('queryPermission');

const connectionInfo = {
  'projectId': 'gcp-cloud-project-id',
  'datasetId': 'destination-dataset',
  'tableId': 'destination-table',
};

if (queryPermission('access_bigquery', 'write', connectionInfo)) {
  const rows = [{
    'column1': 'String1',
    'column2': 1234,
  }];
  const options = {
    'ignoreUnknownValues': true,
    'skipInvalidRows': false,
  };

  BigQuery.insert(connectionInfo, rows, options)
      .then(data.gtmOnSuccess, data.gtmOnFailure);
}

access_firestore

Display name: Accesses Google Firestore

Description: Allows access to Google Firestore.

Configuration: Option to allow specified project and path (wildcard syntax supported) combinations to be used with Firestore. Setting a project ID configuration of GOOGLE_CLOUD_PROJECT will allow using the GOOGLE_CLOUD_PROJECT environment variable as the project ID when projectId is excluded from the Firestore API parameter.

Required by: Firestore

Query signature: queryPermission('access_firestore', <operation>, <options>)

Notes: <operation> is a string and can have the following values:

  • read - Grants access to read and query APIs
  • write - Grants access to write API
  • read_write - Grants access to read, write, and query APIs

<options> is an object containing the following items:

{
  'projectId': <project_id>,
  'path': <path>
}

Example code

const Firestore = require('Firestore');
const queryPermission = require('queryPermission');

const options = {
  'projectId': 'gcp-cloud-project-id',
  'path': 'collection/document',
};

if (queryPermission('access_firestore', 'read', options)) {
  Firestore.read('collection/document', {
    projectId: 'gcp-cloud-project-id',
  }).then(data.gtmOnSuccess, data.gtmOnFailure);
}

access_response

Display name: Accesses response

Description: Accesses the response body, headers, or status.

Configuration: Option to allow any or specific access, with sub-options for controlling access to various subcomponents.

Required by: setPixelResponse, setResponseBody, setResponseHeader, setResponseStatus

Query signature: queryPermission('access_response', 'write', <component>[, <optional component name>])

Notes: Governs whether the outgoing HTTP response component can be accessed.

Example code

const queryPermission = require('queryPermission');
const setResponseBody = require('setResponseBody');
const setResponseHeader = require('setResponseHeader');
const setResponseStatus = require('setResponseStatus');
if (queryPermission('access_response', 'write', 'header', 'Content-Type')) {
  setResponseHeader('Content-Type', 'text/plain');
}
if (queryPermission('access_response', 'write', 'body')) {
  setResponseBody('Not Found');
}
if (queryPermission('access_response', 'write', 'status')) {
  setResponseStatus(404);
}

access_template_storage

Display name: Accesses Template Storage

Description: Allows access to temporary storage for templates that can persist for the lifetime of the server-side process.

Configuration: None

Required by: templateDataStorage

Query signature: queryPermission('access_template_storage')

Example code

const queryPermission = require('queryPermission');
const templateDataStorage = require('templateDataStorage');
const key = 'my_key';
if (queryPermission('access_template_storage')) {
  const value = templateDataStorage.getItemCopy(key);
}

get_cookies

Display name: Reads cookie value(s)

Description: Reads the values of the cookies with the specified name.

Configuration: List of names of cookies permitted for reading.

Required by: getCookieValues

Query signature: queryPermission('get_cookies', <name>)

Notes: Governs whether a cookie can be read, depending on its name.

Example code

const queryPermission = require('queryPermission');
const getCookieValues = require('getCookieValues');
const cookieName = 'info';
let cookieValues;
if (queryPermission('get_cookies', cookieName)) {
  cookieValues = getCookieValues(cookieName);
}

logging

Display name: Logs to console

Description: Logs to the developer console and Tag Manager's preview mode.

Configuration: Option to enable logging in production. Defaults to only enable logging in debug/preview. If permission is denied, logToConsole will not throw an error, but will suppress the log message.

Required by: logToConsole

Query signature: queryPermission('logging')

Notes: Controls whether a custom template can log to the developer console.

Example code

const queryPermission = require('queryPermission');
const logToConsole = require('logToConsole');
// Note that it's fine to call log, since the log call will be ignored if
// logging isn't permitted in the current environment.
logToConsole('diagnostic info');

use_message

Display name: Uses messages

Description: Sends or receives messages using the addMessageListener or sendMessage APIs.

Configuration: Option to specify the message type and whether the template can listen, send, or both.

Required by: addMessageListener, sendMessage

Query signature: queryPermission('use_message', <usage>, <message type>)

Notes: Usage can be one of listen, send, or listen_and_send.

Example code

const queryPermission = require('queryPermission');
const sendMessage = require('sendMessage');
if (queryPermission('use_message', 'send', 'set_cookie')) {
  sendMessage('set_cookie', {name: 'foo', value: 'bar'});
}

read_container_data

Display name: Reads container data

Description: Reads data about the container.

Configuration: None.

Required by: getClientName, getContainerVersion

Query signature: queryPermission('read_container_data')

Notes: Controls whether a custom template can read container data.

Example code

const getContainerVersion = require('getContainerVersion');
const queryPermission = require('queryPermission');
if (queryPermission('read_container_data')) {
  return getContainerVersion();
}

read_event_data

Display name: Reads event data

Description: Reads data from the event.

Configuration: Option to allow any access, or specific access controlled by a list of allowed key paths (wildcard syntax supported).

Required by: getAllEventData, getEventData

Query signature: queryPermission('read_event_data'[, <optional key>])

Notes: Controls whether a custom template can read event data at a given key path (or all the event data, if no key path is given).

Example code

const getAllEventData = require('getAllEventData');
const queryPermission = require('queryPermission');
if (queryPermission('read_event_data')) {
  return getAllEventData();
}

const getEventData = require('getEventData');
const queryPermission = require('queryPermission');
const keyPath = 'parentField.childField';
if (queryPermission('read_event_data', keyPath)) {
  return getEventData(keyPath);
}

read_event_metadata

Display name: Reads event metadata

Description: Reads event metadata in Event Callbacks

Configuration: None

Required by: addEventCallback

Query signature: queryPermission('read_event_metadata')

Notes: Controls whether a custom template can read event metadata in callbacks.

Example code

const queryPermission = require('queryPermission');
const addEventCallback = require('addEventCallback');
if (queryPermission('read_event_metadata')) {
  addEventCallback((containerId, eventMetadata) => {
    // Read event metadata.
  });
}

read_request

Display name: Reads HTTP request

Description: Reads the request headers, query parameters, body, path, or remote IP address.

Configuration: Option to allow any or specific access, with sub-options for controlling access to various subcomponents.

Required by: extractEventsFromMpv1, extractEventsFromMpv2, getRemoteAddress, getRequestBody, getRequestHeader, getRequestPath, getRequestQueryParameter, getRequestQueryParameters, getRequestQueryString

Query signature: queryPermission('read_request', <component>[, <optional component name>])

Notes: Governs whether the incoming HTTP response component can be accessed.

Example code

const queryPermission = require('queryPermission');
const getRequestBody = require('getRequestBody');
const getRequestHeader = require('getRequestHeader');
let body, contentType;
if (queryPermission('read_request', 'body')) {
  body = getRequestBody();
}
if (queryPermission('read_request', 'header', 'content-type')) {
  contentType = getRequestHeader('content-type');
}
if (body && contentType == 'application/json') { ... }

return_response

Display name: Returns response

Description: Returns response to the caller.

Configuration: None

Required by: returnResponse

Query signature: queryPermission('return_response')

Notes: This permission has no fields to narrow, and is typically not queried for.

run_container

Display name: Runs the container

Description: Runs the container with an event

Configuration: None

Required by: runContainer

Query signature: queryPermission('run_container')

Notes: This permission has no fields to narrow, and is typically not queried for.

send_http

Display name: Sends HTTP requests

Description: Sends an HTTP request to a specified URL.

Required by: getGoogleScript, sendEventToGoogleAnalytics, sendHttpGet, sendHttpRequest

Query signature: queryPermission('send_http', <url>)

Notes: Governs whether an HTTP request can be made, depending on the URL. To ensure a secure connection, only secure (HTTPS) URLs are permitted.

Example code

const queryPermission = require('queryPermission');
const sendHttpGet = require('sendHttpGet');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_http', url)) {
  sendHttpGet(url);
}

send_pixel_from_browser

Display name: Sends pixels from browsers

Description: Sends a GET request to a specified URL from the browser.

Required by: sendPixelFromBrowser

Query signature: queryPermission('send_pixel_from_browser', <url>)

Notes: Governs whether a request can be sent from the browser, depending on the URL.

Example code

const queryPermission = require('queryPermission');
const sendPixelFromBrowser = require('sendPixelFromBrowser');
const url = 'https://example.com/search?query=foo&results=10';
if (queryPermission('send_pixel_from_browser', url)) {
  sendPixelFromBrowser(url);
}

set_cookies

Display name: Sets a cookie

Description: Sets a cookie with the specified name and parameters.

Configuration: A table of allowed cookie names, each with optional restrictions on name, domain, path, secure attribute, and expiration.

Required by: setCookie

Query signature: queryPermission('set_cookies', <name>, <options>)

Notes: Governs whether a given 'Set-Cookie' header can be added to the response, depending on the cookie name, domain, path, secure attribute, and expiration.

Example code

const queryPermission = require('queryPermission');
const setCookie = require('setCookie');
const options = {
  'domain': 'www.example.com',
  'path': '/',
  'max-age': 60*60*24*365,
  'secure': true
};
if (queryPermission('set_cookies', 'info', options)) {
  setCookie('info', 'xyz', options);
}

use_custom_private_keys

Display name: Uses custom private keys

Description: Uses private keys from a JSON key file for cryptographic operations.

Configuration: A list of allowed key IDs. The IDs must match the keys in the JSON key file referenced by the SGTM_CREDENTIALS environment variable on the server.

Required by: hmacSha256

Query signature: queryPermission('use_custom_private_keys', <key id>)

Notes: Governs the list of allowed private keys.

Example code

const hmacSha256= require('hmacSha256');
const queryPermission = require('queryPermission');
const keyId = 'key1';

let result;
if (queryPermission('use_custom_private_keys', keyId)) {
  result = hmacSha256('my_data', keyId);
}

use_google_credentials

Display name: Uses Google Application Default Credentials

Description: Uses the Google default credentials to make calls to Google APIs.

Configuration: A list of allowed Google OAuth 2.0 scopes.

Required by: getGoogleAuth

Query signature: queryPermission('use_google_credentials', <scopes>)

Notes: Restricts the allowed Google OAuth 2.0 scopes for use with Google APIs.

Example code

const getGoogleAuth = require('getGoogleAuth');
const queryPermission = require('queryPermission');

const scopes = [
  'https://www.googleapis.com/auth/datastore'
];

let auth;
if (queryPermission('use_google_credentials', scopes)) {
  auth = getGoogleAuth(scopes);
}