This covers authentication methods in Digital-Clay, including 'single sign-on' and 'same sign-on' features added in version 9.2.57. It is a guide for administrators to learn how to configure Clay and integrate Clay with external authentication servers.
Digital-Clay supports multiple authentication methods. The default built-in authentication method is a proprietary and stand-alone Clay login where the passwords are managed and authenticated by ClayCentral and the user has to enter their Clay username and password. The other custom/external authentication methods that can be added to Clay, are either 'single sign-on' or 'same sign-on', where the users and passwords are managed by an external server.
'Single sign-on' is when Clay takes an existing and active login session (for example from the user's running Windows OS, or a web site) and uses that to sign into Clay without requiring the user to login to Clay at all. Whereas 'same sign-on' means the user sees the Clay login window and has to type their username and password, but the authentication is performed by an external server. Even this latter method however provides several important benefits, including the ability to manage users and passwords in only one place, as well as allowing Clay to take advantage of more advanced and customized authentication methods such as multi-factor authentication.
Customizing and adding authentication methods in Clay is done via the ClayCentral Settings tool under Security/Custom Authentication.
There may be multiple authentication configurations added for each type, except 'Built-In' and 'Windows SSO'. Adding multiple configurations allows users to login using one of many servers, for example two Windows domain controllers, or even the same Windows server with different configuration options, one for each domain or Active Directory folder.
Note that all external authentication methods only work if the User exists in Clay. Either the User must already be there beforehand, or can be added/merged automatically once the user is authenticated externally (this is configurable), or the user may be imported into Clay using the 'Import' button. I.e. users logging into Clay still login as Clay users (and require an appropriate license), they are merely authenticated and managed elsewhere.
If you lock yourself out and can't login even as an administrator, you must remove the custom authentications from the registry manually under Software/DigitalClay/ClayCentral and remove the 'AuthMethods' setting and restart ClayCentral. This will remove all of the configured custom configurations and you will have to configure them again.
This is Clay's own authentication. Users and passwords are managed by Clay. When customizing authentication methods in Clay, this default authentication method is no longer used unless this is added as one of the Custom Authentication methods in the list. In other words, once you customize, you will no longer be able to authenticate using Clay users and passwords unless this method is added to the list of methods. This is recommended to do at least temporarily, in case you lock yourself out by misconfiguring other authentication methods.
There can be only one Built-In method added to the list. As opposed to other custom methods, it is configured using the 'Built-In Authentication' tab. There you can configure things such as password requirements, among other things.
This takes the current Windows login session used by the client on the client's Windows machine, authenticates the user using Windows authentication at the server where ClayCentral is running, and logs the user into Clay using the Windows session information.
There can be only one Windows SSO method added to the list since it doesn't require much configuration.
This method is Single Sign-On and by default doesn't show the Clay login Window.
This method allows for any advanced authentication method including biometric and multi-factor, as long as the client's Windows OS has been configured for it.
To use Windows SSO in desktop Clay clients, nothing else needs to be configured. But the client machine must either be in the same Domain as the ClayCentral server machine, or the same Windows user/passwords must exist on both machines.
To use Windows SSO in WebClay, additional configuration is needed. See below for more detail. Note that the web browser must be running on a Windows machine in the same Windows domain as the server as with desktop clients in order for the login to be automatic. But if it isn't, the user may still login, but will be prompted for a Windows username and password.
The Windows SSO method is unique in that it can be combined with a 'Windows Active Directory' configuration as its 'Source':
These are two authentication methods that use very similar configuration options and methods, but which have been separated for convenience with different default options.
Both are 'same sign-on' methods (see above). This means the user will still need to type the username and password in the Clay login window if he uses this method, but the authentication will be performed using the AD or LDAP server. This also allows for two-factor authentication if the server supports it.
Configuration options include the server connection options, as well as how to map user information from the server to Clay.
Single Sign-On using a currently logged in session for a web site that supports SAML. TBD.
Single Sign-On using a currently logged in session for a web site that supports OpenID. TBD.
Whether the user already exists in Clay, or is being added after the user is authenticated, the Role (and optionally the Workgroup) in Clay will be set every time the user is authenticated.
There are two ways to set the Clay Role and Workgroup:
This is done by using the 'Role Mapping' tab in ClayCentral Settings under Security. This maps one to one. For example one of the user's groups like 'Domain User' in the Active Directory can be mapped to a Clay Role called 'Restricted User' and optionally to the 'Marketing' Workgroup.
If the user has multiple groups, only one will be used. Ordering is important, as the highest mapping in the list that Clay finds will be used. For example, the 'Domain Admins' mapping may be placed higher up than 'Domain Users' in order to give that group top priority.
The role mapping list has been separated from the authentication method configuration so that it only needs to be done once for all methods.
Note that this feature very effectively allows for filtering of users. If a mapping is not found and no Default Role is set (see below), it will reject the user. Thus one can filter and allow only users belonging to certain known groups.
This is configured using the custom authentication method window. Only if the above role mapping fails to find a mapping, will Clay use these defaults. I.e. this is a fallback and allows all users to be added to Clay with a default Role/Workgroup regardless of their group at the source.
Use these settings with care, as it may import unexpected users and give them the default Role you defined.
If neither a mapping nor a default is set, the user's authentication will be rejected.
Name: This name appears in the login window and the user may select the authentication method using this name.
Active: This allows one to deactivate an authentication method temporarily without deleting it.
Default Path/Domain: This is a very important setting for AD/LDAP. This is what allows users to enter their short username in Clay instead of their fully qualified Domain/LDAP path of their user. For example, a user in AD may be identified as either 'CN=Jack,CN=Users,DC=Acme,DC=com' or 'Jack@Acme.com' or 'Acme\Jack'. By default these would be the proper usernames to use when logging into Clay using this method. But by using this option, this can be shortened:
For example, if this option is set to 'CN=%username%,CN=Users,DC=Acme,DC=com' and then the user can simply type 'Jack' as his username which will be expanded to the above path when authenticating with AD (%username% is the mandatory placeholder).
If the AD/LDAP server has multiple paths or domains, and the user belongs to the non-default domain, then there are two options:
Add if Doesn't Exist: This tells Clay whether to add the authenticated user to Clay if it doesn't exist. If this setting is off and the user doesn't already exist in Clay, the authentication will be rejected. Users may be added manually beforehand, or imported, as an alternative to this option. Turning this off would strictly restrict the users entering into Clay only to users known in advance (but would still allow the administrator to manage the users' information and password elsewhere).
Merge Into Existing: Use this with caution. As an alternative to the above option, this would allow users into Clay as long as their Username exists in Clay. For example, if 'Jack' already exists in Clay as a Clay username but has never logged into Clay using the external authentication method before, this option would allow Jack in by merging the external Jack with the Clay Jack. But if Jack doesn't exist in Clay already, he would only be able to login to Clay if the 'Add' option is on.
Warning: This setting can be very dangerous if external usernames are unknown or not under control of an administrator. For example, if the external authentication server has a user that called himself 'admin' it would be merged into the Clay 'admin'. The Clay Role would be changed once authenticated so the user would not be able to do anything that the mapped role doesn't allow him to do. But the existing Clay user would be 'hijacked'.
Use Floating License: This applies to the 'Add' option above only. When users are added they can be added with their 'Floating License' flag set in advance. This may help with licensing issues.
Default Role/Workgroup: See Role Mapping above.
(Note that using Automations, other fields in Users added by external authentications can also be set using Automation rules.)
External Authentication Only field: This is a field in the Users table not in the authentication method. When users are added automatically or imported from an external authentication server, this flag is set automatically. This means that this user cannot login to Clay using the built-in method and only with the external method (since the user has no password). If the admin wishes to allow these users to login using Clay, this flag must be unchecked.
Authentications: This is also a field in the Users table. It lists all the authentication methods used by this user in the past. Authentications may be removed (but not added) via this field. For example, use this if the user was merged incorrectly and is identified as the wrong external user.
This section is where you configure the connection to the authentication server. For example with LDAP, you configure the server hostname, port, whether to use SSL, a username/password with access (for getting user information from the server), and the Base Path, the base from which to start looking for users.
The 'Base Path' (LDAP) can be used to filter which users will be added/authenticated and can limit Clay to a subset of the directory.
This tab tells Clay how to map user information from the authentication server to Clay. For example, the names for classes to use to identify which objects are users or groups, and which attributes to use for finding group memberships, names and email/phone info. Multiple classes and attributes may be used for each mapping, separated by commas. Note that the most common defaults are automatically filled, but these may be changed as needed.
Example: Say you want to authenticate or import all objects of type 'user', 'person' and 'inetOrgPerson'. In which case the User's 'Class Name' option should be set to 'user,person,inetOrgPerson'. And if their phone may be stored in two different attributes, the 'Phone' option can be set to 'mobilephone,workphone'.
The above configuration options list what is needed for external users to be added to Clay automatically on successful authentication. Alternatively, users can be imported into Clay using the Import button and then the authentication method can be configured to not add any more users automatically.
Simply select the authentication method from the list (it won't work with Windows SSO) then use the Preview and Import buttons. It is highly recommended to use the Preview button first. This will open a list of users and whether the user cannot be imported due to a role mapping error, or whether it will be Added (the Add option does not have to be switched for an Import), Merged (only if the Merge option is on), or simply Updated (meaning synchronized). The Import button will actually perform these actions as well as show the list of users.
Imported Users may then be pruned or edited manually as usual within Clay.
Note that Clay license restrictions will come into effect during an Import. Same with Automation Validations and Required Fields. The import may therefore result in errors.
By default, all Clay clients will use the first authentication method in the list. The order of the custom authentication methods is therefore important. For example, if Windows SSO is first in the list, the Clay client will automatically login using the current Windows session even on first run.
To select a different authentication method, the user can load the Clay Login window (e.g. by disconnecting) and select it from a list in the username drop-down. This method will then be saved for the next time the user logs in, and it will become the user's new default Authentication Method.
There are several options to implement a more complex authentication mechanism:
This section is only relevant for the 'Windows Single Sign-On' authentication method.
To use Windows SSO in desktop Clay clients, nothing else needs to be configured. To use Windows SSO in WebClay however, additional configuration is needed in four places: ClayCentral, WebClay, Apache, and the client's Web Browser:
ClayCentral: ClayCentral must be told two things, otherwise all SSO logins from a web source will be rejected with a bad SSO configuration error message. Both of these settings are set in the ClayCentral Settings window in the 'General' tab:
WebClay: Web ClayStation needs to be configured with the SSO key used in the previous step. This setting 'ssokey' can be configured using the command-line or with an environment variable. See Web ClayStation for more details.
Web Browsers: This step has to be done for every client web browser on each client machine or mobile device (unless a Group Policy is used). Each browser type is different and these instructions may change depending on the browser version. It is recommended to search the web on how to do this, but see for example: Configuring Browsers for NTLM
Quick summary:
Apache: Note that the default configuration file installed by the WebClay install includes this configuration so nothing needs to be done for this step unless you need to change the configuration or add it to your own Apache install.
Also note that IIS configuration is also possible but not covered here.
The first thing with Apache is to decide whether you want to separate users logging in using Windows SSO and regular Clay logins. This is important because if a user logs into WebClay from a mobile phone or machine that is not Windows or not in the same Windows domain of the server, the automatic SSO login will not work and the user will be prompted with a generic Web login window where they can enter their Windows username and password. Whereas a normal Clay login will show the Clay login window instead.
To separate it with Apache, you can configure two different Locations in the httpd.conf. For example, the following first defines two locations to be handled by WebClay “clay.dcw” and “claysso.dcw”.
LoadModule proxy_fcgi_module modules/mod_proxy_fcgi.so <IfModule mod_proxy_fcgi.c> <Location /clay.dcw> SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ProxyPass balancer://clay </Location> <Location /claysso.dcw> SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 ProxyPass balancer://clay </Location> </IfModule>
And then this section defines the claysso.dcw only for automatic Windows SSO authentication, leaving clay.dcw for regular users. Note that it requires the optional mod_authnz_sspi module and it is fully annotated so you can understand what each option does:
<IfModule !mod_authnz_sspi.c>
LoadModule authnz_sspi_module modules/mod_authnz_sspi.so
</IfModule>
<IfModule mod_authnz_sspi.c>
<Location /claysso.dcw>
# What to prompt in the user/pass popup dialog
AuthName "Clay/Windows Authentication"
# A must for NTLM
AuthType SSPI
# FOR SERVER: this will turn on/off the Windows authentication module
SSPIAuth On
# FOR SERVER: this will turn on/off if the the Windows authentication is mandatory or if other modules can be used as a fallback
SSPIAuthoritative On
# FOR CLIENT: Set this if you want to allow access with clients that do not support NTLM, or via proxy from outside. Don't forget to require SSL in this case!
SSPIOfferBasic On
# see above if it is On then basic authentication will have higher priority
SSPIBasicPreferred Off
# the IP address or name of your windows domain controller against which the authentication is run
SSPIDomain localhost
# Set this if you have only one domain and don't want the MYDOMAIN\ prefix on each user name
SSPIOmitDomain Off
# tells how the user name letter cases are converted. The possible values are lower and upper. If this is not specify then no conversion is made. AD user names are case-insensitive, so use this for normalization if your application's user names are case-sensitive
#SSPIUsernameCase Lower
require valid-user
</Location>
</IfModule>