Configuring Authentication for Authors

Enable Authentication for Authors

By default, authors don’t need to be logged in in order to use AEM 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 Admin service can access your Sharepoint or Google data. In case you are not an admin on the account, you will see 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 organization’ when they log in, or later via the Azure Portal.

In order to grant admin consent, open the Azure portal and go to:
HomeActive DirectoryEnterprise 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 organization}.

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:

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 requireAuth 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

Permission Purpose
cache:write Purge cache
code:read Read code status
code:write Update code
code:delete Delete code
code:delete-forced Delete code (forced)
config:read Read all config
config:read-redacted Read redacted config
config:write Update config
index:read Read index matching
index:write Reindex
preview:read Read preview information
preview:write Update preview
preview:delete Delete preview resources
preview:delete-forced Delete preview resources (forced)
preview:list List preview resources
edit:read Read edit status
edit:list List edit resources
live:read Read live status
live:write Update live resources (publish)
live:delete Delete live resources
live:delete-forced Delete live resources (forced)
live:list List live resources
cron:read Read cron job config
cron:write Update cron job config
snapshot:read Read snapshots
snapshot:write Update snapshots
snapshot:delete Delete snapshots
job:read Read job information
job:write Start jobs
job:list List jobs
log:read Read logs
log:write Write logs (append)

Admin Roles

Role Permissions
admin
  • <all permissions>
basic_author
  • cache:write
  • code:read
  • code:write
  • code:delete
  • index:read
  • index:write
  • preview:read
  • preview:write
  • preview:delete
  • edit:read
  • live:read
  • cron:read
  • cron:write
  • snapshot:read
  • job:read
basic_publish
  • <basic_author>
  • live:write
  • live:delete
author
  • <basic_author>
  • edit:list
  • job:list
  • log:read
  • preview:list
  • preview:delete-forced
  • snapshot:delete
  • snapshot:write
  • job:write
publish
  • <author>
  • live:write
  • Live:delete
  • live:delete-forced
  • live:list
develop
  • <author>
  • code:write
  • code:delete
  • code:delete-forced
config
  • config:read-redacted
config_admin
  • <publish>
  • config:read
  • config:write

Configuration Service

If you have set up the Configuration Service for your site, then you can use the following API operations to configure permissions for authors:

In each of these API requests, you will use the fields