Changes to Documentation in Version 3.1

If you are installing version 3.0, continue on this page under the section Single Sign-On for Version 3.0.

If you are installing version 3.1 or above, please see the new documentation here: FastClose Server Authentication Introduction

Single Sign-On for Version 3.0

FastClose can be configured to authenticate users via a traditional username / password challenge known as ‘FastClose authentication’ or it can use ‘Windows Authentication’ which uses their Windows domain username to identify a user. Because the user has already had to provide their credentials to Windows, they are deemed to have already proven their identity.

Using Windows Authentication means that it is no longer necessary for the user to provide a password to run FastClose and they are not challenged with a user login dialog either in the FastClose client software or when using FastClose server web pages.

Configuring the Server

The authentication system is set by editing the appsettings.customersettings.json file, which for a default installation can be found in C:\Program Files\FastClose\FastCloseServer.

Editing this file requires administrator privileges. This can be achieved by launching Notepad from an instance of PowerShell launched with Administrator rights.

Important: When you save this file after editing you must change the name to appsettings.customer.json

FastClose Authentication

This is the default option and no configuration changes should be required to enable this mode.

Within the json file it is configured like this:

{
	...
	"AuthenticationOptions": {
		"UserAuthenticationType": "FastClose",
		"AdministratorSetupIdentity": "",
		"IsHostedByIIS": false
	}
}

Windows Authentication

To enable Windows Authentication (single sign on), you must alter the appsettings.customer.json file to let the server know to authenticate users via Windows.

In appsettings.customer.json change the value of UserAuthenticationType to Windows Change the AdministratorSetupIdentity to the domain user name of an administrative user on the domain who will add the initial FastClose users into the system.

{
	...
	"AuthenticationOptions": {
		"UserAuthenticationType": "Windows",
		"AdministratorSetupIdentity": "YELLOWSTONE\\Adam",
		"IsHostedByIIS": false
	}
}

Important: Restart the FastClose Server service to enable windows authentication mode after editing and saving appsettings.customer.json.

NB: If the FastClose Service has been to set launch under a specific user or system account (usually to facilitate logging into SQL Server as a specific account) it may be necessary to assign more privileges to that account to enable the service to launch under Single Sign On. A symptom which would indicate this would be if FastClose doesn't respond to a web browser (giving something like Connection Refused), then it may not have started properly even though the service display may say it has. The solution is to make the account being used for the service a member of the "Administrators" group on the Windows server.

Setting Up Initial FastClose Users for Single Sign-On

Once windows authentication is enabled visit the home page of the web server. The user’s domain username should be visible in the top-right hand corner. For example:

At this point, the only user that will be able to use the server is the AdministratorSetupIdentity as configured above.

The first task is to create at least one other administrator via the Users page. Subsequently, any of those administrators can create other standard users, using their Windows domain username. For example:

Domain\Username needs to be the exact windows domain name and username. It is case insensitive.

Username is used for the name of the user's personal reports folder in FastClose. It can be any unique value.

If the authentication mode is ever reverted to use FastClose native authentication, users will still be able to login with the Username value (i.e. without the domain). In this scenario, all users will have the same password and that password can be obtained from FastClose support.

Once additional administrator users have been created the AdministratorSetupIdentity is obsolete – it is only used for bootstrapping new Windows users in FastClose.

Important: If the identity used is the name of an intended user of FastClose it is important to go back to the appsettings.customer.json and reset the AdministratorSetupIdentity to “”. If this is not done, that user will be associated with the built-in Administrator account by the client software when they log in and their personal reports will be created in the wrong places as well as granting them permanent administration rights.

Additional Step for sites using the Scheduler / Worker Service: To allow the Worker Service to authenticate with the FastClose Server there needs to be a user configured in the repository that has the same service account as the account the Worker Service is running under eg: "NT AUTHORITY\SYSTEM", so ensure one is configured.

IIS Hosted FastClose Server

The FastClose web server can be hosted within IIS rather than as its own service if wished. There is separate documentation on how to do this.

Both FastClose authentication and Windows authentication will work under IIS hosting. To ensure the server runs properly under IIS hosting change the configuration option IsHostedByIIS to true in appsettings.customer.json

{
	...
	"AuthenticationOptions": {
		...
		"IsHostedByIIS": true
	}
}

IIS must also be configured to match the settings in appsettings.customer.json otherwise the server will not run. The authentication mode in appsettings.customer.json must match the authentication mode in IIS. The following table shows valid configurations for app settings and IIS settings:

The following image shows the correct configuration in IIS for Windows authentication.

Configuring Clients

There is no specific configuration required on clients to make them work with Windows authentication.

When Windows authentication is enabled on the server, FastClose Designer and Reader desktop clients are logged in automatically based on the currently logged in user's Windows domain username and there is no username / password challenge.

The Excel Add-In requires the user to press the login button in the ribbon to start the login process but again there is no username / password challenge.

The Reader web app does not support Windows Authentication at this time.

If there are issues logging in, then the Login form will be displayed with an error message. The user can select a different server or retry the login process.

Troubleshooting

If you are switching between authentication modes, then the website cookies need to be cleared otherwise you may see yourself still logged in as a windows user in FastClose authentication mode and vice versa. To delete cookies in Chrome, open the ‘Developer tools’ window, navigate to the Application tab, click Cookies and click Clear All.