Knowledge Base

Authentication services

Last Modified:
08 Jan 2019
User Level:
Administrator

Description

Authentication services are available to ensure security protection of your site, network, and directories. To provide this protection, the normal process is to use various standardized protocols.

The protocols and services available to TERMINALFOUR are:

The following section describe each service and how to configure the service to meet your needs.

How to use Authentication services

To access Authentication services, go to System Administration > User Rights & Roles > Authentication Services. The start page is shown below. The services are presented in a tabular form allowing you to view their current status as either Enabled or Disabled.

You can directly access each service by either clicking the Edit option on the Actions menu or click the service name. 

Authenticaion services screen

CAS

You can choose to work CAS with the TERMINALFOUR system. As with SAML, when a user logs in to TERMINALFOUR, they are directed to use their CAS login. Additionally, a login to the CAS service automatically logs the user into TERMINALFOUR.

Your user accounts need to pre-exist in TERMINALFOUR (either created manually or via an import from LDAP/AD).

To configure CAS, go to System Administration > User Rights & Roles > Authentication Services. Select Edit from the Actions menu next to CAS.

To enable CAS, click on the Enabled toggle.

Configure the following options:

ItemDescription
CAS server prefix Enter the root URL to the CAS server installation, used for communication between TERMINALFOUR and the CAS server
Login URL Enter the URL to the CAS servers login page
Logout URL Enter the URL to the CAS servers logout page

If you are satisfied with your entries, then click Save changes.

Kerberos

TERMINALFOUR can work with a Kerberos protocol service. Kerberos is a computer network authentication protocol which uses 'tickets' to allow nodes communicating over a non-secure network to prove their identity to one another in a secure manner. This service functions as a client-server model to provide mutual authentication — both the user and the server verify each other's identity. 

To configure Kerberos, go to System Administration > User Rights & Roles > Authentication Services. Select Edit from the Actions menu next to Kerberos.

To enable Kerberos, click on the Enabled toggle.

Configure the following options:

ItemDescription
Service principal name* Enter the name of the Kerberos service principal you are accessing.
Location of keytab file* Enter the file location of the keytab file, which contains the Kerberos encrypted keys. E.g. /usr/var/secure/krb5.keytab. This file must be readable.
Kerberos realm* Enter the Kerberos authenticate administrative domain. For more information, see Kerberos domain.
Strip realm from principal? The Kerberos user principal needs to be mapped to a username. If the two are not the same and the specified realm needs to be stripped from the former to get the latter, then check this. Note a '@' is prefixed to the realm before it is stripped out.

If you are satisfied with your entries, then click Save changes.

LDAP

This service permits your LDAP or Active Directory users to log in to TERMINALFOUR using their standard user credentials. Permissions within TERMINALFOUR can be configured based on the roles these users are assigned within your directory service. If used, TERMINALFOUR locally stores some user information (example: username) but does not store any password related information.

Each authentication request takes place against your LDAP or Active Directory service.

To configure LDAP, go to System Administration > User Rights & Roles > Authentication Services. Select Edit from the Actions menu next to LDAP.

To enable LDAP, click on the Enabled toggle.

Configure the following options:

ItemDescription
HostName/IP address* Sets the hostname or IP address used to connect to the LDAP server 
Port* Sets the port used to connect to the LDAP server 
Secure communication

When communicating with the LDAP server, three mechanisms are available:

  • Non-TLS: This is an un-encrypted connection which sends everything in the clear (normally over port 389). Where possible use 'LDAP over TLS' connections.
  • Start TLS: Makes an un-encrypted connection to the LDAP server and uses the 'Start TLS' command to upgrade it to a TLS secured connection (normally over port 389).
  • LDAP over TLS: Makes a TLS secured connection to the LDAP server and routes all its communications over this secure link (normally over port 636). This is the recommended option for best security.
Admin DN* Enter the full Distinguished Name (DN) used to bind to the LDAP server e.g. cn=t4sitemanager, ou=ServiceAccounts, dc=terminalfour, dc=com
Admin password Sets the administrative password for the account specified above
Referral method

Property for specifying how referrals encountered by the service provider are to be processed. The value of the property is one of the following strings:

  • Follow: Follow referrals automatically
  • Ignore: Ignore referrals
  • Throw: Throw a ReferralException when a referral is encountered
Maximum results per page

Sets the page size when searching the LDAP server during an import. Set to 0 for no limit.

Update user record

Updates user information (e.g. first name) using values taken from the LDAP server. This keeps the TERMINALFOUR user information in sync with the user directory information. It is highly recommended that you use this option.

Deactivate user record Sets imported LDAP users as inactive rather than deleted if not found during subsequent imports. It is recommended that this is checked since if users are deleted all history and auditing information of that user is deleted.
Enable users on import Sets imported LDAP users to enabled by default
Default language Sets the default language for users from LDAP imports
Default html editor Sets the default html editor for users from LDAP imports
Username attribute Sets the LDAP attribute used to populate the user's username. This must be unique to each user. e.g. sAMAccountName
Email attribute Sets the LDAP attribute used to populate the user's email address e.g. mail
First name attribute Sets the LDAP attribute used to populate the user's first name e.g. givenName
Last name attribute Sets the LDAP attribute used to populate the user's surname e.g. sn

You may have additional elements if you use an Extended user details Content Type. This will vary from installation to installation. If such elements are present populate them with the appropriate attribute values for your user records.

Choosing an Authentication Service

When an Authentication Service has been configured and enabled, it will be listed in 'Default authentication method' drop-down. In this example, SAML has been configured and enabled and can then be selected as the 'Default Authentication method':

Screenshot of the SAML selected as authentication method in LDAP settings

To complete the configuration of the user import and creation, see LDAP Settings.

Common issues

The most common LDAP issues are the result of one or more of the following:

  • The CMS server is not whitelisted on the LDAP server
  • The LDAP server certificate doesn’t exist in the Tomcat keystore on the CMS
  • Username/password for the admin DN is incorrect in the LDAP config

Local

This service is for accounts associated with TERMINALFOUR use only. These accounts are stored securely on the TERMINALFOUR database and use the standard combination of the username and password. This service can be beneficial for providing access to users who are not in your organization's directory services. Also, you can use if integration between TERMINALFOUR and your directory service or other authentication servers is not possible.

To configure Local, go to System administration > User Rights & Roles > Authentication services. Select Edit from the Actions menu next to Local. The only configurable option is to Enable or Disable local authentication.

TERMINALFOUR recommend leaving this enabled at all times. You must always maintain one Local user for use with TERMINALFOUR administration should there ever be a problem connecting to your directory service. This account is required when upgrading TERMINALFOUR.

Remote User

This method is designed to permit ease of integration with non-standard or custom authentication functionality. With the Remote user function you can pass a username to TERMINALFOUR as a header variable, and if matched, the user login is successful.

Your user accounts need to pre-exist in TERMINALFOUR (either created manually or via an import from LDAP/AD).

To configure Remote user, go to System Administration > User Rights & Roles > Authentication Services. Select Edit from the Actions menu next to Remote user.

Enter the Header name: the request header to parse that TERMINALFOUR will use to identify the correct user

If you are satisfied with your entries, then click Save Changes.

SAML

If your organization prefers to use SAML or Shibboleth-based single sign-on services, this service works with TERMINALFOUR. If this is the case, TERMINALFOUR acts as a service provider and initiates authentication requests against your Identity Provider. Each time a user needs to login to TERMINALFOUR they are directed to the organization's single sign-on page to login. In cases where your users have already logged in to your single sign-on server then they are automatically logged in to TERMINALFOUR.

Your user accounts need to pre-exist in TERMINALFOUR (either created manually or via an import from LDAP/AD).

If you are using LDAP with SAML, it's recommended that you configure, test and import users with LDAP first. 

To configure SAML, go to System Administration > User Rights & Roles > Authentication Services. Select Edit from the Actions menu next to SAML.

SAML authentication configuration options screenshot 

To enable SAML, click on the Enabled toggle.

Configure the following options:

ItemDescription
IdP Metadata URL* The URL to a document describing one or multiple identity and service providers. Exchange of metadata between identity and service providers is typically the first step for establishing federation.
Identity provider entity ID* The ID of the entity taken from the metadata document which authenticates users and provides information about their identity to service providers/relaying parties using federation protocols.
Service provider entity ID* The ID of the service provider TERMINALFOUR uses to communicate with the identity provider.
Default key name* The default key in the keystore file.
Identifier parameter key* The parameter returned as part of the SAML assertion for TERMINALFOUR. Used to identify the correct user

If you are satisfied with your entries, then click Save Changes.