Authentication across applications, including Dovetail Mobile / AgentLite
We’ve worked with a couple of customers recently who use some other application for authentication. Basically, Single Sign-On. One was using CA SiteMinder, and another had a home grown application. In both instances, we were able to easily allow Dovetail Mobile / AgentLite to work with their existing authentication mechanisms, allowing single sign-on capabilities. This means that if a user has already authenticated in their environment, then they were automatically logged into Dovetail, without having to enter their username and password again. Pretty nice user experience.
In this post, I’ll share some of the details about how this all works.
For this scenario, our customer had a home grown “App Store”. Users logged into this App Store, which authenticates them, and then shows them a list of applications that they are authorized to use. One of them is Dovetail Mobile.
The customer’s App Store application is an ASP.NET web application that uses forms based authentication. Dovetail Mobile also uses ASP.NET forms based authentication. Which means that we can take advantage of forms authentication across applications.
ASP.NET supports forms authentication in a distributed environment, either across applications on a single server or in a Web farm. When forms authentication is enabled across multiple ASP.NET applications, users are not required to re-authenticate when switching between the applications.
Flows
Lets see this in action.
To test this out, I built a very simple “App Store” app that does forms based authentication using a simple XML file as a membership provider.
I browse to the login page (which is part of the App Store) and login. I then see my list of available apps, which includes Dovetail.
Clicking that app automatically logs me into Dovetail. No additional authentication necessary.
Lets see that in action: (Video Link)
Another common flow is that the user browses to the Dovetail app, but they aren’t yet authenticated. That flow looks like:
- Unauthenticated user browses to Dovetail app
- User is redirected to the login page (which is part of the App Store app)
- User logs in
- Authenticated user is automatically redirected back to the original requested page (Dovetail) and can access the app.
Lets see that in action: (Video Link)
Configuration
To set this all up, it’s mostly a configuration exercise. To configure forms authentication across applications, you set attributes of the forms and machineKey sections of the Web.config file to the same values for all applications that are participating in shared forms authentication.
A Tale of Two Applications
The first application is the App Store app, which is the app that performs the authentication. Its URL ishttp://app.company.com
The second application is Dovetail Mobile. Its URL is http://dovetail.company.com
Authentication Config
In the App Store (which performs the authentication), we configure the forms section within the web.config like so:
<system.web>
<compilation debug="true" targetFramework="4.0" />
<authentication mode="Forms">
<forms name=".ADAuthCookie" loginUrl="~/Account/Login"
defaultUrl="~/" protection="All" timeout="30" slidingExpiration="true"
path="/" cookieless="AutoDetect" enableCrossAppRedirects="true" domain=".company.com">
<credentials passwordFormat="SHA1" />
</forms>
</authentication>
A couple things to take note of:
- loginUrl: this is the path to the login page. The fully resolved path would be http://app.company.com/Account/Login
- domain: Since the two apps need to share an authorization cookie, the domain needs to be set with a leading dot. This allows the authentication cookie to be available to subdomains (i.e. a cookie created on app.company.com is available to dovetail.company.com)
Dovetail Config
In the Dovetail app, we configure the forms section within the web.config like so:
<system.web>
<authorization>
<deny users="?" />
</authorization>
<authentication mode="Forms">
<!-- The name, protection, and path attributes must match exactly in each Web.config file. -->
<forms
name=".ADAuthCookie"
loginUrl="http://app.company.com/account/login"
defaultUrl="~/"
protection="All"
timeout="21600"
slidingExpiration="true"
path="/"
cookieless="AutoDetect"
enableCrossAppRedirects="true"
domain=".company.com" />
</authentication>
A couple things to take note of:
- loginUrl: this is the path to the login page – which is part of the App Store app.
- domain: again, the domain needs to be set with a leading dot.
- The name, protection, and path attributes must match exactly in each Web.config file. Here, we’ve matched them to the App Store config.
Machine Key
We also need to ensure the machineKey for Dovetail Mobile is in sync with the app store machineKey.
In the Dovetail web.config file, within the system.web element, add:
<machineKey
decryptionKey="94222F033F0A4759E6FFCA4A0F02F31290D37935F1EFBDB5"
validationKey="C03B9555F16851C764665C9FDF07D3D660821EACA33E0D40EEA775D0956DFDCCA95E23D82FD71FE4A3544EE6CA886460CC9252C8075DB1FBFD8224AD0BF6549F"
validation="SHA1" />
Note: Use your own keys! Not the ones above! Those are just examples!
The name, protection, path, validationKey, validation, and decryptionKey attributes must be identical across all applications. Similarly, the encryption and validation key values and the encryption scheme and validation scheme used for authentication tickets (cookie data) must be the same. If the settings do not match, authentication tickets cannot be shared.
To access and generate a machine key:
- From IIS Manager, click on the top level server node in the left pane.
- In the main panel, under ASP.NET, click on Machine Key
Changes so far
So far, we haven’t made any changes to the app other than configuration. The code has remained unchanged. But we do have a couple of scenarios that we need to code for, that aren’t handled by configuration alone.
- Unknown Users
- Redirects across different servers
Unknown Users
If a user authenticates via the app Store, but is an unknown user in Dovetail, then by default the user is redirected back to the login page. They can login in again, it will redirect them to Dovetail, where Dovetail would redirect them back to the login page again (as they aren’t a valid user in Dovetail). A seemingly infinite login loop without the user knowing what’s going on. This isn’t good. Instead, we’ll create an Unknown Agent page which tells the user what happened and what they should do.
Redirects across different servers
One other scenario that the .NET configuration doesn’t handle properly is the redirect to a different server.
Given this flow:
- Unauthenticated user browses to Dovetail app
- User is redirected to the login page (which is part of the App Store app)
- User logs in
- User is automatically redirected back to the original requested page (Dovetail)
When the user is redirected to the login page, we can look at the URL and we’ll see a ReturnURL querystring parameter. Such as this:
http://app.company.com/appstore/Login.aspx?ReturnUrl=%2fdovetail
This tells the authentication app where to return the user to once the user is authenticated.
But, notice that it’s a relative, not a full URL. The correct ReturnURL should be http://dovetail.company.com/
This is a common problem that many have run into, and it doesn’t seem to be able to be resolved just with config. So a small code change was necessary. Something like this.
Summary
In general, the majority of everything worked with just some config settings. We had to add code to handle a few specific edge cases, but for the most part, it just works.
What I dig is how easily we were able to integrate into an existing authentication application, and improve the end user experience. Sweet!
Rock on.
