Toggle menu


Site user authentication, that is, confirming the identity of the people using your site and (perhaps) letting them see secure content, is something you need to get right. Not only are you potentially allowing users to see content and carry out tasks linked to a named account, you are also likely to end up storing data about those users, which could be subject to data protection legislation.

The authentication process involves several elements, including the Authentication template, forms to handle user registration and user profile updates, iCM website groups and users, and the Authentication worker described below.

Authentication Providers

A provider is a named service that will authenticate a user. A provider will always be of one of the supported types. A provider can have any name you choose, although in most cases we recommend calling your LinkedIn provider "LinkedIn", your Google provider "Google" etc, to avoid confusion.

Before you can set up a provider you will need information from the provider you'd like to use. This will mean creating developer accounts for providers like Facebook and Google so you can generate the app/client secret keys, and, in the case of SAML or MyGovScot providers, a combination of certificates, metadata and other files.

Authentication Types

All authentication providers have a type. You can think of the various types as the underlying definition of your provider. You can configure multiple providers of the same type. For example, you might have two subsites, each of which wants to use Facebook to provide authentication. You could configure two different Facebook providers (linked to different accounts with different secret keys etc), but they are both of the Facebook type.


When a user chooses to authenticate using an external provider, they will have to give their consent for some of their data to be passed back to iCM/your website. These consent messages are configurable per provider. The behaviour of the login process if a user refuses consent is explained in the Base Provider documentation below.

Site Users

When a user authenticates via an external provider, or completes your website Registration form, a local iCM site user is created for them. This user is known as an account user. The account user has a user profile populated by details passed back from the external provider (or entered into your site's registration form for user registering directly with your site).

Account Users

Account users uniquely identify a user and hold information about them. Account users have a unique username - although this is not the username used to log in with. Account users have user profiles, are recorded in the platform's history service when interacting with forms and workflows, and are assigned tasks during workflow processes.

Account users also hold information about the subsite zones the user is able to access. When a user registers with a subsite, or successfully logs in using a third party provider, they are given access to the zone the subsite is in.

Login Users

Account users can have one or more login users associated with them. Login users provide the methods account users log in with. Users can add and remove login users from their account using the My Account template, and link new login users to an existing account on login. The types of login user present in your site will match the login types set up and enabled in the Authentication worker and template. 

Site User Groups

When a user is created, they will automatically added to a user group named after the provider that created the user, using the providerName set in the configuration of that provider (apart from the iCMSiteUser which always puts users in a group called ICMSITEUSER). Users can also be added to other groups when they log in, which are set in the article extras of the Authentication template.

User Data

As explained above, using an external provider may result in user data from that provider being passed back to the Authentication worker and stored against a user in their user profile. The data that each external provider sends back is listed in the type specific documentation below.

OAuth Worker

The Authentication worker manages people logging into your site. It should not be confused with the OAuth worker, which allows the platform to act as an authentication provider to other systems.

Worker Configuration Properties

The properties of the worker, including user profile mapping, session expiration, error page URLs and the array of the providers themselves.

Provider Types

These articles describe the base provider parameters and setting up providers of each of the supported types.

Linking Providers, Account and Profile Management

Users may be prompted to add a new provider to their existing account when they log in. Login providers can also added to or removed from existing accounts when the Authentication worker is in account management mode.

Handlebars Templates

The Authentication worker is responsible for the HTML used in the login form and consent message. You can override the default with your own handlebars templates.

Site User Profile Mapping

Once a user has authenticated with a provider, details are passed back, mapped to the user's profile, and a site user is created or updated with the details.

Auth Sessions

The Authentication Worker stores all of its state in an AuthSession, stored in a database table called WkAuthSessions.

HTTP Methods

These methods are called via a standard HTTP POST or GET rather than via JSONRPC.

JSON RPC Methods

The worker supports five JSONRPC methods.

Share this page

Facebook icon Twitter icon email icon


print icon