Toggle menu


The site login article uses the Authentication template. It lets users log into the site, either with an account they have created using the Registration form, or with a third party provider.

Auth Login

Page Title and Content

The page title and content, including inline elements, appear as per the Default template.

Related Assets

Articles using the Authentication template display related images, media items, forms, polls and features in the same way as the Default template.

Related Articles

Related articles are output as a series of links beneath the other page content. 

Utility Articles

Articles picked in the Utility section of the article extras are output as links beneath the login form. These links are designed to link to your site's registration and password reset pages. The links will include your login article as a return URL parameter (including any return URL parameters present on your login page).

These return parameters mean that when a user registers with your site, or resets their password, the forms can redirect them back to the login article and, once they have logged in, they will be redirected again to the secure content they were trying to access.

The standard forms we provide are called CITIZENSIMPLESIGNUPEXAMPLE and CITIZENRESETPASSWORDEXAMPLE. They should be related to articles using the Forms Service template and those articles picked here.

Login Form

The login form is generated by Handlebars Templates the Authentication worker.

The actual login options displayed on the form can be controlled using the article extras of the Authentication template.

When Will Users Log In?

There are two scenarios that will prompt a user to log in.

Authentication Challenge

If a non-authenticated user tries to access secure content, they have to log in. The user will be directed to the site's login article, which uses the Authentication template, and once they've authenticated, they'll be redirected to the secure content they were trying to access.

Upon reaching the secured content the user will either be able to view the content, or be presented with a "Security Denied" message (set in the subsite configuration) should the content be secured to a security group the user is not a member of.

Direct Login

A non-authenticated user may also log into the site by navigating directly to the site's login article. After successfully authenticating the user will be directed to the "Welcome" article in the article extras. If an article has not been set, the user will be directed to the site's homepage.

Failed Logins

If a user fails to authenticate when logging in using the "already a member" method (ie they are registered directly with the site via your registration forms), they'll receive an error message advising them that either the username or password they entered was incorrect.

Multiple attempts to log in with a valid username but incorrect password may cause the user to become locked out. The default is to be locked out for 15 minutes after 5 failed login attempts. Both the lockout threshold and lockout duration are configured in the iCMSiteUser provider of the Authentication worker.

Two-Factor Authentication

The iCMSiteUser provider can also have two-factor authentication enabled. This functionality is provided entirely by the Authentication worker and not controlled by your login article or the Authentication template.

Creating a Login Article

The Authentication template is one part of the GOSS Authentication product. The full product also includes the API Server's Authentication worker, iCM's Site Groups and Users, optional connections to external authentication providers, and iCM Forms which handle user registration, password management and user profile information.

Configuring the Site Login

An article using the Authentication template can be configured via its article extras as follows:

  1. Log out text. When a user is logged in, the log out text will be used when outputting links to the login article instead of the article heading or alternate link text. If left blank, the value "Log out" is used. When this link is clicked users will be automatically logged out of the site. They will remain logged into any external authentication providers if they logged in via a third party (ie if a user authenticates using Facebook, then logs out of the iCM powered site, they will remain logged into Facebook). This behaviour is outside of our control.
  2. Welcome article. If the user was prompted to log in when trying to access a secure article or content (the target content), they will be redirected to it on successful login. If no such target content can be identified, the user will instead be redirected to the selected "Welcome" article. If a welcome article is not selected, the user will be redirected to the site homepage.
  3. Default groups. A list of the groups that a user authenticating with the site will be added to. If you change these groups, the next time a user logs in, they'll be added to any additional groups. User's aren't ever removed from groups (otherwise your staff members would be removed from their secure groups when logging in)
  4. Utility articles. Pick the articles that display your registration and password reset forms
  5. Enabled authentication providers. The authentication providers a user is able to sign in with. These providers must first be configured in the API Server's Authentication worker. Only providers that have been configured will appear here. Checking a box will cause that provider to appear on the login article.
  6. Enable LDAP authentication. Check to allow LDAP Authentication. For LDAP/Windows authentication to function the server will need to be appropriately configured.

Site User Creation

After successfully authenticating against an external provider, user details are retrieved, mapped to the Authentication worker's UserProfile class, and a site user created or updated. An appropriate login is recorded against their account.

Site users are added to the groups set in the article extras of the login article. This should normally include the "default" security group for your site. Users will also be added to a group named after the type of external provider that created them, using the providerName set in the configuration of that provider. Should this group not already exist it will be automatically created.

Example Site User

The following user was created after authenticating via Facebook.

Example User

The user has been made a member of three groups.

Example User Groups

The first of these is the default Facebook group automatically created by the Authentication worker. The other two were assigned at the time of login, and are set in the article extras of the Authentication template article.

Default Groups

User logins created by authenticating with an external provider cannot be used by a user to log in via the iCM Site User username and password method (the "already a member" option), despite them existing as users in iCM. The username of the login will never be known to the user and the password is not stored in iCM. Authentication is handled entirely by the external provider.

Login Timeout Configuration

When a user logs into your site a login session is created for them. If they remain idle for a period of time, their session will expire and they will be logged out. A session becomes idle if there are no key presses, mouse clicks or any mouse movement for the whole time period, which defaults to twenty minutes.

The default behaviour of sessions and notifications is described in the framework Session Timeouts article. You can customise the idle timeout and the timeout notification text in the Authentication article extras. See the table below for more information.

If you have more than one authentication article, the configuration for the article that was used to log in with are used. That means you could have two articles set up, perhaps one for the public and one for staff, using different authentication providers and different timeouts.

Article Extras

Field NameTypeDescription
LOGOUTTEXTTextReplaces the article heading when the user is logged in. Default: "Log out". Users are automatically logged out when they click this text
WELCOMARTICLEAsset Lookup (single article)The article a user will be redirected to after logging in
GROUPSAsset Lookup (multiple site user groups)The groups a user will be added to when they successfully log in
UTILITYARTICLESAsset Lookup (multiple articles)Pick Forms Service articles that display your registration and forgotten password forms. These links will automatically be appended with the URL of the login article (including any return URL parameters) as a return URL, allowing the forms to redirect the user back to this page
PROVIDERSCheckbox groupThe configured authentication providers. Options are populated using the 'getProviderDetails' method
ENABLELDAPAUTHENTICATIONCheckboxWhether LDAP is enabled or not
IDLETIMEOUTMINUTESNumberThe time, in minutes, that a session remain valid for without any interaction from the user
TIMEOUTNOTICETEXTText AreaThe text that will appear in the notification
EXPIREDNOTICETEXTText AreaThe text in the notification once the session has expired
Last modified on 28 March 2024

Share this page

Facebook icon Twitter icon email icon


print icon