Sunday, April 12, 2009

K2 blackpearl Kerberos Configuration

1 - Introduction

Recently I went through another Kerberos configuration and I promised myself after going it I would write something about it. I have had to do Kerberos configurations several times and it seems that every time I do it something changes. Luckily it is not just me who has this experience so I do not feel too bad.


I am not a security expert nor am I a network engineer. There are tons of blogs and articles that explain Kerberos however I am going to try to make this simple. When installing K2 or MOSS you may need to configure Kerberos to get around authentication issues associated an account's credentials being passed between applications that reside on different physical servers. For example:

  • Application A is on Server A.
  • Application B is on Server B.
  • A user logs into Application A on Server A and needs to use Application B services that are on Server B.
  • Application A needs to pass the user's credentials from Server A to Server B so that Application B can authenticate against that account without requiring another login.

Kerberos is required to resolve the issue commonly referred to as the "double hop" issue. If you ever see errors like "NT AUTHORITY/ANONYMOUS LOGON" or "401 - Access Denied" you are experiencing an issue that can be resolved by configuring Kerberos authentication. When receiving an error like this, what is happening is Application A does not have permission to delegate user credentials to Application B which resides on Server B. Because there is no permission to delegate permissions from one machine to another, Application B subsequently defaults to using an anonymous login which is not sufficient for most applications.

To resolve this issue a level of trust needs to be created such that service accounts are trusted to pass a user's credentials from one machine to another.

  • First, a combination of service type and machine, and service account will be registered with the domain controller.
  • Second, a service account will then be given permission to pass user credentials to a specified registration (service type, machine, and service account).

In the case of K2, Kerberos authentication is always required once the K2 topology becomes dispersed across multiple servers. A common scenario is when SharePoint and K2 are not installed on the same physical servers.

Setting up Kerberos authentication should not be confused with Single Sign-On (SSO). SSO is used for storage of multiple username and passwords and then allowing the user to only log in once. Since all of the credential information is stored centrally then a broker will use those stored credentials to log the user into another application without having them to type in a different username and password. This is typically used so that the user does not have to remember multiple username and passwords to access systems.

In following sections I will discuss setting up Kerberos for K2 blackpearl. In part two of this series I will discuss Kerberos considerations for SharePoint. Setting up Kerberos authentication in a SharePoint environment is considered to be a best practice and provides better security than NTLM. It is also common to have to configure Kerberos with SharePoint when working with SQL Reporting services (SSRS).

2 - K2 and Kerberos


As mentioned before, you will need to set up Kerberos authentication for K2 when it is distributed across many servers. The major components are that can be distributed are:

  • The K2 Host Server
  • SQL Server
  • SharePoint
  • SQL Reporting Services
  • K2 Workspace web site

The K2 Getting Starting documentation is really good. A good portion of the following documentation comes from it however I have re-organized it a little and identified a few gaps.


2.1 - K2 and SQL Server


It is possible to have K2 blackpearl and SQL Server sitting on different machines and not require Kerberos authentication. The K2 Service account needs to have access to the access to SQL Server to access the various K2 databases; that is it.

2.2 - K2 Host Server


In the K2 Getting Started instructions, it states that you will need to run the following commands:

  • setspn -A K2Server/MachineName:5252 domain\K2 Service Account
  • setspn -A K2Server/MachineName.FQDN:5252 domain\K2 Service Account
  • setspn -A K2HostServer/MachineName:5555 domain\K2 Service Account
  • setspn -A K2HostServer/MachineName.FQDN:5555 domain\K2 Service Account

You will need to run these commands regardless of how you plan to distribute your K2 environment.


To verify the spn commands you ran:


  • setspn -L domain\K2 Service Account

This command states which machines the K2 Services Account can delegate from. It is good to run this periodically so you do not get lost while doing this.

The following picture shows the following Kerberos delegations that could be required based on the distribution of the K2 environment. The numbers correspond to sections below.


2.3 - K2 and SharePoint

A common scenario is that K2 Host Server and the SharePoint server will not reside on the same machine. If that is the case the following commands need to executed.

  • setspn -A HTTP/MachineName domain\SharePoint Service Account
  • setspn -A HTTP/MachineName.FQDN domain\SharePoint Service Account

Notes:


  • The MachineName is the name of the server where SharePoint resides. If there is an alias for the SharePoint site the MachineName will be the DNS entry. If you have multiple web front end servers (WFEs) in the SharePoint farm that are load balanced it is not required to run the above commands for each physical machine. For example if the SharePoint DNS entry is http://mymossfarm/, then the setspn command would be HTTP/mymossfarm. Make sure that this name is configured in DNS as an A Record and NOT an alias (CName).
  • The SharePoint Service Account refers to the service account for the application pool that SharePoint is running under.

Now that the spn has been set up for the SharePoint WFE we need to:

  • Go to Administrative Tools >> Active Directory Users and Computers.
  • Search for the SharePoint Service Account, open properties, go to the Delegation tab, and select the "Trust this user for delegation to specified services only" option. Then select the "User Kerberos only" option.

  • Press the add button, search for the K2 Service Account and select both the K2Server and K2HostServer Service Types. These were created in section 2.2.
  • Click ok and ok again.
  • Finally you will need to go to Central Admin of SharePoint >> Application Management >> Authentication Providers. Then in the default zone you will set the IIS Authentication Settings to use "Negotiate (Kerberos)". You will need to do an IIS reset for the changes to take effect.

In the delegation tab, what we basically did was say that the SharePoint Service Account is allowed to delegate credentials to the K2 Service Account only. Hopefully that can simplifies your understanding of what is going on.

You may be wondering why you had to do all of this. If you do not, K2 commands that are generated from SharePoint will not be trusted by the K2 Host Server. For instance the K2 task list web part, a web service call from web enabled InfoPath, etc. will not be trusted by the K2 Host Server. If you were to run the K2 Service from command line and not do any of the configurations above you would see a bunch of "NT AUTHORITY/ANONYMOUS LOGON" errors.

Debugging Note - There can be no duplicate SPN entries created. Uniqueness is defined by the combination of service and machine name. Examples of a service to this point are K2Server, K2HostServer and HTTP. A common mistake is to set up SPNs for the same service and machine with multiple service accounts. You will not receive an error when using the setspn command however Kerberos will not work if this is done. Some tools are discussed later that will help uncover these sort of issues.

Unusual Error – I had a painful experienced recently when configuring a K2 environment. We had followed all of the instructions correctly but we were still getting "NT AUTHORITY/ANONYMOUS LOGON" errors when watching the K2 Host Server via command line. Our solution was to select the "Use any authentication protocol" option instead of the "User Kerberos only" option in the Delegation tab. We lost days trying to figure this issue; unknowingly thinking that the only valid option was to select "User Kerberos only".

When doing some research on this option I found that the "Use any authentication protocol" option, meant that "the account can use the protocol transition extension to obtain a service ticket enables it to obtain service tickets to a pre-configured subset of kerberized services". I needed some more clarification and a colleague of mine (Jason Montgomery) sent me the following, "For Kerberos to function, a user's computer needs to be able to contact the Key Distribution Center (KDC) directly in order to get a Ticket to pass along to the Web Site they would like to authenticate with. If the user is outside the network and doesn't have network access to the KDC (Domain Controller), Protocol Transition allows the user to authenticate using any windows authentication protocol (Client Certificates, Forms Auth, Token, proprietary, etc). Once the user has authenticated, the Protocol Transition Extension allows the Service to retrieve a Ticket from the KDC on behalf of a user to itself. From this point on, the Service will be to properly pass the users ticket along to other tiers where required allowing the system to function as designed." He further explained "In your case having Protocol Transition setup didn't work because the Service needs first authenticate the user then call LsaLogonUser or use WindowsIdentity to obtain the token using the S4USelf extension (i suspect they are using the normal Kerberos proxy delegation or S4UProxy extension). If the K2 Service doesn't use the S4USelf extension during Auth then configuring K2 to use Protocol Transition will always fail". That was much lower that I had expected to go, however my tip is sometimes if Kerberos is still not working, try changing the Kerberos delegation to use the "Use any authentication protocol" option.


2.4 - K2 and K2 Workspace

When K2 and the K2 Workspace are placed on different servers, Kerberos authentication will need to be configured between the K2 Workspace and the K2 Host Server. In many cases I personally tend to keep the K2 Workspaces on the same machine as the K2 Host Server. The reason being is that the K2 Workspace is typically only opened up to a few power users and administrators. It is full of a ton of administrative functionality and I typically equate it to Central Administration for SharePoint.

Before continuing note that many occasions I have seen the same account used for both the K2 Service and the K2 Workspace Service. It is still required that you set up an SPN because delegation is going across physical servers and that is why Kerberos is required.

  • If you have not done section 2.2; complete that first.
  • setspn -A HTTP/MachineName domain\K2 Workspace Service Account
  • setspn -A HTTP/MachineName.FQDN domain\K2 Workspace Service Account
  • Go to Administrative Tools >> Active Directory Users and Computers.
  • Now search for the K2 Workspace Service Account, open properties, go to the Delegation tab, and select the "Trust this user for delegation to specified services only" option. Then select the "User Kerberos only" option.
  • Press the add button, search for the K2 Service Account and select both the K2Server and K2HostServer Service Types.
  • Click ok and ok again.

We have now given the K2 Workspace Service Account permission to pass user credentials to K2 Service Account. Otherwise you will get a bunch of 401 errors in the K2 Workspace web site.

2.4.1 K2 Workspace IIS Metabase


Next you need to update the IIS Metabase. The changes will be made to IIS in order to allow Kerberos authentication for the K2 Workspace web site.

  • Open IIS Manager.
  • Right click the top node and select properties.
  • Check the Enable Direct Metabase Edit checkbox.
  • Click ok a few times and finish.
  • Get the K2 Workspace Site Identifies from the IIS Manager. Click on top node and in right main window, there will be a Site Identifier number. That number will be used in the following commands.
  • Open a command line window and cd C:\Inetpub\AdminScripts
  • Next you need for force IIS to use Kerberos instead of NTML. Run the following commands
    • cscript adsutil.vbs set w3svc/NTAuthenticationProviders "Negotiate,NTLM"
    • cscript adsutil.vbs set w3svc/Site Identifier/NTAuthenticationProviders "Negotiate,NTLM"

2.5 – SharePoint and K2 Workspace


If SharePoint and the K2 Workspace are not on the same server, Kerberos authentication needs to be set up such that the SharePoint Service Account and delegate to the RuntimeServices web services that are hosted within the K2 workspace.

  • You must set up the SPN that were described in section 2.3.
  • At a minimum make sure to complete the first three bullets on Section 2.4 (even if both K2 Host Server and the K2 Workspace are on the same machine.
  • Go to Administrative Tools >> Active Directory Users and Computers.
  • Now search for the SharePoint Service Account, open properties, go to the Delegation tab, and select the "Trust this user for delegation to specified services only" option. Then select the "User Kerberos only" option.
  • Press the add button, search for the K2 Workspace Service Account and select the HTTP Service Type.
  • Click ok and ok again.

2.6 - K2 and SSRS


Another common scenario is that SSRS will already be installed somewhere. The following configurations are required.

Note - This can be avoided by installing SSRS on the machine where the K2 Host Server resides. This is possible because SSRS is a web site can be installed anywhere. Be warned, that if you do this, you will need to pay another SQL Server License because Microsoft deems this as another install of SQL Server.

2.6.1 SSRS to K2

The Reporting Services Service Account is the account which the SSRS web site runs under in the IIS Application Pool. This is needed to ensure that the account that being used to access a report is verified against the K2 Host server. For instance if K2 SmartObject Data Provider is used in a SSRS report, the account needs pass the K2 Host Server.

Complete the following:

  • If you have not done section 2.2; complete that first.
  • setspn -A HTTP/MachineName domain\Reporting Services Service Account
  • setspn -A HTTP/MachineName.FQDN domain\Reporting Services Service Account
  • Go to Administrative Tools >> Active Directory Users and Computers.
  • Now search for the SSRS Service Account, open properties, go to the Delegation tab, and select the "Trust this user for delegation to specified services only" option. Then select the "User Kerberos only" option.
  • Press the add button, search for the K2 Service Account and select only the K2HostServer Service Type.
  • Click ok and ok again.

2.6.2 K2 to SSRS


Another thing you will need to do is to allow the K2 Host Server service account to schedule SSRS reports. Now the K2 Host Server needs to be able to delegate to the SSRS Service Account. You will not need to run any spn commands because you have then all done at this point. You need to do the following:

  • Search for the K2 Service Account, open properties, go to the Delegation tab, and select the "Trust this user for delegation to specified services only" option. Then select the "User Kerberos only" option.
  • Press the add button, search for the SSRS Service Account and select the HTTP Service Type.
  • Click ok and ok again.

2.6.3 - K2 Workspace to SSRS

To add one more wrinkle to this, if you have the K2 Workspace and SSRS sitting on different servers, you need to allow the K2 Workspace to delegate use credentials to SSRS. This is because SSRS reports are embedded directly into the K2 Workspace.

  • If you have not done section 2.4; complete that first.
  • At a minimum, complete the first three bullets of 2.6.1.
  • Go to Administrative Tools >> Active Directory Users and Computers.
  • Search for the K2 Workspace Service Account, open properties. On the Delegation tab both "Trust this user for delegation to specified services only" and "User Kerberos only" options should already be selected.
  • Press the add button, search for the SSRS Service Account and select only the HTTP Service Type.
  • Click ok and ok again.

2.6.4 SSRS IIS Metabase


Next you need to update the IIS Metabase. The changes will be made to IIS in order to allow Kerberos authentication for the SSRS web site.

  • Open IIS Manager.
  • Right click the top node and select properties.
  • Check the Enable Direct Metabase Edit checkbox.
  • Click ok a few times and finish
  • Get the SSRS Site Identifies from the IIS Manager. Click on top node and in right main window, there will be a Site Identifier number. That number will be used in the following commands.
  • Open a command line window and cd C:\Inetpub\AdminScripts
  • Next you need for force IIS to use Kerberos instead of NTML. Run the following commands
    • cscript adsutil.vbs set w3svc/NTAuthenticationProviders "Negotiate,NTLM"
    • cscript adsutil.vbs set w3svc/Site Identifier/NTAuthenticationProviders "Negotiate,NTLM"

5 - Still Having Issues - Kerberos Configuration Tool


Download this tool; this helped me out tremendously after going through the Kerberos configuration and validating if I had set up everything correctly. It took a little bit to get the hang but it works great.

You only need to install it on one machine in the farm. What you can do is modify the parameters and it will tell you if there are any issues with Kerberos authentication between machines.


Some other tools that were recommended to me which I have not used are ldifde.exe and spnquery.vbs.


6 - Recommendations

My recommendation is place the K2 Host Server, K2 Workspace and SSRS on the same machine. SharePoint should be installed on its own dedicated environment. The SSRS install is only created to support K2 SSRS reports. This will only require you to complete sections 2.2, 2.3 and 2.5.


7 - References


8 - Credits


I also had some reviewers which helped me out.

No comments: