Windows¶

When the Windows authenticator plug-in is installed, the Curity Authentication Server supports Integrated Windows Authentication (IWA), enabling users to login using either Kerberos or NTLM. This allows users to login with an existing session they obtained when logging into their Windows workstation; when a session isn’t yet established, users are also able to login using their normal Windows login. With this feature, organizations can provide single sign-on to their Windows users, and reduce the number of credentials that users must manage.

IWA support is provided in part by the Windows Connector, an agent that runs on a domain-joined Windows Web server. The Windows Connector is a separate application, and must be installed and configured separately from the Curity Authentication Server. It runs on a Windows Server that has the Web role (i.e., IIS) installed. The overall architecture is shown in the following diagram:

Fig. 94 IWA architecture

Installing the Windows Connector¶

To install the Windows Connector, perform the following steps:

Make sure that your Windows Web server has ASP.NET 3.5 or higher enabled.
Copy the files located in $INSTALL_DIR/misc/windows-connector to the Windows Web server.
Configure a Web site within IIS to use the physical path of the directory to where the files where copied. This web site need not necessarily be the default Web site; however, the Windows Connector must be installed in the root of the Web site. It cannot be served from an application, virtual directory, or sub-directory within a site.

Caution

Ensure that the worker process for this Web site has read access to this directory.

Configure IIS to allow overriding authentication in the web.config file by doing the following:
1. Open the file %windir%\system32\inetsrv\config\applicationHost.config in Notepad or the like.
2. Find the sectionGroup element with a name attribute that has the value system.webServer. Under this element will be another sectionGroup with a name of security. This, in turn, will have a sectionGroup called authentication. Within this, you will find a few section elements. For the ones with the name attributes of windowsAuthentication and anonymousAuthentication change the overrideModeDefault to Allow.
  
  Hint
  
  The XPath expression of this configuration element is “/configuration/configSections/sectionGroup[@name = ‘system.webServer’]/sectionGroup[@name = ‘security’]/sectionGroup[@name = ‘authentication’]/section[@name = ‘windowsAuthentication]’
3. Below the security element but still within the system.webServer element, you will find another element named httpErrors. Make sure that the value of lockAttributes is blank or at least does not include defaultPath.

Configuring an Authenticator¶

In order for IWA to work, an authenticator needs to be configured. This can be done like any other authenticator. Specifically, you need to add an authenticator of type windows. The ID is arbitrary but will be reflected in the URLs that the user’s browser accesses and the configuration in the Windows Connector. There are two required settings and one optional that may be configured:

The URL of the Windows Connector
The symmetric key that will be used to encrypt messages exchanged between the Windows Connector and the Curity Authentication Server.
An optional fail-over authenticator to use when IWA is not possible (e.g., because a user is not on a domain-joined workstation).

windows-connector-url¶

This setting is the URL of the Windows Connector as setup previously in IIS on the Windows Server machine. This URL should use HTTPS, and should use a valid certificate that will not display any errors or warnings to the user. This URL should also be in the list of trusted sites in Internet Explorer. An optional port may be included if the default port for the scheme is not used (e.g., 8443 instead of 443). This URL must be a valid absolute URL or the configuration will not be accepted.

symmetric-key¶

A shared secret that will be used to encrypt messages sent between the Windows Connector and the Curity Authentication Server. Even though the communication between these two entities will be encrypted when SSL is used, it is also encrypted and signed using this pre-shared master key. Communication will fail if this exact same key is not configured in the Windows Connector (see below).

fail-over-authenticator¶

When a user is not on a domain-joined computer or IWA fails for some reason, it is possible to fail over to some other authenticator. This can be any authenticator that is configured in the Curity Authentication Server. With this flexibility, it is possible to require additional factors of authentication and create a secure login for remote users or users that are surfing with a browser that does not support IWA. To set the fail-over authenticator, simply reference an existing authenticator. When IWA fails, this authenticator, if set, will automatically be shown. If this setting is not configured, the user will receive an access denied error when IWA fails.

Configuration Example¶

<authenticator>
    <id>win1</id>
    <windows xmlns="https://curity.se/ns/conf/authenticators/windows">
        <windows-connector-url>https://ad.example.com/<windows-connector-url>
        <symmetric-key>MyGoodPassword</symmetric-key>
        <fail-over-authenticator>html-with-sms-otp</fail-over-authenticator>
    </windows>
</authenticator>

Configuring the Windows Connector¶

The Windows Connector includes a web.config file. There are a few settings in this file that need to updated to match your deployment. To set them, do the following:

Open the web.config file in Notepad or the like.
In the configuration element, locate the appSettings element. This should have an add element with a key of crypto.key. Set the value attribute to have the same symmetric key that you used in the Curity Authentication Server configuration. This should be a random key that is not reused across your various environments (i.e., use different keys in production and non-production).
Set the add element with a key of idsvr.url to have a value of the authenticate endpoint for the authenticator you created previously. This URL will depend on the authentication endpoint you configured in the authentication profile.
Do a find a replace for the URL https://localhost:8443/dev/authn/anonymous/win1. Replace all occurrences of this URL with the scheme, host name, port, and URI of your instance of the Curity Authentication Server.

Troubleshooting¶

Because the Windows Connector automatically redirects all requests back to the Curity Authentication Server, it can be difficult in the default configuration to diagnose problems. To troubleshoot issues more easily, follow these tips.

Using the Request Log in the Curity Authentication Server¶

When the request log is enabled, which it is by default, it will include details about every request that is made to the Curity Authentication Server. These messages include the resulting status code and all request parameters (both form and query string parameters) that were included in the request. When an error occurs in the Windows Connector, the same error code will be reported and displayed in the Curity Authentication Server. In some cases, an additional sub-error code will also be reported to the Curity Authentication Server; this error code and sub-error code are the ones reported from IIS, and will be shown in the request parameters of the request log. This can be useful for debugging issues in IIS without having to change anything in the Curity Authentication Server. The request log is located in $IDSVR_HOME/var/log/request.log by default. A request sent from the Windows Connector will look something like this (but without the additional whitespace added for readability):

2016-05-30 16:48:11 INFO  {qtp2001115307-38}
    se.curity.identityserver.app.RequestReceiver:116
    accept="text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
    client="0:0:0:0:0:0:0:1"
    content-type="text/html; charset=UTF-8"
    lang="en"
    method="GET"
    params="{statusCode=[500], subStatusCode=[50]}"
    protocol="HTTP/1.1"
    size="32768"
    status="500"
    uri="/dev/authn/anonymous/win1/error/"

From this example, you can see that IIS reported error 500.50 to the Curity Authentication Server. These errors and their causes can be found in the IIS documentation.

Enable Tracing of the Windows Authenticator in the Curity Authentication Server¶

If more information is needed to diagnose a problem, you can increase the log level of the Windows authenticator plug-in. This will cause more information to be written to the server.log file. This can be helpful when debugging message encryption and communication issues. To do this, follow these steps:

Open the log4j2.xml file in a text editor. By default, this file is located in $IDSVR_HOME/etc.
Enable trace level tracing for the se.curity.identityserver.plugins.authenticators.windows logger. This will show the responses from the Windows Connector, including error codes, subcodes, and cryptographic data. A sample of the logger that should be added is this:

<AsyncLogger name="se.curity.identityserver.plugins.authenticators.windows" level="TRACE"/>

After adding this logger configuration to the log4j2.xml file and restarting the server, you should see many messages from the Windows authenticator when you make a login attempt.

Danger

Do not enable this log except for when troubleshooting. Enabling it will severely impact performance and cause very sensitive information to the written to the logs.

Enable Tracing in IIS¶

In addition to tracing in the Curity Authentication Server, additional logs can be written in the Windows Connector. To enable these, do the following:

Open web.config in Notepad or the like.
Locate the trace element in the system.web section of the config file.
Change the enabled attribute to have a value of true instead of the default of false.

After enabling tracing, make a request to the Curity Authentication Server for Windows authentication. After the request reaches the Windows Connector, various information will be added to the IIS trace log. To view it, surf to <windows connector host>/Trace.axd> in your browser, where <windows connector host> is the scheme (e.g., HTTPS), hostname and port of the IIS server that hosts the Windows Connector.

If you also enable trace-level logging of the Windows authenticator in the Curity Authentication Server, all of the cryptographic data used by both will be shown in their respective logs. This can be essential for debugging complicated communication issues.

Danger

Do not enable this log except for when troubleshooting. Enabling it will severely impact performance and cause very sensitive information to the written to the logs.

Disable ASP.NET Errors in IIS¶

When an error occurs in IIS that is generated from an ASP.NET Web page, the default behavior of the Windows Connector is to redirect the browser back to the Curity Authentication Server. This behavior can easily be changed, allowing an admin or developer to view the actual ASP.NET error. To do this, perform the following changes:

Open web.config in Notepad or the like.
Locate the customErrors element in the system.web section of the config file.
Change the mode attribute to have a value of off instead of the default of on.

With this change, ASP.NET errors will be reported at IIS and the request won’t automatically be redirected back to the Curity Authentication Server.

Disable HTTP Errors in IIS¶

The above tip only causes IIS to show errors that are generated from ASP.NET code, like the C# code included in the Windows Connector source files. Any error generated from another source in IIS will still cause the user to be redirected to the Curity Authentication Server. To avoid this and have IIS report the errors directly, do the following:

Open web.config in Notepad or the like.
Find the httpErrors element in the system.webServer section of the config file.
Change the errorMode attribute to have a value of Detailed instead of the default of Custom.

After making this change, errors, such as access denied errors from the Windows authentication provider, will be displayed directly in IIS, and the browser will not redirect back to the Curity Authentication Server.