SAML: Front End Login Example

SAML Authentication can be used to enforce front end login for restricted sites and content. This works if you have SAML configured for your domain and your subfolders, pages or files do not have CMS Anonymous = READ permissions and instead require other permissions to access.

Example Setup

In this example we will set up a new intranet site and users will need to belong to a custom Intranet Users role in order to access this site.

1. We create the new Intranet Users role, paying special care to what we use as the ROLE_KEY. We will need this ROLE_KEY in order to grant access to the site on successful login.
   
2. Create the new Intranet site.
   
3. Permission the new Intranet site. Once created you need to allow CMS Anonymous = READ permissions to the site, but do not add any inheritable permissions for CMS Anonymous. You should then add your Intranet Users role and grant that role READ to the site and all sub-assets. Granting CMS Anonymous Read on the site, but not on the underlying assets allows an anonymous request to access the site, but when any specific asset is requested, it forces the unauthenticated user into the authentication flow. Permissions on your intranet site should look something like this:

   CMS Anonymous Permissions

   

Intranet Users Permissions

Pages and files added under this site will automatically inherit these permissions, which means they will be visible to users with the Intranet Role but not visible/accessible anonymously.

FLOW

When an unauthenticated user requests a front end page or file that does not have CMS Anonymous = READ access, dotCMS will redirect that request to a virtual path, /dotCMS/login and include the requested page or file as the “referrer” parameter, e.g. /dotCMS/login?referrer=/index. The dotCMS SAML implementation listens to this virtual path, intercepts it, stores the referrer path in the user browser session and redirects the user to your IDP for authentication. Once you authenticate, your IDP returns the user to the /api/v1/dotsaml/login/{uuid} path to finish the login. This authenticates the user in dotCMS, reads the referrer and then redirects the user back to the path that was originally requested.

SAML Configuration

Configuring SAML for a front end site works the same as configuring it for a backend site - though it requires a few custom properties. You should proceed to connect to your IDP as described in the other SAML documentation but should add/consider the following properties:

• access.filter.values: This is a comma separated list of paths that are excluded from the SAML filter and will not invoke a SAML authentication redirect. We need to allow the /api so saml can make a successful callback without entering a redirect loop and we add /favicon.ico because browsers automcatially request that in the background and it can sometimes (race condition) become the “referrer” set in the user's session, which we never want.
• build.roles: This is a comma separated list of role KEYs that we want to add to the SAML user when they successfully authenticate. In this case, we are automatically adding our INTRANET USER role to our users so they can access the site and its content.
• include.path.values: this is a list of REGEX paths that we want to allow the SAML Filter to run on - any visit to these these paths that include SAML authetication parameters will automatically log the user in. Because we are enforcing SAML permissions site wide, we use the pattern .*. If you only wanted to enfore SAML on a folder, you would use something like /intranet* to match that folder path.
• role.extra: This defines how we want to add the roles found in build.roles. In this case, we want the role addition to be additive, adding the role to the user if it does not exist but leaving the existing user roles intact. See SAML Configuration for more information about the role.extra parameter.

You can see the values from a working example here:

Using SAML for both Front End and Back End Authentication

While the same SAML configuration can be used for both front end and backend logins, this can also be hard to configure your IDP to do this correctly. Another strategy is to separate your “admin” domain from your front end domain, meaning, access your administrative tools using a admin.dotcms.yourcompany.com and your users access the site/content at intranet.yourcompany.com. That way, each domain can use a separate, specific SAML configuration for each type of user.