style
content

Configuring Site Authentication

AEM Live supports token-based authentication. Site authentication is usually applied to both the preview and publish sites, but can also be configured to only protect either site individually.

Warning

Enabling Site Authentication for the publish sites (*.aem.live) will enforce authentication for all your site visitors (intranet). It will also prevent automatic PSI (Page Speed Insights) checks from running on your pull requests in GitHub. For use cases where your BYO CDN should use no (or different) authentication from your .live origin, you will need to configure preview only authentication or bypass authentication with an API_KEY.

Limitations

Enable Authentication for the Preview and Publish Sites

Click here to view instructions on how to update the configuration in document mode

1. Enable the Configuration Service

All of the following instructions use the Configuration Service for your site, so follow the linked instructions to enable and authenticate, then perform the following API requests.

2. Create a site token to access your protected site

POST an empty body to http://admin.hlx.page/config/{org}/sites/{site}/secrets.json the response will be a JSON object containing an id and value field. Remember both, you'll need them for the next steps:

curl -X POST https://admin.hlx.page/config/acme/sites/website/secrets.json \
  -H 'x-auth-token: <your-auth-token>'
{
  "id": "SGFsbG8gVG9iaWFz",
  "value": "hlx_ZGFzIGlzdCBkZWluIHRva2Vu",
  "created": "2024-08-21T18:28:54.075Z"
}

Note that you now have two tokens:

  1. The auth token for the admin API obtained during login. This one is highly sensitive and cannot be used for site authentication.
  2. The site token, which you just created, which can be shared with users and systems than need to access your site

3. Enable the token to access your site

POST to http://admin.hlx.page/config/{org}/sites/{site}/access/site.json so that accessing your site on aem.page and aem.live requires the token value you've retrieved in the previous step.

curl -X POST https://admin.hlx.page/config/acme/sites/website/access/site.json \
  -H 'content-type: application/json' \
  -H 'x-auth-token: <your-auth-token>' \
  --data '{
    "allow": ["*@acme.com", "*@adobe.com"]
    "secretId": ["SGFsbG8gVG9iaWFz"]
  }'

{
  "allow": ["*@acme.com", "*@adobe.com"]
  "secretId": ["SGFsbG8gVG9iaWFz"]
}

The response contains the content of the access.site object. Each POST request overwrites that object, so if you want to update any content, make sure to perform a GET request to the same URL before and include the original content.

The example above sets the site property which controls access to both aem.page and aem.live. This is the most restrictive approach. If you want to limit access to both aem.page and aem.live, POST to .../access/site.json. If you want to limit access to aem.page only, post to .../access/preview.json. In the unlikely case that you want to limit access to aem.live only, and keep aem.page, post to .../access/live.json.

If you have set tokens for site and either preview or live, then preview and live will override the site-wide settings.

4. Verify that access has been limited

When you open your site in your browser, you will see an HTTP 401 status code, indicating that no access is possible without authentication. Next, try to access the site and provide the token value:

curl https://main--website--acme.aem.live \
  -H 'authorization: token hlx_ZGFzIGlzdCBkZWluIHRva2Vu'

In this request we use the site token value in the Authorization header.

5. Make your CDN pass the right Authorization header

With this change, nobody can access your site without the correct authorization header. This includes your CDN, and therefore every visitor to your site. To enable access again, you need to add the Authorization header to each origin request your CDN makes.

The CDN setup instructions explain how to enable the authorization header for each supported Content Delivery Network.

Browser Access to the Protected Sites

Accessing protected sites directly from a browser requires users to have an appropriate role defined in the project configuration and to sign in using the AEM Sidekick Extension.

Example

The following excerpt of the access object of a site configuration for acme/website enforces the following:

{
 "access": {
   "preview": {
     "allow": [
       "*@acme.com"
     ],
     "secretId": [
       "SGFsbG8gVG9iaWFz",
     ]
   },
   "admin": {
     "role": {
       "publish": [
         "*@acme.com"
       ]
     },
     "requireAuth": "true",
     "apiKeyId": [
       "1kLvEvoipnINAOGDP8NVl3IYbJy2qmUQa5b1Fe23S7tt"
     ]
   }
 }
}