Configuring Authentication for Authors

Enable Authentication for Authors

By default, authors don’t need to be logged in in order to use Franklin via Sidekick. In order to enable authentication, it is sufficient to add relevant access-statements to your site configuration. Upon encountering said access-statements, the Sidekick will enforce authentication with the respective provider: Microsoft for Sharepoint based projects, and Google for Google Drive based projects.

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 admin.role.author and or admin.role.publish 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: admin.role.publish = some.user@example.com
Example for a wildcard domain: admin.role.author = *@example.com

The following example would grant author access all users within the “example.com” domain and publish rights to a the single user “some.user@example.com”:

Ensure that the users are able to authenticate themselves using their login credentials as follows:

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.

Step 4: Login via Sidekick

The next time the Sidekick opens on a document, it will show a Sign In option:

Once you click it, it will open a new browser tab, redirecting to your respective provider:

The first time, it will ask for consent that the Franklin Admin service can access your sharepoint or google data. In case you are not admin on the account, you see a the following message:

In this case, ask an Active Directory admin of your organization to login via Sidekick or directly 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:

It should have the application id shown above.

Select the Permissions tab (below security):

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:

Using the Admin Service (admin.hlx.page)

When authentication is enabled for admin.hlx.page using the API endpoint with tools like curl will require to use a proper auth token. For one time ad-hoc use by developers it is very convenient to just copy/paste the x-auth-token header from your browser's network tab from an authenticated request sent by sidekick to admin.hlx.page and pass it into the curl via the -H option. eg:

curl -v -H "x-auth-token: id_token=..." "https://admin.hlx.page/status/[org]/[repo]/main/?editUrl=auto"

Define user roles without enforcing authentication

By default, as soon as the role mapping is defined via an admin.role.* entry, authentication is enforced on that project. It might be desirable to allow unauthenticated access but still be able to define a user mapping, for example give a user the admin role.

The requireAuth property can be used for this with the following values:

Example:

Give the user bob@example.com the admin role but don’t enforce authentication: