Integrated Windows Authentication

There are two ways to authenticate users in HEAT:

Window Integrated Security: Uses Windows credentials. This option is only available for the on-premise version of HEAT. The user's computer must be a member of the Windows domain.

Direct AD Authentication: Uses the identify provider of the customer. This option is available for the on-premise and Cloud versions of HEAT. Users must log in each time, although they can save their credentials within their browser.

Users can access authentication either by going directly to the identity provider (such as active directory, SAML, or OpenID), or by logging into HEAT (which then redirects the user to the identity provider).

The identify provider authenticates the user but does not share credentials.
The identify provider session is separate from the HEAT session, and must be configured separately.
The identify provider is configured separately and according to the specific identify provider process.

The following illustrates how active directory authentication works:

Active Directory Authentication

Configuring HEAT and Windows Integrated Security

This describes how to configure HEAT active directory authentication using Windows Integrated Security (WISWindows Integrated Security. Uses the security features of Windows clients and servers and the current Windows user information on the client computer.). This feature allows users to access HEAT without entering their user name and password. This procedure is only valid for the on-premise version of HEAT.

1.

Within the ConfigDB tenant, open the Tenants workspace. The available tenants are listed.

2.

Open the HEATSM tenant by clicking the company name on the line with the HEATSM tenant. The Tenants page appears.

3.

In the Login Url field, enter the URL where users go to log in.

4.

Click Save.

5.

Log into HEAT as administrator in a separate browser window or tab.

6.

Open the Authentication Provider workspace (from either the Service Desk Console or Configuration Console).

7.

Click New Record Menu and select New Windows Integrated. The Windows Integrated window appears.

8.

Enter information into the fields.

--fields--

Field	Description
Default	Automatically generated by the system. The default value is false.
Disabled	Saves this configuration without activation.
Name	The provider name, such as WISWindows Integrated Security. Uses the security features of Windows clients and servers and the current Windows user information on the client computer..
Identity Server URL	The path to your identity server, such as /HEAT/WIS.
Logout URL	The URL that users are directed to when logging out of the authentication provider.
Sort Order	Specifies the sort order of this provider in relation to other providers assigned to a user. A value of 1 means this provider is used first for authentication when logging in. If a login failure occurs (server failure or incorrect password), the next provider in the sort order is used. The last successfully authenticated login is highlighted in the Enable External Auth area of the Employee record. Use this field only if multiple authentication providers are configured.
Certificate of customer's Windows Integrated server	Only applies to public certificates. Click Browse to navigate to the certificate.
Expiration Date	Specifies the date that the certificate expires. This field merely stores the date so that you can see when the current one expires and get another certificate before or when it expires.
Auto Provisioning	Adds new users via authentication. You have the option to auto provision the role, status, and team for the new user. If selected, an Employee record is created if an user logs in using authentication and does not already have an Employee record.

9.

Open the Employee workspace (as administrator), then open an employee record.

10.

Modify an existing employee by enabling External Auth and specifying Login for External Auth as the newly created Windows Integrated authentication provider.

Check Enable External Auth and Click Add New ...

Enter the Name of your Windows Integrated Authentication Provider

11.

Click Save

from the toolbar.

12.

Log out. The Login page appears with Sign in with WIS.

Sign In with WIS

13.

Next to Login for External Auth, click Add New. The New External Login window appears.

If the window does not appear, then Windows authentication is disabled for Windows Integrated Security.

14.

Click Sign in with WIS. The Windows sign-in window appears.

15.

Enter your user name and password, then click OK.

Cloud authenticated the user using the WISWindows Integrated Security. Uses the security features of Windows clients and servers and the current Windows user information on the client computer. system.

If auto provisioning is enabled in new authentication provider, you can skip step 6. HEAT creates a new employee with external authentication enabled and the login for external authentication is specified as the Windows integrated authentication provider.

Configuring HEAT and Windows Integrated Security for External Authentication

The lifecycle for external authentication using a Windows Integrated Security provider is as follows:

Windows Integrated Security receives an authentication SAML request from HEAT.
Windows Integrated Security validates the request and checks the certificates.
Windows Integrated Security creates the SAML response.
Windows Integrated Security signs the SAML response with the certificate specified in the Web.config file.
Windows Integrated Security enables auto provisioning in the SAML response using LDAP configuration from the Web.config file.
Windows Integrated Security posts the SAML response back to the Cloud.

Windows Integrated Security is configurable in the Web.config file. You can specify whether an external authentication request from HEAT should be validated and its certificate checked. To skip the authentication request validation, do not specify the heatCertificatePath application setting in the Web.config file.

Validating Incoming Authentication Requests

1.

The HEAT tenant may be marked with an ADFS private certificate. To check or specify it, open the ConfigDB tenant and specify the ADFS private certificate and its password for each corresponding tenant.

Set the ADFS Certificate for Each Tenant

2.

Open the Web.config file with a text editor (such as NotePad), and set the heatCertificatePath setting to a path relative to the public certificate. This is used on the Windows Integrated Security side for validating HEAT requests.

…

</appSettings>

…

</configuration>

If the heatCertificatePath setting is specified incorrectly or if there is no such directory or file, then an unhandled exception is thrown during the validation process. For example:

produces:

Server Error Example

If you do not see an error message, then the validation of the external authentication succeeded.

Configuring Windows Integrated Security for Auto Provisioning

The Windows Integrated Security Web.config file may contain the LDAP server and active directory LDAP queries used for retrieving data needed for auto provisioning:

First name
Last Name
Email
LoginId

After windows authentication Windows Integrated Security performs the LDAP search with parameters given in the Web.config file:

</configSections>

</ldapConfiguration>

…

All ldapConfiguration parameters are required.

ldapConfiguration should contain server, userName and password for LDAP connection. Also, it should contain rootNode and filter for LDAP search. If any options are not specified, then the LDAP connection or search fails and auto provisioning does not work for the Windows Integrated Security authentication provider. As a result, HEAT Cloud cannot create a new employee on external authentication.

ldapConfiguration is a custom configuration section, so it should be added to the configSections collection.

Configuring Windows Integrated Security Provider to Sign its Response with a Certificate

The HEAT authentication provider may be marked with a public certificate. See Configuring HEAT and Windows Integrated Security. This reduces the ability of external sites to send the authentication requests to HEAT and successfully authenticate. It also means that only requests signed with the corresponding private certificate result in a successful authentication.

You can configure the Windows Integrated Security provider with a private certificate, by doing the following:

Open the Web.config configuration file for the Windows Integrated Security site.
Specify the wisCertificatePath application setting and name of the private certificate.
Specify the wisCertificatePassword secure application setting for the certificate password.

For example:

…

</configSections>

…

</appSettings>

…

</secureAppSettings>

…

</configuration>

Note that wisCertificatePassword should be specified in the secureAppSettings custom configuration section. It contains the password for the private certificate so it can be encrypted to reduce the possibility of password leak.

Also note that secureAppSettings is a custom configuration section, so it should be added to the configSections collection in the Web.config file as shown in the example above.

If the authentication provider is marked with a public certificate and the Windows Integrated Security site is not configured with a private certificate:

The private certificate password wisCertificatePassword is not specified in the Web.config file.
The private certificate password is incorrect.
The private certificate name wisCertificatePath is not specified in the Web.config file.
The private certificate name is specified incorrectly.

then the external authentication fails.

Failed External Authentication

At same time, if the HEAT authentication provider is not marked with a public certificate and Windows Integrated Security configured with the private certificate, then the HEAT external authentication succeeds and the user is redirected to the default page.

Configuring the Server to use Windows Authentication

By default, the Windows Server and local server of Windows OS are not configured to use Windows Authentication. So you cannot use Windows Integrated Security to perform Windows authentication for HEAT external authentication.

Windows Authentication on the IIS Web Server

To enable Windows authentication on IIS web server, do the following:

1.

Within Windows, go to Control Panel > Programs > Turn Windows features on or off.

Turn Window Features On or Off

A list of features appears.

2.

Expand Internet Information Services, then go to World Wide Web Services > Security, then check Window Authentication.

Windows Authentication - Web

3.

Click OK, then close the window.

Windows Authentication on the Windows Server IIS Web Server

To enable Windows authentication on Windows Server IIS web server, do the following:

1.

Within Windows, right-click Computer, then choose Manage. The Server Manager opens.

2.

Expand Roles, right-click Web Server (IIS), then choose Add Role Services. The Add Role Services window opens.

3.

Expand Security, select Windows Authentication, then click Install.

Windows Authentication - Server

Enabling for WIS

After Windows authentication is enabled on the server, enable it for WIS:

1.

From the Windows search box, type inetmgr. The IIS Manager window opens.

2.

Go to MachineName > Sites > Default Web Site > HEAT > WIS.

3.

In Features View, select Authentication.

4.

Right-click Windows Authentication, then choose Enable.

5.

Disable all other authentication types.

Enable Windows Authentication

Testing

To test, log into HEAT with external authentication using the WIS authentication provider. If Windows Authentication was installed correctly, then the default window should appear.

Successful Windows Authentication Install

Setting the Default Provider

Designate an authentication provider as the default to ensure the correct configuration is accessed by users.

1.

Log into the Service Desk console as Administrator, and open the Authentication Provider workspace. The list of configured providers are listed.

2.

Select the provider you want to make the default, then click Set Default from the toolbar.

Set the Default Authentication Provider

Only one provider can be the Default.

Configuring Windows Integrated Security to Work in Debug Mode

Using Windows Integrated Security in debug mode shows you all configurations used in WIS, and errors that occurred during validation of a SAML request or construction of a SAML response. You can easily determine the cause of failed external authentication using this method.

WIS in debug mode shows the following information:

Request validation information.
SAML request in XML format.
LDAP server information.
Auto Provisioning block – LDAP search result parameters and attributes.
SAML response certificate.
SAML response in XML format.

To enable debug mode for Windows Integrated authentication provider, do the following:

1.

Log into HEAT and open the Authentication Provider workspace.

2.

Double-click to open the Windows integrated authentication provider record. See Authentication Providers.

3.

Identity Server Url Add a debug parameter to the URL.

/HEAT/WIS/Default.aspx?debug=true

4.

Click Save

from the toolbar. Log out.

5.

Log in using Windows integrated authentication provider, using the windows user name and password.

The Windows Integrated Security debug mode page appears.

Windows Integrated Security Debug Mode Page

The following links appear on this page:

More ... Hides/shows the SAML request or SAML response.
Private certificate Is used for the signature of the SAML response. This downloads the corresponding public certificate.
Post This button posts the SAML response to HEAT to the corresponding AssertionConsumerHandler.

SAML Request Validation

If the authentication request validation fails, the Post button is disabled and users cannot perform external authentication with the Windows Integrated Security provider. An error message appears:

SAML - Authentication Request Error Message

LDAP Configuration

If ldapConfiguration is not specified in the Web.config file, then an error message appears in the debug log. It means that auto provisioning does not work in this scenario for the Windows Integrated Security provider. For detailed information see Configuring Windows Integrated Security for Auto Provisioning above. The user still has the ability to perform external login without auto provisioning and post SAML responses to HEAT.

LDAP - Authentication Request Error Message

SAML Response Signature

If Windows Integrated Security is configured in the Web.config file to sign the SAML response with the private certificate, then an error might occur if the wrong certificate password is specified. The error message appears in the debug log.

Note that the SAML response is created anyway, but does not have a signature. Posting this SAML response back to HEAT fails.

SAML Response - Failed Authentication

Disabled Windows Authentication

If IIS is not configured to perform Windows authentication or Windows authentication is not enabled for Windows Integrated Security, then external authentication with the Windows Integrated Security provider fails.

Windows Authentication Fails

Encrypted Config Sections in the Web.config FIle

The Web.config file of the WIS application may contain passwords for:

LDAP server configuration
private certificate password

To reduce the possibility of password leak at the servers where WIS is deployed, some config sections in Web.config may be encrypted.

For detailed information see the MSDN article at http://msdn.microsoft.com/en-us/library/zhhddkxy(v=vs.100).aspx.

EncryptWebConfig.bat uses RsaProtectedConfigurationProvider for encryption. So once the Web.config section is encrypted at one computer or server, it can’t be used in another server. The Windows Integrated Security application throws an unhandled exception in this case.

Integrated Windows Authentication in Browsers

Windows Authentication works differently in browsers. Firefox will ask you to login each time you access the site with Windows Authentication, while Internet Explorer and Chrome browsers only ask you to login the first time.

Internet Explorer

If the Windows Integrated Security site is not located in local IIS web server, you must add it to the list of trusted sites.

Go to Tools > Internet Options > Security > Trusted sites > Sites and add the site.

If the Windows Integrated Security site is located on local IIS web server, then you do not need to make changes in the security options, since local intranet sites use the “Automatic logon in Intranet zone” option by default.

Firefox

Config method:

Firefox provides a configuration string which can be modified to enable this functionality:

1.

Open a new tab in Firefox.

2.

In the address bar, enter about:config. A Proceed with Caution message appears.

3.

Click Agree. The configuration page loads.

4.

In the search box, enter network.automatic.

5.

Double-click the row containing network.automatic-ntlm-auth.trusted-uris, then enter http://<your-intranet-server-name> or http://<www.your-site.com>.

Multiple sites can be added separated by commas, such as http://<your-intranet-server-name>, http://<www.your-site.com>.

To specify all subdomains, use .your-site.com instead of www.your-site.com, help.your-site.com, or pictures.your-site.com.

Extension method:

The Firefox extension can be used instead of configuring the about:config file when you need to work with a site with NTLM authentication. Such extension is called integrated authentication for Firefox. Install the extension, restart Firefox, and then in the Tools menu, a new option appears (called integrated authentication sites) that lets to add or remove entries. As per the manual method, only the http:// prefix and the hostname of the server should be included. There is no trailing slash nor a path to any particular page. Authentication is enabled on a per-site basis.

Chrome

Chrome takes its trusted site settings from the same internet options as Internet Explorer.

Go to Settings > Show advanced settings > Change proxy settings > Security > Trusted Sites > Sites and add the site.

You will be asked to login the first time you access the trusted site.