iMIS Shared Forms Auth Setup and Configuration

Overview

This article will show you how to change the iMIS web.config settings to create a shared Forms Authentication environment.

Applies To

This article applies only to iMIS 2017 / 20.x on-premise. iMIS 20.3, iMIS Cloud, and any future versions no longer rely on forms authentication technology.

What is Forms Authentication?

Forms Authentication is a technology developed by Microsoft that, essentially, uses an encrypted cookie with a username inside of it in order to determine who is logged in.

To the end user, the cookie may look like this:

Name	Value
Login	`09043CE89A0................................................AFE07110A65D`

But when the server decrypts the cookie, the following data is available inside in what is known as the forms authentication ticket:

Key	Value
Name	The username of the current user.
Expiration	The time after which this forms auth ticket expires.
IssueDate	The time at which this forms auth ticket was created.
Version	The protocol version of Forms Authentication that this ticket is compatible with. (This value is almost always "2".)
UserData	A custom string that can be set for the user. Note that iMIS 2017 uses this internally by setting this value to a serialized JSON object, and if this object does not exist, iMIS will reject the ticket and sign the user out.

Shared Forms Authentication

Since the forms authentication ticket is just an encrypted cookie value, it is possible to share the cookie/ticket with more than one website.

If two or more websites operating on the same base domain have the same Forms Auth configuration settings, they can share login information and user sessions.

Configuring iMIS in Shared Forms Authentication Mode

iMIS 2017 uses forms authentication to sign the user in and keep track of user sessions.

It is possible to make some (safe, non-breaking) configuration changes to the web.config file in order to put iMIS into a shared forms auth mode. These changes are required if you want to use the Cloud SSO in forms authentication identity mode.

Standard / Out of the Box Values

Let's look at a standard iMIS 2017 installation with no modifications.

OOTB web.config

XML

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  ...
  <system.web>
    ...
    <authentication mode="Forms">
      <forms name="Login" timeout="50000000" loginUrl="~/AsiCommon/Controls/Shared/FormsAuthentication/Login.aspx" requireSSL="true" />
    </authentication>
    ...
    <httpCookies httpOnlyCookies="true" requireSSL="true" lockItem="true" />
    ...
  </system.web>
  ...
</configuration>

The changes we need to make are:

The <forms> tag needs the base domain.
The <machineKey> tag is missing (see below for how to generate one).
The <httpCookies> tag is missing the base domain.

Let's pretend that our base domain is example.org. We need to make the following changes.

Add the domain=".example.org" attribute to the <forms> tag.
Add the domain=".example.org" attribute to the <httpCookies> tag.
Generate a valid <machineKey> tag.
- To generate a machine key definition, click here and copy the line of code that it produces. Paste it alongside/below your <authentication> tag (see below for an example).
  - Each time you visit that link, new values are generated, so your generated keys are secure/random.

Base Domain Tip

When dealing with forms authentication, and cookies in general, the domain must start with a dot ("."). In the example above, the correct value is ".example.org" (note the leading dot). An incorrect value would be "example.org" (missing the leading dot). Ensure that your domain values begin with "."!

If we apply our changes to the sample web.config values above, we end up with this:

Shared Forms Auth web.config

XML

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  ...
  <system.web>
    ...
    <authentication mode="Forms">
      <forms name="Login" domain=".example.org" timeout="50000000" loginUrl="~/AsiCommon/Controls/Shared/FormsAuthentication/Login.aspx" requireSSL="true" />
    </authentication>
    ...
    <machineKey validation="SHA1" decryption="AES" validationKey="D812558AF9C4D91113B9AE87036AC91ECEBFC9EF" decryptionKey="72BC545A59CA6ECE5EE5BA53D4EA233A318A587E33A556960E63A62336481018" />
    ...
    <httpCookies httpOnlyCookies="true" domain=".example.org" requireSSL="true" lockItem="true" />
    ...
  </system.web>
  ...
</configuration>

Changes to ASI Scheduler

Important!

It is always important to keep certain ASI Scheduler web.config values in sync with those in iMIS / RiSE. Please do not skip this step!

The changes made above also need to be applied into the ASI Scheduler web.config. Of note, please make sure the values for these keys are the same between iMIS and the scheduler:

<authentication> / <forms>
<machineKey>
<httpCookies>

It is OK to simply copy and paste these values from the iMIS web.config to the Scheduler web.config.

Additional Values to Verify

In the web.config file, there are a few other values that need to be checked.

Legacy Forms Authentication Mode(s)

If any of these values are set in the <appSettings> section, remove these values. These values are not compatible with the Cloud SSO, and additionally, these values cause your Forms Authentication security to be weaker and easier to break by brute force.

aspnet:UseLegacyFormsAuthenticationTicketCompatibility
aspnet:UseLegacyEncryption

Machine Key Compatibility Mode

The <machineKey> element can contain the following tag: compatibilityMode="..."

Depending on a number of factors, including which versions of .NET are installed/active on the server and other factors, this tag may either be required or must not be present.

Important!

All connected applications using Forms Authentication (that are sharing the same login cookie) must have this value match. If you are not using shared forms authentication with any other apps, then changing the iMIS and ASI Scheduler web.config files is sufficient.

First, try removing the attribute altogether and test the SSO to see if it can read the cookie.

If it does not work with the tag off, add: compatibilityMode="Framework20SP2"

Your resulting machine key should look something like this:

Machine Key with Compatibility Mode

XML

<machineKey validation="SHA1" decryption="AES" validationKey="D812558AF9C4D91113B9AE87036AC91ECEBFC9EF" decryptionKey="72BC545A59CA6ECE5EE5BA53D4EA233A318A587E33A556960E63A62336481018" compatibilityMode="Framework20SP2" />

Again, make sure the iMIS and ASI Scheduler lines match. Then test the SSO again.

One of these configurations should allow the Cloud SSO to work. If not, please contact CSI Support for further instructions.

Entity Manager Base URI

The Entity Manager Base URI needs to match and be pointed to the same "primary" domain that iMIS is running on (with the ASI Scheduler path on the end), and the same domain that forms auth cookies are issued from.

It cannot be:

A different base URI
An internal server URL or localhost

Entity Manager Base URI Setting

XML

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  ...
  <iMIS>
    ...
    <Soa>
      ...
      <settings>
        ...
        <setting key="EntityManagerDefaultBaseUri" value="https://imis.example.org/Asi.Scheduler_SAMPLEIMIS" />
        ...
      </settings>
      ...
    </Soa>
    ...
  </iMIS>
  ...
</configuration>

Scheduler Warning

If you change this value, you must also set the same value in the ASI Scheduler web.config file!

iMIS Web Server URL

The iMIS web server URL app setting needs to match the same "primary" domain that iMIS is running on (with the iMIS net folder path on the end - typically "/EXAMPLEIMIS").

It cannot be:

A different base URI
An internal server URL or localhost

iMIS Web Server URL Setting

XML

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  ...
  <appSettings>
    ...
    <add key="ImisWebServerUrl" value="https://imis.example.org/SAMPLEIMIS" />
    ...
  </appSettings>
  ...
</configuration>

Scheduler Warning

If you change this value, you must also set the same value in the ASI Scheduler web.config file!

iMIS Desktop Verification

If you are on an earlier version of iMIS 2017 (roughly SP K or earlier), some iMIS Desktop users may be using an internal server URL to connect to iMIS.

When configuration Shared Forms Authentication, iMIS desktop must be updated to use the fully-qualified URL to connect to the server. You cannot use a server name or localhost, and you must use HTTPS.

URL Check

The iMIS Desktop URL is correct if:

It starts with HTTPS
It contains a fully qualified URL ending in a TLD (com/net/org/uk/au, etc)
It ends with /cs (usually)

Later versions of iMIS 2017 enforce this requirement already, and in these cases, iMIS Desktop should continue to function normally.

Verifying Your Changes

To verify your changes, save all web.config files and recycle both (iMIS and scheduler) app pools.

Sign into the iMIS staff site and open your browser's Developer Tools (typically F12).

Go to Application > Cookies > .example.org and find your login cookie. The "Domain" column should read ".example.org" if everything is configured correctly!