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:

• 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 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:

• If using Google Drive, they must be able to authenticate with their credentials using Google authentication.
• If using Microsoft SharePoint, they must be able to authenticate with their credentials using Microsoft authentication.

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.

Step 5: 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:

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:

• auto is the default and enforces authentication as soon as a role mapping is defined.
• true will always enforce authentication
• false will not enforce authentication

Example:

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

Default Roles

If no role mapping is configured, the admin uses default roles to determine the permissions of the request. The default role can be specified using the admin.defaultRole property.

By default there are no default roles, unless requireAuth is auto, in this case the default role is basic_publish (see below). Example:

Use publish as default role:

Evaluation

The effective roles of a request are evaluated as follows:

1. If a request isn’t authenticated and requireAuth is true, a 401 status code is returned.
2. If a request isn’t authenticated and requiredAuth is auto and role mapping is defined, a 401 status code is returned.
3. If a request isn’t authenticated the defaultRole is used.
4. If a request is authenticated and no role mapping is defined, or if requireAuth is false, the defaultRole is used.
5. If a request is authenticated and role mapping is defined and requireAuth is not false, the roles that match the user are used.
   1. If no mapping matches, the user will have no role; effectively always returning a 403 status code.
   2. If several mapping matches, the user will have a combined set of roles

Admin Permissions

Admin Roles