Kerberos – Single Sign-On

Posted on 4th January 2018

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 clients.  Kerberos SSO is not supported in the iOS or Android apps.

Appliance Time

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:

time-sync IP-address-of-domain-controller

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>

Example

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

WWhen a users signs into Foldr using Kerberos, the appliance still needs actual credentials to connect to the backend  SMB storage.   The administrator has two different options to this problem:

1. Use pre-defined service accounts in the Foldr Settings backend and connect to each configured share with a master service accountTo use this option this administrator must select a suitable service account in Foldr Settings >> Sharesand then enable ‘Use service account for all access’ on the advanced 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.

2.  Prompt users for their password the first time they access the system by Kerberos SSO.  Once the Foldr appliance has the users password, it is encrypted and stored within the 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.

Specify the IP addresses / subnets to be used for SSO (Applies to web app only)

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.

Click Save.

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, Google Chrome and Firefox should sign into the Foldr web app automatically.

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 the Safari browser.

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"

Authentication Fallback

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 Certificate warnings and Domains

It is common to use different domain names inside an organisation (Active Directory) and externally (for the public website, email etc). Due to the way Kerberos works, accessing Foldr via the internal FQDN will work by default, however it will also present the user with unwanted SSL trust warnings in the browser that must be accepted before signing in. Assuming you have a signed SSL certificate installed on the Foldr appliance, it would be preferable for users to connect to the public URL while still be able to use Kerberos SSO.

In order to do 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 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 a simple A record would.

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 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 / username@domain) 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:

klist

Note – if you need to request a new ticket, or are testing on a standalone Mac, issue the command:

kinit username@DOMAIN.COM

Note – the DOMAIN section must be uppercase

3. 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

Need more help?

Get in touch with our friendly help desk who will be happy to assist you, support@foldr.io