Title: How do I configure TeamPage for Kerberos authentication with Microsoft ActiveDirectory?
TeamPage supports Kerberos for user authentication via the standard mechanism outlined in RFC 4559. The document explains how to set up TeamPage to use Kerberos authentication for user accounts defined in Microsoft Active Directory (AD).
Introduction
When connecting to AD for user management, TeamPage still supports NTLMv1 out-of-the-box. The more secure NTLMv2 is supported with an extra-cost add-on. TeamPage also supports connecting to Azure AD instead of on-premises AD.
But if you're still using on-premises AD, Kerberos is definitely a more secure option than either version of NTLM. Indeed, many organizations either are in the process of disabling NTLM in their AD environments, or have already done so. Additional advantages of using Kerberos include:
- Support for the latest strong encryption standards.
- No communication is required between TeamPage and the AD service to authenticate the user.
- Widely natively supported in Windows environments, and supported with some extra configuration steps in both Linux and MacOS.
Please read on to learn how to set up a TeamPage server to use Kerberos authentication for users defined in your AD environment.
AD Configuration
You will need to set up an account in AD that can be bound to the Service Principal Name (SPN). The following steps require both administrative access to at least one domain controller (DC) in your AD environment so that you can use Active Directory Admin Center and Windows PowerShell.
You will need all the details, such as the account name and password, configured in these steps below in the "TeamPage Configuration" section, so please either make a note of them. You may also want to follow along with the instructions in that section in parallel with these instructions.
A competent AD administrator should perform these steps to ensure that it is done correctly while preserving your organization's policies.
1. Create a new service account. We suggest you use something that identifies the TeamPage server for which the Kerberos authentication is being configured. In this example, we've chosen "teampagedev" for our TeamPage Development server. You might choose "teampagepro" for production or "teampagetest" for your test server. Make a note of the password you use (ideally storing it somewhere secure, such as a password manager); you will need it in step 4 below.
Be sure to open the Password options and Other encryption options so you can choose "Other password options" > "Password never expires", since this is effectively a service account; and "Other encryption options" > "This account supports Kerberos AES 128/256 bit encryption".
(The reason it is important to enable those AES encryption types is that future versions of Java may not support older less secure encryption types. Setting this up now makes this arrangement more future-proof all around.)
2. Ensure that your Windows Server environment supports current and future strong encryption types.
In the Local Security Policy editor, you can find the setting labeled "Network security: Configure encryption types allowed for Kerberos". You will need to at least check the boxes for the AES 128 and 256 options; you may also wish to check the box for "Future encryption types", and to uncheck the boxes for other weaker encryption types:
3. Register an SPN for incoming connections from your TeamPage server.
In this example, our TeamPage server is running on the host "funzone.tractionsoftware.com", and our domain is "tractionsoftware.com". Our SPN, therefore, will be "HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM" -- note that the domain following the @ symbol must be in ALL CAPS.
We'll use the setspn command in PowerShell. -L means "list"; -A means "add"; and -D means "delete" in case you make a mistake and need to do that. In this example, we'll list, then add the SPN, and then list again to confirm what we did:
PS C:\Users\Administrator> setspn -L teampagedev
Registered ServicePrincipalNames for CN=teampagedev,CN=Users,DC=tractionsoftware,DC=com:
PS C:\Users\Administrator> setspn -A HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM teampagedev
Checking domain DC=tractionsoftware,DC=com
Registering ServicePrincipalNames for CN=teampagedev,CN=Users,DC=tractionsoftware,DC=com
HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM
Updated object
PS C:\Users\Administrator> setspn -L teampagedev
Registered ServicePrincipalNames for CN=teampagedev,CN=Users,DC=tractionsoftware,DC=com:
HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM
4. Create a keytab file that TeamPage will use to decrypt Kerberos authentication challenge responses from users' browsers.
The SPN will be the user name. You'll use the same password you set for the user account in step 1.
We use the ktpass command in PowerShell to create this SPN binding to our "teampagedev" user account. Besides the SPN and the name of the user account, we need to choose the following:
- The target DC to use (or we can omit -target and let ktpass use its default behavior, which will automatically select a DC based on the principal name).
- The type of encryption. We strongly recommend that you use "AES256-SHA1" which is a robust option supported by both Windows and all versions of Java TeamPage currently runs on.
- The output file. We recommend choosing a good and descriptive name, and an extension of .keytab. In the example, we've chosen "teampagedev.aes256.keytab".
Note that the principal type (-ptype) must be "KRB5_NT_PRINCIPAL".
Here is an example command with suitable arguments for all these parameters:
ktpass -princ HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM -mapuser teampagedev -crypto AES256-SHA1 -ptype KRB5_NT_PRINCIPAL -pass sledge-oldy-PHOSGENE -target WIN-G53K0E0GRBO.tractionsoftware.com -out c:\Users\Administrator\teampagedev.aes256.keytab
The output from this command will be something like the following:
Using legacy password setting method
Successfully mapped HTTP/funzone.tractionsoftware.com to teampagedev.
Key created.
Output keytab to c:\Users\Administrator\teampagedev.aes256.keytab:
Keytab version: 0x502
keysize 105 HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM ptype 1 (KRB5_NT_PRINCIPAL) vno 5 etype 0x12 (AES256-SHA1) keylength 32 (0x608647feef0f58c097b9195bc79bd23c4b734eefb149519e7075b023c4392165)
4. Copy the keytab file to the TeamPage server. It will be required in the steps below.
TeamPage Configuration
1. Navigate to server settings > General > Current Journal and click the "Modify User Directory" button.
2. In the user directory chooser view, click "New..." to open the user directory dialog.
3. In the user directory editor, enter a description for your new configuration. We suggest including the date and some mention of Kerberos. Also choose whether Visitor access is allowed. (Your license may or may not allow Visitor access; please create a support request if you need further assistance with the Visitor account.)
4. In the "Active Directory Server" settings, set your domain controller, LDAP search base, and other basic AD connection and lookup settings.
- In this example, we've chosen to use the FQDN for a single DC; you may choose to use your root domain as a way to let your AD environment route requests to various DCs.
- Our default domain is "win-2019-test" because our user accounts belong to that domain in this example.
- Your LDAP search base should include the DN components to narrow down the scope of the query that TeamPage will use to find users and groups
- We suggest you choose LDAPS (SSL/TLS) if possible to secure the connection for LDAP queries made by TeamPage. You should also consider whether you will need to use the global catalog port (3268 or 3269 for LDAP with TLS) so that TeamPage can locate all users you'll want to find.
- The Authentication Type setting here refers specifically to the LDAP query connections. The currently available options are none (anonymous access) and simple (user name + password). (In future, Kerberos may also be supported here.) Assuming you have an AD account set up to allow TeamPage to perform LDAP queries against AD, choose "Simple" and enter the user name and password in the fields provided.
5. Configure the "Authentication" settings governing user authentication.
- Choose "Kerberos" for the Login Method setting.
- For the keytab file, enter the location of the file -- where you copied it in AD Configuration Step 4 above. The path can be absolute -- e.g., D:\Traction\TeamPage\teampagedev.aes256.keytab -- or a path relative to your TeamPage installation's server folder, e.g., settings\teampagedev.aes256.keytab if you placed it in, e.g., D:\Traction\traction\server\settings.
- The part of the SPN you created above that refers to just the service account name. In our example, the full SPN is "HTTP/funzone.tractionsoftware.com@TRACTIONSOFTWARE.COM", so we enter "funzone.tractionsoftware.com". If you leave this blank, TeamPage will attempt to use a default based upon the canonical host name of the host computer, but this may not match its host name as far as your Windows environment is concerned, so we strongly recommend you just enter the correct name here instead of relying upon the default behavior.
- The Kerberos "realm", which is the same as the domain -- the part of the SPN you entered in ALL CAPS. In our example, this is "TRACTIONSOFTWARE.COM".
- Kerberos Server Password, which is the password set for the SPN on the command line. This will be required by Java's JAAS system to use the keytab file.
- Other settings can be configured as you see fit.
6. For other settings, you can use the defaults, but please review them to see whether there may be any that need adjusting. For example, you may decide you want to use a filter other than the default when looking up user accounts, or that you want TeamPage to refresh its local cache of AD user and group principal metadata more or less frequently than usual.
7. In the text input labeled "Save as", enter a good and descriptive name, and then click "Save".
8. Important. Although it is not currently possible to test the Kerberos authentication part of your custom user directory configuration, it is possible and very important to test the user and group lookup capabilities to make sure user accounts you expect to find can be found by TeamPage. After you click "Save" and the page reloads, click "Test" (next to "Save") to try out user and group. Make sure accounts you expect to find can be found (by sAMAccountName, display name, etc. -- however you configured your "Lookup User Search Expression" setting), as well as whatever groups you intend to use to manage permissions within TeamPage. If tests fail, close the test dialog and change whatever settings need adjusting, save again, and test again until the lookups work as expected.
Another important suggestion is that in case authentication does not work, and you have to revert to a default user directory, you should make sure that you have a TeamPage-only administrator account, not bound to an AD account, which you have the credentials for.
9. Close the user directory configuration dialog, and confirm that your newly created configuration is selected. Check the "Migrate Principals" checkbox if you're migrating from one of TeamPage's default user directories (i.e., if you're not just migrating from one existing AD configuration for the same AD environment to this new one). If you select the "Migrate Principals" checkbox, you'll be directed to a form where you can review the mappings TeamPage has found for existing TeamPage user accounts, and fix any that don't seem correct. Then click "Finish".
If everything was set up correctly, users should be able to log into TeamPage from their browsers with no prompting ("Seamless SSO"), but in some browsers, additional configuration may be required.
Windows Users and Kerberos Tickets
Users of Windows computers joined to the AD domain should not need to do anything to obtain or renew their "ticket granting ticket" (TGT) required for their systems to generate a ticket to send to TeamPage.
MacOS Users and Kerebros Tickets
Users of MacOS, unless otherwise joined to the domain in a way that allows their system to automatically retrieve and renew their TGT need to use the kinit command line tool. Additional steps may be required:
- The /etc/krb5.conf file must be updated to incorporate the correct settings so that kinit can identify what KDC to use for a domain. In our example, with the DC serving as the KDC located at win-g53k0e0grbo.tractionsoftware.com, the krb5.conf file may look something like this:
[libdefaults]
default_realm = TRACTIONSOFTWARE.COM
allow_weak_crypto = false
[realms]
TRACTIONSOFTWARE.COM = {
kdc = WIN-G53K0E0GRBO.tractionsoftware.com
}
[domain_realm]
.win-g53k0e0grbo.tractionsoftware.com = WIN-G53K0E0GRBO.TRACTIONSOFTWARE.COM
win-g53k0e0grbo.tractionsoftware.com = WIN-G53K0E0GRBO.TRACTIONSOFTWARE.COM
.tractionsoftware.com = WIN-G53K0E0GRBO.TRACTIONSOFTWARE.COM
tractionsoftware.com = WIN-G53K0E0GRBO.TRACTIONSOFTWARE.COM
[appdefaults]
pam = {
debug = true
ticket_lifetime = 86400
renew_lifetime = 86400
forwardable = true
krb4_convert = false
}
- DNS must be configured properly so that the KDC can be found, which if the Mac computer is not joined to the domain, may require an additional step.
In this example, the account password for "shep" is stored in the file ~/krb.pass so that it doesn't need to be entered on the command line; if the --password-file argument is omitted, the command will prompt the user for their password.
funzone (shep) ~ → kinit --password-file=./krb.pass --verbose shep@TRACTIONSOFTWARE.COM ✘ [1]
Placing tickets for 'shep@TRACTIONSOFTWARE.COM' in cache 'API:619284E9-DA92-43B2-BFCE-73A7CE819BBB'
funzone (shep) ~ → klist
Credentials cache: API:619284E9-DA92-43B2-BFCE-73A7CE819BBB
Principal: shep@TRACTIONSOFTWARE.COM
Issued Expires Principal
Jul 24 18:59:38 2023 Jul 25 04:59:38 2023 krbtgt/TRACTIONSOFTWARE.COM@TRACTIONSOFTWARE.COM
After the first TGT is obtained, the user may be omitted from the kinit command.
The klist command can be used to list tickets, including TGTs and any tickets obtained with the TGT.
The kdestroy command can be used to clear all tickets, including TGTs (use with care).
Browser Support
All major browsers support Kerberos authentication with "Seamless SSO".
- In IE11, or in Edge on the latest versions of Windows 10 and newer, users should be able to log into TeamPage with no prompting, and no additional configuration on the part of administrators, as long as the computer is joined to the domain.
- In Firefox, the TeamPage server address needs to be added to the "network.negotiate-auth.trusted-uris" setting. This can be done via the "about:config" page, although enterprises may also have a way to modify this setting across all users' computers. See this page for details.
- In Chrome on Windows, you may need to use the Chrome policy editor to enable Kerberos. See this page for details. On MacOS, users or administrators can use commands like the following to allow Chrome to use Kerberos for one or more domains:
defaults write com.google.Chrome AuthServerAllowlist funzone.tractionsoftware.com
defaults write com.google.Chrome AuthNegotiateDelegateAllowlist funzone.tractionsoftware.com
- In Safari on MacOS, as long as the user has used kinit to obtain the TGT for the right domain, no additional configuration is required.
