Introduction – Kerberos SSO
Foldr can be configured to authenticate users using Kerberos authentication. This provides a convenient way to automatically sign users into Foldr if they are using a PC or Mac that is bound to Active Directory. With Kerberos SSO, a user can sign in automatically to either the Foldr web app and Windows / macOS drive mapping apps. Kerberos SSO is not supported in the iOS or Android apps.
Signed SSL Certificate Requirements
A signed SSL certificate must be installed on the Foldr server for Kerberos authentication to work successfully. You can install a purchased signed certificate from a recognised provider or make use of the free option available via Let’s Encrypt. The default, self-signed or other ‘untrusted’ certificate cannot be used.
Internal DNS changes should be made to allow clients using Kerberos to connect to the Foldr server using the URI protected by the SSL certificate. This is covered later in the article.
To use Kerberos authentication, the Foldr appliance must have accurate system time – i.e. it must be in sync with the Active Directory domain. You can check the appliance time from within Foldr Settings (show top right of the UI) or by running the
date command from the console when signed in as fadmin. Should you need to correct the appliance time, this can either be done by correcting the host clock (VMware ESXi etc) or if using NTP in Foldr Settings >> General >> Time Settings and obtain time from a local domain controller.
You can force the appliance’s clock to be synchronised with an NTP time source using the console command:
Enabling Kerberos authentication
1. Log onto the Foldr appliance console and issue the command:
krb5-enable <Active Directory FQDN> <Domain Controller FQDN> <Foldr Appliance FQDN> <Foldr Appliance Hostname> <AD Account to join Foldr to domain>
krb5-enable minnow.it dc-01.minnow.it foldr-v4.minnow.it foldr-v4 administrator
2. Enter the Active Directory account password
The appliance will join the domain and a computer account object will be created in the default Computers container in Active Directory.
Security Considerations – Service Accounts and User Passwords
When a user signs into Foldr using Kerberos, the appliance still requires credentials to connect to the backend SMB storage such as those hosted on Windows file servers. The administrator has two different options to this scenario:
1. Recommended – Prompt users for their password the first time a new user signs into Foldr using Kerberos SSO. Once the Foldr appliance is given the users password, it is encrypted and stored within its configuration database and can then be used for future sessions. A benefit of this approach is that service accounts are not required for access to SMB shares and Foldr can operate in the normal manner of respecting all existing security ACLs on the file servers providing access to the shares/data. You can enable the prompt for network credentials feature when enabling the SSO service within Foldr Settings >> Single Sign-On >> Kerberos.
2. Use pre-defined service accounts in the Foldr Settings backend and connect to each configured share with a master service account. To use this option this administrator must select a suitable service account in Foldr Settings >> Shares & Storage >> edit-share >> Access tab and then enable ‘Use service account for all access’ in the Access tab in the share configuration screen.
If the administrator also enables ‘Full ACL support‘ on the advanced tab, the appliance will connect to the storage using the service account credentials, but then parse the Windows ACLs to provide the correct permissions for the user signed into Foldr.
If full ACL support is not enabled, Foldr will not respect the users’ actual security permissions but instead provide the level of permission that applies to the service account user. The administrator can still control read or write access to each share for the service account using the permissions section in Foldr Settings >> Shares & Storage.
Specify the IP addresses / subnets to be used for SSO (Applies to web app and client apps using web sign-in)
Within Foldr Settings >> Single Sign-on >> Kerberos you should now configure the subnets (or even individual IP addresses) that clients will be connecting that should use Kerberos SSO. Configure one subnet / address per line.
Windows Client Configuration (Applies to web app only)
The Foldr appliance URL must be added to the workstations LOCAL INTRANET zone before they are able to use SSO in the web browser interface.
Control Panel >> Network and Internet >> Internet Options >> Security tab >> Local Intranet >> Sites >> Advanced
Once this change has been made Internet Explorer, Edge, Google Chrome and Firefox and their variants should sign into the Foldr web app automatically. Other browsers may not be compatible.
These settings can be controlled in a domain environment through Group Policy.
macOS Client Configuration
No client configuration is required on a domain bound macOS computer when using SSO in Safari.
To use Google Chrome browser with Kerberos based SSO, you must run the following commands from the macOS terminal, replacing “your-appliance.fqdn” with the URL of the Foldr appliance.
defaults write com.google.Chrome AuthServerWhitelist "your-appliance.fqdn"
defaults write com.google.Chrome AuthNegotiateDelegateWhitelist "your-appliance.fqdn"
Should you attempt to connect to web app from within a Kerberos SSO specified subnet, but the machine is not domain bound, you will be presented with a standard authentication prompt. If valid credentials are entered into the prompt, the web app will sign in as usual.
SSL Certificates and Domains
It is common to use different domain names inside an organisation (Active Directory) and externally (for the public website, email etc).
In order to support this, assuming that one does not already exist, you must create a forward lookup zone on the internal DNS service (typically a Windows domain controller) for the EXTERNAL / PUBLIC domain and create a CNAME record inside this zone pointing at the internal FQDN of the Foldr system. A CNAME in DNS is an alias and as such does not break Kerberos authentication in the same way that an A record would. Other DNS records should be created for this zone as required for the organisation.
NOTE – If the internal FQDN of Foldr matches the common name of the SSL certificate installed on the appliance, a CNAME is not required.
Creating the CNAME record in DNS
In the example below, the domains are as follows:
minnow.it = internal Active Directory domain with a Foldr appliance accessible at foldr.minnow.it. An A record already exists in this zone for ‘foldr’ pointing at the virtual appliance.
foldr.io = organisation’s public domain.
After creating a new lookup zone for foldr.io, right click in the zone and select ‘New Alias (CNAME)
Enter the public FQDN of the appliance (i.e. that is covered by the SSL certificate installed on the appliance) and point this at the internal FQDN (foldr.minnow.it)
IMPORTANT – When creating the new lookup zone on the internal DNS service for the organisation’s public domain, you must also consider any other records that need to be created. Typical examples are the public website, webmail servers and so on. Create records for each as required and point them at the relevant public IP address.
If you now browse to the Foldr server at https://demo.foldr.io on a domain bound workstation, the SSL certificate will validate and it will sign in automatically with Kerberos authentication.
Foldr for Windows Configuration (Drive Mapping Client)
Kerberos SSO is supported in release v1.0.38. By default Kerberos SSO is available to use, but is not the default authentication type. Should the user wish to sign in via Kerberos SSO on a domain bound machine, a Single Sign-On checkbox is available to use.
Kerberos SSO can set as the default authentication method through an MSI option when deploying the client (SSO_LOGIN_BY_DEFAULT=1) – More information on deploying the Windows application and the available MSI options can be found in the following KB article
Foldr for macOS Configuration (Drive Mapping Client)
By default Kerberos SSO is available to use, but is not the default authentication type. Should the user wish to sign in via Kerberos SSO on a domain bound machine, a Single Sign-On checkbox is available to use.
Troubleshooting Kerberos using macOS
Mac clients provide some useful command-line utilities to help troubleshoot Kerberos issues. If you are having issues with the app signing in, please follow these steps and raise a support ticket through the support email address.
Firstly, double-check that the user in question has no issues with their account in Active Directory. A blank UPN attribute (User Principle Name / [email protected]) from a misconfigured bulk user import script can be the root cause of some Kerberos issues that only become apparent on non-Windows clients.
Check DNS, and if required in your environment, create a CNAME record as described above. Ensure the client is connecting to Foldr so the (signed) SSL certificate is valid on the client.
1. Open Terminal
2. Check for the existence of a Kerberos ticket using the command:
Note – if you need to request a new ticket, or are testing on a standalone Mac, issue the command:
kinit [email protected]
Note – the DOMAIN section must be uppercase
curl -v --negotiate -u : https://FOLDR/sso/krb5
Replacing FOLDR with the FQDN of the Foldr appliance
4. If Kerberos authentication is working as expected, towards the end of the output you should see a HTTP 302 redirect pointing to /home
Group Memberships & 400 error bad request
If a user is unable to sign into Foldr and receives a 400 error / bad request, this will be due to the user being a member of a large number of groups in Active Directory. To resolve, simply reduce the number of security groups the user is a member of.