Configuring Site Authentication

Franklin supports out-of-the-box authentication using the Microsoft Identity Provider (IDP) and Microsoft accounts. Your Franklin site acts as an application to which the administrator of your Microsoft organization will need to grant access. Site authentication is usually applied to the preview and publish sites, but can also be configured to only protect the sites individually.

Warning

Enabling Site Authentication for the publish sites (*.hlx.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..

If you use authentication, your BYO (production) CDN must not use (disable) caching, otherwise authentication is gradually circumvented.

Limitations

Enable Authentication for the Preview and Publish Sites

In order to enable authentication, it is sufficient to add relevant access-statements to your site configuration. Upon encountering said access-statements, Franklin will automatically configure your site to redirect to the Microsoft IDP for authentication.

Step 1: Create Configuration

If not present already, create your site configuration file:

Step 2: Add Access Allow To Configuration

Open your site configuration file, located in your site root folder: .helix/config.xslx (on Sharepoint) or .helix/config (on GDrive).

Add access.allow key/value pairs as rows to your configuration sheet for each individual user or wildcard-domain you’d like to give access to the site for.

Example for an individual user: access.allow = some.user@adobe.com

Example for a wildcard domain: access.allow = *@adobe.com

The following example would grant access to the site for all users within the “example.com” domain and the single user “some.user@adobe.com”:

Step 3: Activate Your Configuration

If you haven’t done so already, install the Sidekick Extension.

With the site configuration sheet still open, click the Sidekick’s “Preview Button”:

This will copy your site configuration to both the preview and live stages of Franklin, since configuration values are treated global. Authentication, by virtue of the access.allow statements you added in the previous step, should now be automatically enabled on your site.

Go to your site’s preview URL (https://main–<repo>--<owner>.hlx.page) or live URL (https://main–<repo>--<owner>.hlx.live). You should be redirected to the Microsoft Sign In page:

Sign in with a user covered by the access.allow statements.

If this is the first time this Franklin site is used in conjunction with a Microsoft Login for your account or domain, the IDP will ask to give permissions to the Franklin Application. Depending on your setup, an administrator may need to grant those permissions. (see step 4: granting admin consent)

After login, you should be redirected to and see your site.

Incase you are not the admin on the account, you see the following message:

In this case, ask an Active Directory admin of your organization to login via the admin link: https://admin.hlx.page/auth/microsoft

They should see the following:

The admin can either grant consent directly by checking the ‘Consent on behalf of your organisation’ when they log in, or later via the Azure Portal.

In order to grant admin consent, open the azure portal and go to:
Home -> Active Directory -> Enterprise Application s

Search for the Franklin Admin:

And click on Grant admin consent for {your organisation}.

After clicking Accept you can refresh the Permissions blade a few times, until the consented permissions show up:

Now, the non admin user should be able to login.

FAQ

Enable Authentication only for the Preview Site

It is possible to configure the access controls differently for the preview (*.hlx.page) and publish (*.hlx.live) sites by only applying the allow configuration property to one site. For example:

Or you could also grant different users access to the respective sites:

Accessing protected sites with an API_KEY

It is possible to obtain an API_KEY to access a protected site without the need to login.

The key needs to be passed to the protected site via the authorization header. For example

curl -H "authorization: token $API_KEY" \
  https://main--helix-website--adobe.hlx.page

In order to let the system trust your key, its API_KEY_ID needs to be configured on the project as well through the access.apiKeyId property.:

Note: It is possible to configure more than one key, by just adding another row.

You can simply remove the apiKeyId again from the configuration if you no longer need or trust the respective APY_KEY.

Note: It is currently not possible to generate an api key self serviced. Please contact your Adobe Project Lead to generate one for your project if needed.