Configure Kerberos authentication on TEXTML Server

To enable Kerberos user authentication, you modify the IXIASOFT TEXTML Server configuration.

Understanding Service Principal Names

To use Kerberos authentication, you need to create Service Principal Names (SPN) for the server in the Active Directory. The SPN is a unique identifier that must be created for each service that will use Kerberos authentication, so that clients can locate it over a network. The SPN is assigned to the account that is running TEXTML Server. The account that you assign it to depends on your configuration:

If the TEXTML Server service runs under the "Local Service" (default) or "System" account, the SPN is assigned to the NetBIOS name of the machine (for example, machinename@acme.local). Note that the TEXTML Server service should not run as the Local Service if one of the following conditions apply:
- TEXTML Server is installed in a Windows cluster,
- There are multiple Active Directory Forests in the network, or
- An Active Directory Forest includes many domains
If the TEXTML Server service is running as another user, the SPN is assigned to this user name (for example, myusername@acme.local). This user name must be unique in the Active Directory.
If the TEXTML Server service is running in a cluster, the SPN must be assigned to the user name (for example, myusername@acme.local) and not the machine name, so that it can still be reached in case of a cluster failover.

The SPN is the name that users will enter when they add a server to an administration console.

Note: Kerberos delegation must also be enabled on the computer or user account.

When enabled, Kerberos authentication is performed each time a user attempts to connect to a TEXTML Server instance. For more information about Kerberos, see Microsoft's article at the following URL:

http://msdn.microsoft.com/en-us/library/ms178119(v=sql.105).aspx

This procedure:

Creates Service Principal Names (SPN) for the TEXTML Server service in the Active Directory of the Kerberos server.
TEXTML ServerEnables Kerberos delegation for the machine or user account.
Enables TEXTML Server authentication in the TEXTML Server configuration.

Prerequisites

Kerberos authentication requires that TEXTML Server runs on a recent version of Windows server with Active Directory.

The following commands must be run using Administrator privileges in an elevated command prompt.

To enable Kerberos authentication:

On the Kerberos server, run the following command to create an SPN for the TEXTML Server service:

setspn -A TextmlServer/<MACHINE-NAME>:<port-number> <account>

where:

Option	Description
`<MACHINE-NAME>`	is the NetBIOS name of the machine, in uppercase (for example, `WRITIX`)
`<port-number>`	is the port number on which TEXTML Server listens (for example, `2500`)
`<account>`	is one of the following: If the TEXTML Server service runs under the "Local Service" (default) or "System" account, enter the NetBIOS name of the machine. If TEXTML Server is running as another user, enter the user name (for example, `myusername@acme.local`). If the TEXTML Server service is running in a cluster, the SPN must be assigned to the user name (for example, `myusername@acme.local`)

For example, if TEXTML Server is running on machine WRITIX, enter the following commands:

If TEXTML Server service runs as	Enter:
Local service	`setspn -A TextmlServer/WRITIX:2500 writix`
another user	`setspn -A TextmlServer/WRITIX:2500 textmlserveruser@acme.local`
in a cluster	`setspn -A TextmlServer/WRITIX:2500 textmlserveruser@acme.local`

A message similar to the following is displayed:

Registering ServicePrincipalNames for CN=WRITIX,CN=Computers,DC=acme,DC=local
        TextmlServer/WRITIX:2500
Updated object

Run the command again, this time providing the fully qualified domain name (FQDN) for the TEXTML Server machine, as follows:

setspn -A TextmlServer/<MACHINE-NAME>.<FQDN>:<port-number> <account>

This will ensure that the TEXTML Server machine can be reached no matter how it is accessed. For example:

If TEXTML Server service runs as Enter:

Local service

If TEXTML Server service runs as	Enter:
Local service	`setspn -A TextmlServer/WRITIX.example.local:2500 writix`
another user	`setspn -A TextmlServer/WRITIX.example.local:2500 textmlserveruser@acme.local`
in a cluster	`setspn -A TextmlServer/WRITIX.example.local:2500 textmlserveruser@acme.local`

setspn -A TextmlServer/WRITIX.example.local:2500 writix

another user

setspn -A TextmlServer/WRITIX.example.local:2500 textmlserveruser@acme.local

in a cluster

setspn -A TextmlServer/WRITIX.example.local:2500 textmlserveruser@acme.local

Repeat steps 1 and 2 if the TEXTML Server machine can also be reached through an alias.
For example, if the WRITIX machine also has the DOCXML-SERVER alias, run the following commands:
```
setspn -A TextmlServer/DOCXML-SERVER:2500 writix
setspn -A TextmlServer/DOCXML-SERVER.example.local:2500 writix
```
To confirm that the SPNs were created correctly, enter:
```
setspn -L <account>
```
For example:
```
setspn -L writix@acme.local
```
A message similar to the following is displayed, listing the existing SPNs defined for the account:
```
Registered ServicePrincipalNames for CN=WRITIX,OU=Peoples,OU=Company,DC=acme,DC=local:       
        TextmlServer/WRITIX.acme.local:2500       
        TextmlServer/WRITIX:2500
        TextmlServer/DOCXML-SERVER.acme.local:2500       
        TextmlServer/DOCXML-SERVER:2500
```
The next step checks to see if there are duplicates SPNs defined for the TEXTML Server machine. If more than one SPN is defined for TEXTML Server, Kerberos authentication will fail.
To verify that there are no duplicates SPNs, enter:
```
setspn -F –X
```
If a message similar to the following is displayed (see bold):
```
Checking forest DC=acme,DC=local
Operation will be performed forestwide, it might take a while.
Processing entry 

TextmlServer/WRITIX.acme.local:2500 is registered on these accounts:       
  CN=UserA,OU=Peoples,OU=Company,DC=acme,DC=local       
  CN=WRITIX,CN=Computers,DC=acme,DC=local 
TextmlServer/WRITIX:2500 is registered on these accounts:       
  CN=UserA,OU=Peoples,OU=Company,DC=acme,DC=local       
  CN=WRITIX,CN=Computers,DC=acme,DC=local 

found 2 groups of duplicate SPNs.
```
Then the TEXTML Server SPN is assigned to more than one account. For example, in the message above:
- The TextmlServer/WRITIX.acme.local:2500 SPN is assigned to two users: UserA@acme.local and WRITIX@acme.local.
- the TextmlServer/WRITIX:2500 SPN is assigned to two users: UserA@acme.local and WRITIX@acme.local.
You need to remove the duplicate SPNs, otherwise Kerberos authentication will fail.
To remove a duplicate SPN:
1. Enter the following command:
```
setspn -D TextmlServer/<MACHINE-NAME>:<port-number> <machine-account>
```
  For example, to remove the SPNs assigned to UserA, enter the following command:
```
setspn -D TextmlServer/WRITIX.acme.local:2500 UserA
setspn -D TextmlServer/WRITIX:2500 UserA
```
2. To confirm that the duplicate SPNs have been removed, run the following command again:
```
setspn -F –X
```
  A message similar to the following is displayed, showing that TEXTML Server duplicates are no longer there:
```
Checking forest DC=acme,DC=local
Operation will be performed forestwide, it might take a while.
Processing entry 

found 0 group of duplicate SPNs. 
```

To enable Kerberos delegation:

If TEXTML Server service runs as:	Enable Kerberos delegation as follows:
Local service	Open Active Directory Users and Computer. Find the computer account. Open the Properties dialog for the computer account. Click the Delegation tab. Select Trust this computer for delegation to any service (Kerberos only). Click OK.
Another user or cluster	Open Active Directory Users and Computer. Find the user account. Open the Properties dialog for the user account. Click the Account tab. In the Account options area, make sure that the Account is sensitive and cannot be delegated is not enabled. If it is selected, unselect it. Click OK.

On your TEXTML Server instance, navigate to the TextmlServerCfg.xml file:

%ProgramData%\IxiaSoft\TextmlServer44
Open the file, using a text editor such as Notepad.
Set the <AuthenticateUsers> element value to True.
Set the <AuthenticateUsingKerberos> element value to True.
In the <Security> element, set the <ServerAdmin> and <ServerUser> elements to the names of the groups that contain all your users.
For example:
```
 <ServerAdmin>
   <value NAME="Everyone"/>
</ServerAdmin>
<ServerUser>
   <value NAME="Everyone"/>
</ServerUser>
```
Save and close the file.

You must now configure who can access TEXTML Server. This is achieved by configuring TEXTML Server security through roles and permissions. See the Administration Guide for IXIASOFT CCMS for more information.