Preview vs. Live

dotCMS requires authorization to access content and pages stored in dotCMS which have not been published, or which do not have permissions to be viewed by anonymous users.

When accessing content using the REST API, you may control access to Live (published) and Working (draft/unpublished) content in several different ways.

Front-end and Back-end Users

For content which requires authorization, dotCMS has the concept of Front End users and Back End users. Front End users can only see live/published content. Back end users can preview draft/unpublished content.

In addition to the limits applied based on Front-end and Back-end user configuration, access to specific content is controlled by the user's Permissions on individual content:

• The user must have appropriate permissions (View, Edit, Publish, etc.) based on the operation to be performed (read, write, publish, etc.).
• Access also always includes the ability to read content for which the CMS Anonymous user has been given View access.

A user is configured to be a Front End user or Back End user by setting a property (a checkbox) in the user's account.

Authentication Stragies

When using the REST API, there are a number of strategies you can use to set up preview environments (where unpublished content can be viewed) and live environments (where only published content can be accessed).

You may authenticate REST API users in one of four ways:

• Using an API Key:
  • Send a dotCMS API Key from the Client
  • Append a dotCMS API Key at the proxy layer
• Pre-Authenticate the User
  • Using dotCMS Authentication
  • Using 3rd Party Authentication

dotCMS requires an API key to access content and pages stored in dotCMS using the REST API. These dotCMS API keys can be generated from the command line or from the backend of dotCMS from the User Manager screen. In dotCMS, an API key grants the permissions of the user to which they are issued, including permissions tied to any roles that the user might have. All content and API calls are permission-based and will return differently based on the key's user permissions.

Front-end and Back-end API Keys

When using an API Key to authenticate REST API calls, the API Key inherits all permissions of the user the API Key was generated for, including both Front-end/Back-end access and the Permissions the user has to specific content.

This means that you may create your own preview and live environments by using API Keys which are assigned to Back-end users and Front-end users, respectively.

Live/Published Content: Client Side Key

For publically accessable and read only sites, an API key can be generated for a “Front-End” user and embedded in an app or SPA that is used to make the API requests. While the embedded API key would be discoverable by a snooping web developer, it only grants read access to public content and is not unlike anonymous read access on any web property.

Previewing Content: Client Side Key

If your content is not sensitive and your preview environment is only accessable by trusted users, the same strategy can be used to create a “Preview” user key in dotCMS. To do this, you create a limited “Back-End” user in dotCMS and with them generate an api key or .env file for your preview environment. While this back-end api key is easy to use, it has the significant downside that it will also be discoverable by anyone who can access your preview environment. That said, the risks of this approach might be acceptable if simplicity is important, the content is not overly sensitive and the keys' permissions are limited only to reads and/or specific pages or content types.

Previewing Content: An API Key Facade

It is possible to use your ingress/proxy layer and append an api key as a header to incoming requests. This approach effectivly hides the API key from users and avoids having to embed the API key in an SPA or client side code. dotCMS has a demonstration OSGi plugin that can be used for this purpose to transparently append an API key to incoming requests, allowing for selective access to specific apis without exposing the api key publicly. It can be configured to grant access to only a subset of API endpoints.

Pre-Authorization

dotCMS Authentication

The authentication REST API (/api/v1/authentication) can be used to authenticate users before they access any content using other REST API calls. When a user is pre-authenticated with the authentication API, a cookie is set in the users' browser, which is then used to authenticate further dotCMS API calls. The user's browser passes this cookie with each API request, giving all subsequent API calls from the browser the appropriate Permissions for that user.

curl 'https://demo.dotcms.com/api/v1/authentication' -v -H 'Content-Type: application/json' --data-binary ' 
   {
     "userId":"joe@dotcms.com",
     "password":"joe",
     "rememberMe":true,
     "language":"en",
     "country":"US"
   }
' 

3rd Party Authentication

dotCMS can also integrate with 3rd party authentication mechanisms such as OAUTH, SAML or AD (Active Directory).

When an unauthenticaed user accesses the preview site, they are redirected to the 3rd party authentication mechinism. Once authenticated there, they are returned to your app with a token or a cookie they can pass to dotCMS, which will validate the token against the 3rd party and map the newly authenticated user to a user in dotCMS.

For more information on 3rd party authentication, please see the OAuth plugin and SAML plugin.