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

• Only authentication is supported. Authorization is not yet supported.
• Authentication can only be enabled or disabled for the entire site
• It is not possible to create a custom error page for denied access after login

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:

• In your site’s root folder create a folder named .helix
• Go to the folder named .helix
• Create a new spreadsheet with name:
  • On sharepoint: config.xlsx
  • On GDrive: config
• Name the first column header key
• Name the second column header value

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.

Step 4: Granting Admin Consent via 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

• Q: I have published the configuration limiting access to my site, but I can still see the index page without login, whereas sub-paths are protected.
  A: This is most likely a caching issue. You can resolve it by publishing the index document (e.g. index.docx) again.

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.

Limiting access to repositories

Franklin allows development from forked repositories that point to the same content. This results in the ability to access the same content via different URLs. For example a site that has its primary repository at example/website can be accessed using https://main--website--example.hlx.page. Assuming a developer forks the repository to developer/ex-web, and keeping the same fstab.yaml, the same content can be accessed via https://main--ex-web--developer.hlx.page. This might be fine or even desirable during development. But once production content is published, it might be undesirable that the same content can be accessed using a different url (and potentially different website code).

In order to restrict which urls can be used to access the content, add a access.require.repository to your /.helix/config.xlsx. For example:

would only allow access via the https://main--website--example.hlx.page and https://main--website--example.hlx.live urls.