Authentication services
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.
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:
| Item | Description |
|---|---|
| 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
Kerberos support was removed in version 8.3.16.
Terminalfour can work with a Kerberos protocol service. Kerberos is a computer network authentication protocol that uses 'tickets' to allow nodes communicating over a non-secure network to prove their identity to one another securely. 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:
| Item | Description |
|---|---|
| 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:
| Item | Description |
|---|---|
| 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:
|
| 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:
|
| 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':
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.
To enable SAML, click on the Enabled toggle.
Configure the following options:
| Item | Description |
|---|---|
| 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 |
| Logout URL | The URL of a custom logout screen |
If you are satisfied with your entries, then click Save Changes.
While SAML defaults to SHA1 encryption, from 8.2.18 support has been added for SHA1/SHA256/SHA384/SHA512. You can override this using the jvm property in Tomcat. In the setenv.sh file, you can change the last part of the line
JAVA_OPTS="$JAVA_OPTS -Dcom.terminalfour.saml.signatureAlgorithm=SHA1"
to reflect the algorithm required.