### Whitepaper on ADFS 2 Federation with Shibboleth and the InCommon Federation

Over on the Claims-Based Identity blog, they announced a whitepaper was just released on using ADFS 2 to federate with Shibboleth 2 and the InCommon Federation.  I just started reading through it, but it looks really well written.

Here is the abstract of the paper itself:

Through its support for the WS-Federation and Security Assertion Markup Language (SAML) 2.0 protocols, Microsoft® Active Directory® Federation Services 2.0 (AD FS 2.0) provides claims-based, cross-domain, Web single sign-on (SSO) interoperability with non-Microsoft federation solutions. Shibboleth® 2, through its support for SAML 2.0, enables cross-domain, federated SSO between environments that are running Microsoft and Shibboleth 2 federation infrastructures.

What is Shibboleth?

The Shibboleth System is a standards based, open source software package for web single sign-on across or within organizational boundaries. It allows sites to make informed authorization decisions for individual access of protected online resources in a privacy-preserving manner.

What is InCommon?

InCommon eliminates the need for researchers, students, and educators to maintain multiple passwords and usernames. Online service providers no longer need to maintain user accounts. Identity providers manage the levels of their users' privacy and information exchange. InCommon uses SAML-based authentication and authorization systems (such as Shibboleth®) to enable scalable, trusted collaborations among its community of participants.

### Using Claims Based Identities with SharePoint 2010

When SharePoint 2010 was developed, Microsoft took extra care to include support for a claims-based identity model.  There are quite a few benefits to doing it this way, one of which is that it simplifies managing identities across organizational structures.  So lets take a look at adding a Secure Token Service as an Authentication Provider to SharePoint 2010.

First, Some Prerequisites

• You have to use PowerShell for most of this.  You wouldn’t/shouldn’t be adding too many Providers to SharePoint all that often so there isn’t a GUI for this.
• The claims that SharePoint will know about must be known during setup.  This isn’t that big a deal, but…

Once you’ve collected all the information you need, open up PowerShell as an Administrator and add the SharePoint snap-in on the server.

Next we need to create the certificate and claim mapping objects:

$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("d:\path\to\adfsCert.cer")$claim1 = New-SPClaimTypeMapping -IncomingClaimType "http://schemas.microsoft.com/ws/2008/06/identity/claims/role" -IncomingClaimTypeDisplayName "Role" –SameAsIncoming

$claim2 = New-SPClaimTypeMapping "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" -IncomingClaimTypeDisplayName "EmailAddress" –SameAsIncoming There should be three lines. They will be word-wrapped. The certificate is pretty straightforward. It is the public key of the STS. The claims are also pretty straightforward. There are two claims: the roles of the identity, and the email address of the identity. You can add as many as the STS will support. Next is to define the realm of the Relying Party; i.e. the SharePoint server.$realm = "urn:" + $env:ComputerName + ":adfs" By using a URN value you can mitigate future changes to addresses. This becomes especially useful in an intranet/extranet scenario. Then we define the sign-in URL for the STS. In this case, we are using ADFS:$signinurl = https://[myAdfsServer.fullyqualified.domainname]/adfs/ls/

Mind the SSL.

And finally we put it all together:

New-SPTrustedIdentityTokenIssuer -Name "MyDomainADFS2" -Description "ADFS 2 Federated Server for MyDomain" -Realm $realm -ImportTrustCertificate$cert -ClaimsMappings $claim1,$claim2 -SignInUrl $signinurl -IdentifierClaim$claim2.InputClaimType

This should be a single line, word wrapped.  If you wanted to you could just call New-SPTrustedIdentityTokenIssuer and then fill in the values one at a time.  This might be useful for debugging.

At this point SharePoint now knows about the STS but none of the sites are set up to use it.

Authenticating SharePoint sites using the STS

For a good measure restart SharePoint/IIS.  Go into SharePoint Administration and create a new website and select Claims Based Authentication at the top:

Fill out the rest of the details and then when you get to Claims Authentication Types select Trusted Identity Provider and then select your STS.  In this case it is my ADFS Server:

Save the site and you are done.  Try navigating to the site and it should redirect you to your STS.  You can then manage users as you would normally with Active Directory accounts.

### Claims Transformation and Custom Attribute Stores in Active Directory Federation Services 2

Active Directory Federation Services 2 has an amazing amount of power when it comes to claims transformation.  To understand how it works lets take a look at a set of claims rules and the flow of data from ADFS to the Relying Party:

We can have multiple rules to transform claims, and each one takes precedence via an Order:

In the case above, Transform Rule 2 transformed the claims that Rule 1 requested from the attribute store, which in this case was Active Directory.  This becomes extremely useful because there are times when some of the data you need to pull out of Active Directory isn’t in a useable format.  There are a couple options to fix this:

• Make the receiving application deal with it
• Modify it before sending it off
• Ignore it

Lets take a look at the second option (imagine an entire blog post on just ignoring it…).  ADFS allows us to transform claims before they are sent off in the token by way of the Claims Rule Language.  It follows the pattern: "If a set of conditions is true, issue one or more claims."  As such, it’s a big Boolean system.  Syntactically, it’s pretty straightforward.

To issue a claim by implicitly passing true:

=> issue(Type = "http://MyAwesomeUri/claims/AwesomeRole", Value = "Awesome Employee");

What that did was ignored the fact that there weren’t any conditions and will always pass a value.

To check a condition:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/role", Value == "SomeRole"]
=> issue(Type = "http://MyAwesomeUri/claims/AwesomeRole", Value = "AwesomeRole");

Breaking down the query, we are checking that a claim created in a previous step has a specific type; in this case role and the claim’s value is SomeRole.  Based on that we are going to append a new claim to the outgoing list with a new type and a new value.

That’s pretty useful in it’s own right, but ADFS can actually go even further by allowing you to pull data out of custom data stores by way of Custom Attribute Stores.  There are four options to choose from when getting data:

1. Active Directory (default)
2. LDAP (Any directory that you can query via LDAP)
3. SQL Server (awesome)
4. Custom built store via custom .NET assembly

Let’s get some data from a SQL database.  First we need to create the attribute store.  Go to Trust Relationships/Attribute Stores in the ADFS MMC Console (or you could also use PowerShell):

All you need is a connection string to the database in question:

The next step is to create the query to pull data from the database.  It’s surprisingly straightforward.  This is a bit of a contrived example, but lets grab the certificate name and the certificate hash from a database table where the certificate name is equal to the value of the http://MyCertUri/UserCertName claim type:

c:[type == http://MyCertUri/UserCertName]
=> issue(store = "MyAttributeStore",
types = ("http://test/CertName", "http://test/CertHash"),
query = "SELECT CertificateName, CertificateHash FROM UserCertificates WHERE CertificateName='{0}'", param = c.value);

For each column you request in the SQL query, you need a claim type as well.  Also, unlike most SQL queries, to use parameters we need to use a format similar to String.Format instead of using @MyVariable syntaxes.

In a nutshell this is how you deal with claims transformation.  For a more in depth article on how to do this check out TechNet: http://technet.microsoft.com/en-us/library/dd807118(WS.10).aspx.

### Modifying and Securing the ADFS 2 Web Application

When you install an instance of Active Directory Federation Services v2, amongst other things it will create a website within IIS to use as it’s Secure Token Service.  This is sort of fundamental to the whole design.  There are some interesting things to note about the situation though.

When Microsoft (or any ISV really) releases a new application or server that has a website attached to it, they usually deliver it in a precompiled form, so all we do is point IIS to the binaries and config files and we go from there.  This serves a number of purposes usually along the lines of performance, Intellectual Property protection, defense in depth protection, etc.  Interestingly though, when the installer creates the application for us in IIS, it drops source code instead of a bunch of assemblies.

There is a valid reason for this.

It gives us the opportunity to do a couple things.  First, we can inspect the code.  Second, we can easily modify the code.  Annoyingly, they don’t give us a Visual Studio project to do so.  Let’s create one then.

First off, lets take a look at what was created by the installer.  By default it drops the files in c:\inetpub\adfs\ls.  We are given a few files and folders:

There isn’t much to it.  These files only contain a few lines of code.  Next we create the actual project.

DISCLAIMER:  I will not be held responsible if things break or the server steals your soul.  Please do NOT (I REPEAT) do NOT do this with production servers please!  (Notice I said please twice?)

Since we want to create a Visual Studio project, and since ADFS cannot be installed on a workstation, we have two options:

1. Install Visual Studio on the server running ADFS
2. Copy the files to your local machine

Each options have their tradeoffs.  The first requires a bit of a major overhaul of your development environment.  It’s very similar to SharePoint 2007 development.  The second option makes developing a lot easier, but testing is a pain because the thing won’t actually work properly without the Windows Services running.  You would need to deploy the code to a test server with ADFS installed.

Since I have little interest in rebuilding my development box, I went with the second option.

Okay, back to Visual Studio.  The assemblies referenced were all built on Framework 3.5, so for the sake of simplicity lets create a 3.5 Web Application:

I haven’t tested 4.0 yet.

Since this is a Web Application and not a Web Site within Visual Studio, we need to generate the *.designer.cs files for all the *.aspx pages.  Right-click your project and select Convert to Web Application:

At this point if you tried to compile the application it wouldn’t work.  We are missing a few assembly references.  First, add Microsoft.IdentityModel.  This should be in the GAC or the Reference Assemblies folder in Program Files.  Next, go back to the ADFS server and navigate to C:\Program Files\Active Directory Federation Services 2.0 and copy the following files:

• Microsoft.IdentityServer.dll
• Microsoft.IdentityServer.Compression.dll

Add these assemblies as references.  The web application should compile successfully.

Next we need to sign the web application’s assemblies.  If you have internal policies on assembly signing, follow those.  Otherwise double-click the properties section in Solution Explorer and navigate to Signing:

Choose a key file or create a new one.  Rebuild the web application.

So far we haven’t touched a line of code.  This is all general deployment stuff.  You can deploy the web application back to the ADFS server and it should work as if nothing had changed.  You have a few options for this.  The Publishing Features in Visual Studio 2010 are awesome.  Right click the project and Publish it:

Since I set up a test box for ADFS development, I’m just going to overwrite the files on the server:

Pro Tip: If you do something terrible and need to revert back to original code (what part of don’t do this on a production box didn’t make sense? ) you can access the original files from C:\Program Files\Active Directory Federation Services 2.0\WSFederationPassive.Web.

At this point we haven’t done much, but we now have a stepping point to modify the default behavior of ADFS.  This could range from simple theme changes to better suit corporate policy, or to completely redefine the authentication workflow.

This also gives us the ability to better protect our code in the event that IIS craps out and shows contents of files, not to mention the (albeit minor) performance boost we get because the website doesn’t need to be recompiled.

Have fun!

### Presenting at IT Pro Toronto UG on ADFS 2 and Identity Simplification on October 12

Just a heads up that I will be presenting on ADFS in Toronto for the IT Pro User Group.  Here is the write up:

Simplifying User Identity with Active Directory Federation Services (click for link to event)

Start Date/Time:
Tuesday, October 12, 2010 6:30 PM

End Date/Time:
Tuesday, October 12, 2010 9:30 PM

Location:
UofT Health Sciences Bldg, Rm 106, 155 College St.

Description:

There is a growing demand for single sign-on solutions that cross organizational, application and platform boundaries of all sizes.  In this presentation, lets take a look at how we can easily meet these demands using Active Directory Federation Service 2.0 and the Windows Identity Foundation.

Don't worry;  There won't be any code.

Bio:

Steve Syfuhs is a very loud software developer, and works for a large not-for-profit Corporation creating awesome applications.  He has a passion for all things technology, but tries to stick to the fun stuff like the web development, identity management, and telling bad jokes.  His website, www.syfuhs.net, is a collection of random thoughts and ideas that revolve around technology.  And stuff.

### Converting Bootstrap Tokens to SAML Tokens

there comes a point where using an eavesdropping application to catch packets as they fly between Secure Token Services and Relying Parties becomes tiresome.  For me it came when I decided to give up on creating a man-in-the-middle between SSL sessions between ADFS and applications.  Mainly because ADFS doesn’t like that.  At all.

Needless to say I wanted to see the tokens.  Luckily, Windows Identity Foundation has the solution by way of the Bootstrap token.  To understand what it is, consider how this whole process works.  Once you’ve authenticated, the STS will POST a chunk of XML (the SAML Token) back to the RP.  WIF will interpret it as necessary and do it’s magic generating a new principal with the payload.  However, in some instances you need to keep this token intact.  This would be the case if you were creating a web service and needed to forward the token.  What WIF does is generate a bootstrap token from the SAML token, in the event you needed to forward it off to somewhere.

Before taking a look at it, let's add in some useful using statements:

using System;
using System.IdentityModel.Tokens;
using System.Text;
using System.Xml;
using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Tokens;
using Microsoft.IdentityModel.Tokens.Saml11;

The bootstrap token is attached to IClaimsPrincipal identity:

However if you do this out of the box, BootstrapToken will be null.  By default, WIF will not save the token.  We need to explicitly enable this in the web.config file.  Add this line under <microsoft.IdentityModel><service><securityTokenHandlers>:

<securityTokenHandlerConfiguration saveBootstrapTokens="true" />

Once you’ve done that, WIF will load the token.

The properties are fairly straightforward, but you can’t just get a blob from it:

Luckily we have some code to convert from the bootstrap token to a chunk of XML:

StringBuilder sb = new StringBuilder();

using (var writer = XmlWriter.Create(sb))
{
new Saml11SecurityTokenHandler(new SamlSecurityTokenRequirement()).WriteToken(writer, bootstrapToken);
}

string theXml = sb.ToString();

We get a proper XML document:

That’s all there is to it.

### Build your own Directory Federation Service

This is more of a random collection of thoughts because earlier today I came to the conclusion that I need something very similar to Active Directory Federation Services, except for non-domain users.  This is relatively easy to do; all I need is to create a Secure Token Service with a user store for the back end.

The simplest approach is to use ASP.NET Membership and Roles with SqlProvider’s wrapped up by some WIF special sauce.  Turns out Dominick Baier already did just that with StarterSTS.

The problems I have with this is that it’s a pain to manage when you start getting more than a hundred or so users.  Extending user properties is hard to do too.  So my solution is to use something that is designed for user identities… an LDAP directory.  If it’s good enough for Active Directory, it’ll be plenty useful for this situation.

Reasoning
As an aside, the reason I’m not using Active Directory in the first place is because I need to manage a few thousand well known users without CAL’s.  This would amount to upwards of a couple hundred thousand dollars in licensing costs that just isn’t in the budget.  Further, most of these users probably wouldn’t use any of our systems that use Active Directory for authentication, but nevertheless, we need accounts for them.

Also, it would be a lot easier to manage creation and modification of user accounts because there are loads of processes that have been designed to pull user data out of HR applications into LDAP directories instead of custom SQL queries.

So lets think about what makes up Active Directory Federation Services.  It has roles that provides:

• Token Services
• A Windows Authentication end-point
• An Attribute store-property-to-claim mapper (maps any LDAP properties to any claim types)
• An application management tool (MMC snap-in and PowerShell cmdlets)
• Proxy Services (Allows requests to pass NAT’ed zones)

That’s a pretty lightweight product when you compare it to the other services in Microsoft’s Identity stack.

We can simplify it even further by breaking down the roles we need.

Token Services

This is actually pretty easy to accomplish.  Refer back to the WIF magic sauce.

Authentication end-point

This is just (well, you know what I mean) a web page login control.  We can’t do Windows Authentication without Kerberos (or NTLM), and we can’t do Kerberos without Active Directory (technically it could be done, but you’d be crazy to try).

Attribute store-property-to-claim mapper

ADFS can connect to a bunch of different attribute stores, including custom built stores if you provide assemblies.  We only really need to map to a few LDAP properties, and make it easy to map to other properties in the future.

Application management tool

This would be to manage the mapper and a few STS settings like URI names and certificates.  This, I think, would be a relatively simple application if we designed the configuration database properly.

Proxy Services

Proxies are a pain in the butt.  Useful in general, but we don’t really need to think about this at the moment.

Some Warnings

There are some things that are worth mentioning.  We have to be really careful about what we create because we are developing a serious piece of the security infrastructure.  Yes, it is for a group of employees that won’t have much access to anything dangerous (if they need access, they’d be migrated to Active Directory), but nevertheless we are creating the main ingress point for the majority of our employees.  It also needs to be accessible from the internet.

It may sound like I think it’ll be a synch to develop this system and have it work securely, but in reality there is a lot that will need to go into it to protect the network, the employees, and the data this could possibly interact with.  It is tough to develop applications securely.  It is far harder to develop secure applications whose sole responsibility is security related.

Next Steps

The next step is to design the thing.  I know how it will exist in relation to the systems it will be used to provide identity to, but aside from that, the architecture of the thing is still unknown.  With any luck I can accomplish rough designs tomorrow on the train, on my way to visit family for the holiday.

Better yet, maybe while visiting with family.

### Working with ADFS 2 via PowerShell

Over the last few years Microsoft has made a push for all of it’s Server Solutions to have the capability of being managed via PowerShell.  Active Directory Federation Services is no different.

When we installed ADFS for the first time, the installer told us it needed PowerShell as a pre-requisite, so we get some cmdlets available to us out of the box.  Before we start playing around with them though we need to register the cmdlets to our PowerShell session. We can do with this command:

At this point we can now muck around with all of the available cmdlets.  For a full list of available cmdlets for ADFS check out TechNet.

Let’s take a look at our ADFS Server Properties:

AcceptableIdentifiers          : {}
AutoCertificateRollover        : True
CertificateCriticalThreshold   : 2
CertificateDuration            : 365
CertificateGenerationThreshold : 20
CertificatePromotionThreshold  : 5
CertificateRolloverInterval    : 720
CertificateSharingContainer    :
CertificateThresholdMultiplier : 1440
ClientCertRevocationCheck      : None
ContactPerson                  :
DisplayName                    : WEB1.nexus.external.test
ExtendedProtectionTokenCheck   : Allow
HostName                       : WEB1.nexus.external.test
HttpPort                       : 80
HttpsPort                      : 443
InstalledLanguage              : en-US
LogLevel                       : {Errors, Information, Verbose, Warnings}
MonitoringInterval             : 1440
NetTcpPort                     : 1501
NtlmOnlySupportedClientAtProxy : False
OrganizationInfo               :
PreventTokenReplays            : True
ProxyTrustId                   : 58cb3f40-0633-4d9e-b3c2-84f9bc8c2ce8
ReplayCacheExpirationInterval  : 60
SignedSamlRequestsRequired     : False
SamlMessageDeliveryWindow      : 5
SignSamlAuthnRequests          : False

Nothing fancy there.  What about updating?

Yep, we can do that:

NAME

SYNOPSIS
Sets the properties of the Federation Service.

SYNTAX
[…snip…]

DETAILED DESCRIPTION
The Set-ADFSProperties cmdlet sets the global properties and configuration of the Federation Service.

Updating settings isn’t all that exciting, so what about managing Relying Parties?

You can also manage things like Certificates:

There are many more things you can do from within PowerShell.  Again, for the full list check out TechNet.

Being able to manage ADFS directly from PowerShell makes things a lot easier.  Not only for those who aren’t too keen on using MMC snap-ins, but also for the developers to automate deployment for testing and development.

### Videos on Identity Foundation and ADFS

Some videos from the last PDC…

LOTS of information…

### Single Sign-On Between the Cloud and On-Premise using ADFS 2

One of the issues I hear about hosting services in the cloud has to do with managing Identity.  Since the service isn’t local, it’s harder to tie it into services like Active Directory.  What do I mean by this?

I’m kind of particular how certain things work.  I hate having more than one set of credentials across applications.  Theoretically since we can’t join our Azure Servers to our domain, there’s a good chance we will need separate credentials between our internal domain and Cloud Services.  However, it’s possible to make our Cloud Applications use our Active Directory credentials via a Claims Service.

With Federation Services it’s surprisingly easy to do.  Yesterday we talked about installing Active Directory Federation Services and federating an application.  Today we will talk about what it takes to get things talking between Azure and ADFS.

As a recap, yesterday we:

1. Installed prerequisites
2. Installed ADFS 2.0 on a domain joined server
3. Created a relying party
4. Created claims mappings to data in Active Directory
5. Created a simple Claims-Aware application

So what do we need to do next?  There really isn’t much we need to do:

1. Build Azure App
2. Federate it using FedUtil.exe

Building an Azure application isn’t trivial, but we don’t need to know much to Federate it.

How do we federate it?  Follow these steps providing the Azure details for the application URI and the Federation Metadata from ADFS.

One of the gotcha’s with deploying to Azure though is that the Microsoft.IdentityModel assembly is not part of the GAC, and it’s not in Azure builds.  Therefore we need to copy the assembly to the bin folder for deployment.  We do that by going to the Microsoft.IdentityModel reference properties and setting Copy Local to true:

That isn’t the only gotcha.  We need to keep in mind how data is transferred between Cloud and intranet.  In most cases, nothing goes on behind the scenes; it passes across the client’s browser through POST calls.  If the client’s browser is on the local intranet, when it hits the cloud app it will redirect to an intranet location.  This works because the client has access to both the cloud app and can access ADFS.  This isn’t necessarily the case with people who work offsite, or are partners with the company.

We need to have the ADFS Server accessible to the public.  This is kind of an ugly situation.  Leaving the politics out of this, we are sticking a domain joined system out in the public that’s sole responsibility is authentication and identity mapping.

One way to mitigate certain risks is to use an ADFS Proxy Service.  This service will sit on a non-domain joined system sitting on an edge network that creates a connection to the ADFS Server sitting inside the corporate network.  External applications would use the Proxy service.

Installing the Proxy service is relatively simple, but a topic for another post.