Garrett's Tech Musings

Out of the box, Active Directory Federation Services (AD FS) 2.0 comes bundled with several endpoints to support different protocols (WS-Trust, WS-Federation, etc.), credential types, and security modes.  These endpoints are used for communication to the STS so if you have an application that needs to receive tokens via WCF, you can connect to one of the provided endpoints depending on your security and transport requirements.

AD FS 2.0 Endpoints

Customizing the Passive Federation Site

The endpoint that many developers will encounter the most is the Passive Federation endpoint.  This is the URI that a user will be redirected to when trying to authenticate with a Windows Identity Foundation (WIF)-enabled site.  In other words, this is the AD FS login page.

So what happens if you want to customize this site?  Well, the official documentation describes how you can easily configure three things in the sign-on pages: the accepted authentication types, the theme (CSS) of the site including the logo, and finally the “behavior and layout” of the sign-on pages.  There are extension points for creating your own pages as well as modifying the existing ones.

In this posting, I won’t go into the details of the library used to make these customizations (Microsoft.IdentityServer) but needless to say, you have the ability to control many aspects of the AD FS login process.

Changing the Passive Federation Endpoint URL

Once you’ve decided to customize the login site, it would also be nice to change the location of the site so you’re not stuck with the hard-wired URI (/adfs/ls).  In my case, I wanted to simply keep the existing site in place (for backup and testing purposes) while putting in a newly customized STS login site.

Since there’s no way to change the endpoint URI within the management console, you need to update the AD FS configuration, which is conveniently stored in a database column as a single XML file in Windows Internal Database (WID)! Have no fear.  I’ve written a SQL script (see below) to make this update process much simpler.

Connecting to Windows Internal Database (WID)

The first thing you’ll need to do is to connect to the Windows Internal Database (WID) instance on your machine.  As of the RC of AD FS, the settings are no longer stored in an external SQL Server or SQL Server Express database.  Instead, AD FS utilizes WID, which is simply SQL Server running with limited rights and visibility within Windows Server.

To connect, open SQL Server Management Studio (if you’re running this in Windows 2008, be sure to run it as an Administrator) and enter \\.\pipe\mssql$microsoft##ssee\sql\query as the server name.  Yes, that’s the connection string.  It seems like a bit of a hack getting into it, but this is well documented (it’s even on Wikipedia!) so don’t be afraid.

Windows Internal Database Connection

Updating the Endpoint

Once you’ve connected, you can execute the script below to change the address of the Passive Federation endpoint.  A couple of notes first:

1. Standard disclaimer: This is a database update script so be sure that you’ve either backed up the database or made a copy of the settings so that you can roll back if necessary.
2. Set the @EndPointAddress variable to the desired address of your STS login page.
3. If you want to just see the configuration results before committing the changes, set the @Debug variable to 1 (true).

USE AdfsConfiguration
GO

--
-- Variables
--
DECLARE @Settings XML
DECLARE @EndPointAddress VARCHAR(255)
DECLARE @Debug BIT

-- Set the new Passive Federation location here(original='/adfs/ls')
SET @EndPointAddress = '/PassiveFederationSite'

-- Set this to true(1) if you only want to see the changes and not apply them
SET @Debug = 0

--
-- Convert the settings to XML data type
-- so we can more easily work with it.
--
SET @Settings =
(
  SELECT CAST(
    REPLACE(ServiceSettingsData, 'encoding="utf-8"', '')
	AS XML) AS x
  FROM IdentityServerPolicy.ServiceSettings
)

-- Update settings in XML
SET @Settings.modify('replace value of
(/ServiceSettingsData/SecurityTokenService/PassiveEndpoint/@Address)[1] with
sql:variable("@EndpointAddress")')

-- Convert new settings back to NVARCHAR
DECLARE @NewSettings NVARCHAR(MAX)

SET @NewSettings =
'' +
CAST(@Settings AS NVARCHAR(MAX))

IF @Debug = 1
BEGIN
  SELECT @NewSettings
  SELECT @Settings.query
    ('/ServiceSettingsData/SecurityTokenService/PassiveEndpoint')
END
ELSE
BEGIN
  DECLARE @ObjectId UNIQUEIDENTIFIER
  DECLARE @ServiceSettingsVersion BIGINT

  -- Get the latest settings data
  SELECT TOP 1 @ObjectId = ServiceSettingId,
    @ServiceSettingsVersion = ServiceSettingsVersion
  FROM IdentityServerPolicy.ServiceSettings
  ORDER BY LastUpdateTime DESC

  --
  -- Execute stored procedure to update settings
  --
  EXEC IdentityServerPolicy.UpdateServiceSettings @ObjectId,
    @NewSettings, @ServiceSettingsVersion
END

Some Notes on the Script

1. The removal of the “utf-8″ encoding string is necessary for the configuration to be properly converted into the SQL Server XML type.  Without using the XML data type, this script would have been a lot more complex.
2. In addition to updating the configuration settings, the UpdateServiceSettings stored procedure increments the version column and updates the LastUpdatedTime column.  The version column (as far as I can tell) is only used for handling update conflicts.

Wrapping Up

Once the script has been run, the changes will be instantaneous in AD FS.  There’s no need to restart the service.  To roll back to the original URI, just set @EndpointAddress to “/adfs/ls” and rerun the script!

I’ve started writing for my company’s blog: Under the Hood.  I’ll still regularly post here to my blog, but definitely hop over there to check out the wide range of articles from my co-workers at Ironworks.

It could just be a coincidence, but I ran across this message board posting where somebody suggests that Microsoft name their product “Windows Identity Foundation”.  However, this was three years ago!  It’s nice that somebody followed up recently with a little “congratulations on your suggestion” posting, but I wonder if the original poster even realizes that his suggestion is now the official name for the identity framework that Microsoft just released.

I will go ahead and throw out that Microsoft should rename its ORM solution from Entity Framework to Windows Data Access Foundation (WDAF).  You heard it here first!

Less than two weeks after the release of the Windows Identity Foundation (WIF) RC, the final RTM version has been pushed out!

Check out the official announcement on Vibro.NET or download it directly from the Microsoft site.

Still no word on any new releases for Active Directory FS v2 (Geneva Server).

In a recent interview, Grady Booch responded to a question regarding people that are skeptical about overblown architectures with a very succinct and ultimately dead-on answer:

The most important artifact any development team produces is raw, running, naked code. Everything else is secondary or tertiary. However, that is not to say that these other things are inconsequential. Rather, our models, our processes, our design patterns help one to build the right thing at the right time for the right stakeholders.

Yet, while code is king, one must realize that it is also a servant, for it in the end must serve some constituency, deliver some measurable value. Just as I loathe architecture astronauts—people who have no skin in the game, people who are so divorced from the reality of executables that they melt in the sight of a line of code—I also loathe code bigots who are so blinded by their own prowess and tools that they lose sight of why or for whom they are toiling. Design for design’s sake is meaningless; code for code’s sake may be fun but it is also meaningless.

Recognize also that there are very real tensions between doing the right thing in the short term and doing the right thing for the long term. Code centricity tends to draw you to the former; architectual centricity tends to draw you to the latter, and honestly, neither pole is correct, but rather it is the dance between the two for which a particular team with a specific culture working in a given domain must find balance.

How's the weather up there?

This quote probably hits home for many developers. There needs to be a balance between using an architecture to improve the process of software development versus developing working code that does what the client expects.

Trade-offs are usually made in projects due to budget, time, or resource constraints, but the chosen tools and architecture (whether custom built or based on an existing pattern) should at least exhibit these features:

1. The architecture should lend itself to scalability and maintainability. The final application will need to grow and other developers will need to take over programming duties. If your architecture is so rigid and convoluted that it can’t grow, it probably needs to be redesigned.
   
   
2. The methodology and design patterns should not be overly complex. While a learning curve is acceptable, if it takes an inordinate amount of valuable project time to learn the ins-and-outs of the architecture, it may not be worth using, especially for smaller projects.
   
   
3. The architecture must help solve the problem at hand. As Joel Splosky described in his diatribe against “Architecture Astronauts”, tools are just that — tools to help build a solution. People have a tendency to separate the business and technical problem from the underlying architecture, favoring what they know or what they view as the “acceptable” way to do things (“If all you have is a hammer, every problem looks like a nail”).
   
   
4. The architecture should promote best practices and lead programmers into developing in a structured manner. In Code Complete, Steve McConnell describes the role of good architecture:
   
   

   A well thought-out architecture provides the structure needed to maintain a system’s conceptual integrity from the top levels down to the bottom. It provides guidance to programmers — at a level of detail appropriate to the skills of the programmers and to the job at hand…

   Good architecture makes construction easy. Bad architecture makes construction almost impossible.

Grady Booch summed up the balance between architecture and working code pretty well, and this is coming from a man that has been at forefront of object-oriented design. There are no hard and fast rules about which design to use in which situation, and this is why a good deal of thought needs to be given in the architectural phase of any project.