Configure Kerberos authentication on TEXTML Server

To enable Kerberos user authentication, you modify the 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 the 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.
  • Enables 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 Windows 2003 server (and up) with Active Directory.

To enable Kerberos authentication:

  1. 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
  2. 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
    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
  3. 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
  4. 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.
  5. 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. 
  6. To enable Kerberos delegation:
    If TEXTML Server service runs as: Enable Kerberos delegation as follows:
    Local service
    1. Open Active Directory Users and Computer.
    2. Find the computer account.
    3. Open the Properties dialog for the computer account.
    4. Click the Delegation tab.
    5. Select Trust this computer for delegation to any service (Kerberos only).
    6. Click OK.
    Another user or cluster
    1. Open Active Directory Users and Computer.
    2. Find the user account.
    3. Open the Properties dialog for the user account.
    4. Click the Account tab.
    5. 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.
    6. Click OK.
  7. On your TEXTML Server instance, navigate to the TextmlServerCfg.xml file:

    %ProgramData%\UserA\TextmlServer43

  8. Open the file, using a text editor such as Notepad.
  9. Set the <AuthenticateUsers> element value to True.
  10. Set the <AuthenticateUsingKerberos> element value to True.
  11. 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>
  12. 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 TEXTML Server Administration Guide for more information.