Introduction

The purpose of this document is to help diagnose and resolve 401 Errors for the K2.net 2003 or blackpearl Workspace when the Workspace components and the K2 Server components are installed on a single server.

Identifying the Problem

There are two types of 401 errors that you may encounter when working with the K2 Workspace. Since the error type generated depends on the circumstances, two sets of troubleshooting instructions are provided to resolve the two different error types.

The two types are:

  1. 3 strikes and you're out: This is characterized by getting prompted for credentials when trying to access the workspace and after 3 failed attempts to log on you receive a 401 unauthorized error.
  2. The Red 401: This is characterized by receiving a red 401 error message in the middle of the page when trying to access the workspace.
Note: Depending on which type of 401 error you are receiving follow the troubleshooting steps in the appropriate section below.

Troubleshooting "3 strikes and you're out" 401 errors

The cause for the error in this situation is that the Internet Information Service(IIS) is not authenticating the credentials provided. This can be because the credentials (username, password) are incorrect, or because the authentication method (basic, NTLM, Kerberos) is incorrect. Follow the steps below to first confirm that Internet Explorer (IE) is configured correctly and then confirm that IIS is configured correctly:

  1. Enable integrated authentication for IE
    1. From IE select Tools->Internet Options
    2. On the Advanced tab locate and enable the option: "Enable Windows integrated authentication"
  2. Add the workspace site to the list of Trusted Sites in IE
    1. From IE select Tools > Internet Options
    2. On the Security Tab select the Trusted Sites Zone
    3. Click the Sites button
    4. Type the Workspace URL into the text box and click Add
  3. Configure the Trusted sites security level to low and to automatically logon with username and password
    1. From IE select Tools->Internet Options
    2. On the Security Tab select the Trusted Sites Zone
    3. Click custom level
    4. Select Low from the drop down list and click Reset
    5. Under the User Authentication->Logon section select Automatically logon with username and password
  4. Confirm that IIS is configured correctly by following the steps in the following Microsoft KB article: http://support.microsoft.com/?id=871179

Troubleshooting "the red 401" errors

The cause in this situation is that the workspace application is unable to pass the user credentials to the web service that K2.net uses for reporting. Setting up Kerberos authentication will resolve the issue. In a single server environment Kerberos should not be required. The steps below attempt to help resolve the issue without setting up Kerberos but if after following all the steps you continue to get the error you might want to look into the possibility of setting up Kerberos. (see KB000123 for more information)

  1. Disable the loopbackcheck on the IIS server by following Method 1 in the following Microsoft KB article http://support.microsoft.com/default.aspx?scid=kb;en-us;896861  
  2. Give the "Authenticated Users" AD group Read/Write permissions to the "C:\WINDOWS\Microsoft.NET\Framework\< .NET Framework version >\Temporary ASP.NET Files" folder
  3. Configure Integrated Authentication for the IIS site
    1. Open IIS Manager
    2. Drill down to the web sites level
    3. Right click on the site that the workspace is installed under and select properties
    4. On the Directory Security tab make sure that only Integrated Authentication is checked
       
  4. Make sure that all the Virtual Directories under the K2V3 Virtual Directory are running under the same AppPool
    1. Open IIS Manager
    2. Drill down to the web sites level
    3. Expand the IIS site that the K2 Workspace is installed on
    4. Right click on the K2V3 virtual directory and select properties
    5. Note the application pool selection on the home directory tab
    6. Repeat steps (d) and (e) for each virtual directory under the K2V3 node and ensure that they are all using the same application pool
  5. Try using Network Service for the AppPool identity
    1. Open IIS Manager
    2. Drill down to the Application Pool level
    3. Right click on the Application Pool that K2 Workspace is using and select properties
    4. On the Identity tab select Network Service from the drop down and click ok
    5. Restart IIS for the changes to take effect
  6. Try using Local System for the AppPool identity
    1. Open IIS Manager
    2. Drill down to the Application Pool level
    3. Right click on the Application Pool that K2 Workspace is using and select properties
    4. On the Identity tab select Local System from the drop down menu and click ok
    5. Restart IIS for the changes to take effect
  7. Try using a Domain Service Account for the Application Pool identity
    1. Open IIS Manager
    2. Drill down to the Application Pool level
    3. Right click on the Application Pool that K2 Workspace is using and select properties
    4. On the Identity tab select to specify an account and enter the account information
    5. Restart IIS for the changes to take effect
      Note: The domain user that is running the Application Pool will need to be a member of the IIS_WPG local group on the server.
  8. Give the domain user that is running the Application Pool local admin permissions to the server
  9. Check the Execute Permissions for the K2V3 virtual directory
    1. Open IIS Manager
    2. Drill down to the web sites level
    3. Expand the site that the Workspace is installed under
    4. Right click on the K2V3 virtual directory and select properties
    5. On the Home directory tab make sure that the Execute permissions are set to "Scripts Only"
    6. Repeat steps d and e for all the directories that are under the K2V3 virtual directory
  10. Create a new site for the workspace
    1. Open IIS Manager
    2. Drill down to the IIS sites level
    3. Right click on the web sites folder and select New->web site
    4. Click next on the wizard welcome screen
    5. Type a name for the web site and click next
    6. Select a port that does not conflict with other sites on the server and click Next 
    7. Browse to c:\Inetpub and create a new empty folder called K2root to use as the default directory. Also uncheck the "Allow anonymous access" check box and click next
    8. Select "read" and "run scripts" and click next to finish the wizard
    9. Right click on the newly created site and select new->virtual directory
    10. Click next on the wizard welcome screen
    11. Enter K2V3 as the alias and click next
    12. Browse to "c:\Program Files\K2.net 2003\K2WS" or the corresponding blackpearl directory as the target directory
    13. Select "read" and "run scripts" and click next to finish the wizard
    14. Under the new site right click on the K2V3 virtual directory and select properties
    15. On the Home Directory tab click the "create" button to create the application and then also select an application pool for the virtual directory to run under
    16. Repeat steps n and o for the virtual directories under the K2V3 virtual directory
      Note: You will need to modify the webserver key in the web.config under the Workspace virtual directory to point to the new site. If this solution works then delete the old site to avoid confusion.

  11. Try adding the NTAuthenticationProviders tag to the site and setting it to NTLM
    1. Open a command prompt
    2. Navigate to c:\Inetpub\AdminScripts
    3. Run the following command where xx is the identification number for the web site. (you can find the identification number in IIS manager by selecting the web sites folder and looking in the right hand pane)
    4. cscript adsutil.vbs set w3svc/xx/NTAuthenticationProviders "NTLM"
  12. Try adding the NTAuthenticationProviders tag to the site and setting it to Negotiate,NTLM
    1. Open a command prompt
    2. Navigate to c:\Inetpub\AdminScripts
    3. Run the following command where xx is the identification number for the web site. (you can find the identification number in IIS manager by selecting the web sites folder and looking in the right hand pane)
    4. cscript adsutil.vbs set w3svc/xx/NTAuthenticationProviders "Negotiate,NTLM"
  13. Try deleting the NTAuthenticationProviders tag for the site
    1. Open IIS Manager
    2. Right click on the server name and select properties
    3. Check the "Enable direct Metabase edit" check box and click ok
    4. Open Windows Explorer
    5. Navigate to "C:\WINDOWS\system32\inetsrv"
    6. Open Metabase.xml in notepad
    7. Search for "NTAuthenticationProviders" and delete the entry that shows up for the site that workspace is installed under
    8. Save the file and restart IIS