How Access Tokens Work in PageBuilder

Starting with the 2.4 release, PageBuilder Engine supports authenticating requests to the Arc APIs using access tokens. This is now the preferred means of authenticating requests to Arc content sources.

Why use access tokens instead of basic auth?

Using access tokens in PageBuilder Engine offers you several key security benefits over the previous Basic Auth implementation:

• Individualized - For local development, each developer provisions their own access token (see Accessing The Arc XP APIs rather than sharing one credential across a team. When deploying code in PageBuilder, special access tokens are generated on a per-deployment basis. Taken together, this eliminates the need to pass credentials around between users.
• Revokable - Unlike the Basic Auth implementation, access tokens can be easily revoked and rotated once they are no longer in use. This will happen automatically in the PageBuilder Deployer.
• Scope-limited - The tokens generated by the PageBuilder deployer have read-only access to the Arc APIs, and cannot be used to destroy user data in Arc, should they fall into malicious hands.
• Environment-limited - Access tokens are also scoped to specific environment (for example, sandbox or production) and cannot be used across environments.

For these reasons, we recommend you use access tokens going forward in your PageBuilder Fusion deployments.

How are access tokens used in PageBuilder Engine?

PageBuilder Engine leverages access tokens in two key ways.

Engine Support

Starting with 2.4, the PageBuilder Engine now supports an additional environment variable ARC_ACCESS_TOKEN that works in conjunction with the previously-existing CONTENT_BASE variable.

ARC_ACCESS_TOKEN: This variable is used to store the current ARC_ACCESS_TOKEN. In deployed bundles, it will be automatically populated and changed with each new deployment. In local development, users should set it manually in their .env file.

CONTENT_BASE: This variable represents a common base domain to use for multiple content sources. It used automatically in resolve content sources.

When ARC_ACCESS_TOKEN is set and CONTENT_BASE points to your organization’s *.arcpublishing.com domain, requests from resolve() content sources will have the access token automatically injected into the Authorization header. Any Basic Auth credentials will also be stripped out.

Note that this will not happen from requests made in fetch() content sources. For these requests, you will need to manually retrieve the ARC_ACCESS_TOKEN environment variables and Attach It To Your Requests As A Bearer Token. Be careful only to use this for requests to Arc content sources!

Deployer Support

Starting with the 2.4 release, the PageBuilder Deployer automates the process of provisioning and revoking tokens for you so that you don’t have to.

1. A special PageBuilder access token (see below) is provisioned each time you create a deployment. This access token is injected into your bundle and assigned to the ARC_ACCESS_TOKEN variable, overwriting any previous value set for this variable.
2. When a deployment is removed, that deployment’s token is automatically revoked by the deployer.

How are PageBuilder access tokens different from the tokens manually created in Developer Center?

The access tokens generated by the deployer are considered to be PageBuilder access tokens. PageBuilder access tokens are similar to the read-only access tokens you can create in Developer Center, but they differ in one important respect:

Important

PageBuilder access tokens do not appear in Developer Center, and cannot be manually revoked in any Arc UI or public API. Only the PageBuilder Deployer can revoke these tokens.

This is done to prevent users from accidentally breaking your entire website. If you desire to rotate your website’s PageBuilder access token, you can simply create a new deployment with the same bundle and promote it.

PageBuilder access tokens are counted against your organization’s access token limit.

Can I configure the deployer to provision access tokens for an environment other than the one where the PageBuilder is hosted?

Some organizations map PageBuilder content sources to different environments. For example, it can useful to develop PageBuilder features in sandbox against data from a production Content API.

This can be enabled only by a manual configuration change made by the PageBuilder team. If you need this functionality, please file a ticket with Arc Client Support.