Configuring an ASP.NET Application to work as a Relying Party with Geneva Beta 2

Okay, this one's a little off the path from the types of things I normally blog about.  However, I had been doing some work recently on getting an ASP.NET app to integrate with Geneva Beta 2 as a relying party (RP).  For those of you who have the time and resources, there is a walk-through of using MOSS 2007 with Geneva Beta 2 that is about 90 pages long and includes 4 Hyper-V images.  It really doesn't take that long to do (maybe a couple of hours), and it does a really nice job of showing how you can integrate MOSS with Geneva, as well as federating Geneva with another partner (i.e. Security Token Service, or STS).  You'll get to see some of the cool stuff you can do from the Geneva side in terms of claims, pulling claim information from a database, using RMS, as well as the federated experience in SharePoint using the custom membership and role provider that Geneva is shipping.  Pretty cool stuff really.

Along those lines, you may also find yourself in the position of needing to integrate your ASP.NET application with Geneva.  In short, you'll build your ASP.NET application, run a new Federation Utility that configures the web.config in your application to use Geneva and it's authentication pipeline, and then use the Federation Metadata file that is built to create and configure your application as an RP in Geneva.  It's actually pretty straightforward once you know all the pieces, but then if all the pieces were well-documented and easy to find who would need blogs, right?

I'm assuming that you've already created your project in Visual Studio by doing File...New...Web Site, selecting C# as the language and then selecting the Claims Aware Web Application as the project template type.  If you select VB as the language you won't see this option.  Don't shoot the messenger folks, remember I just report the news, I don't write it.  I also recommend that you change your start up options for the application so that it uses a virtual directory on the local web server rather than the built in Visual Studio web server, as well as using SSL.  You're going to have this Url returned to you as part of the authentication process and redirection, so it needs to be a name that your client(s) can resolve.  If you are only testing this out on your local server for example, it can be https://localhost/MyProjectName.  This is really just used during the Geneva configuration process, and you can always go back and change it in Geneva if you move your application to a new site, move it into production, etc.

So assuming you have all of this in place, you want to right click on the project and select the menu to Modify Your STS reference; this launches the Federation utility.  Here are some tips for using the wizard:

  1. For the application URI, you can use whatever you want, i.e. urn:MyDemo:Steve.Com; you can also ignore the "no SSL" warning.  However...if you DON'T use the Url to your application you will have to fix up or add an Endpoint as described in 8G below.  Whatever value you use here is what the xml file puts in for the endpoint address.  If it isn't the Url to your application, the Geneva server won't stick a non-valid url in the Endpoint address and as a result it doesn't know where to redirect the app after authentication.
  2. Select the option to Use an Existing STS, and point it at your Geneva server (i.e. https://mossdemo.steve.local/ and the rest of the stuff that goes after that, as the wizard shows in the example).
  3. Choose No Encryption for now on the cookies.  You can change that later in Geneva.
  4. Click Next then Finish.
  5. In web.config, if you want to require additional claims, uncomment them from web.config and change required = "True".
  6. If you make changes, right click on the project name and select "Update federation metadata".
  7. You should have a folder in your project directory called \FederationMetadata\2007-06; there is a file in there called FederationMetadata.xml.  Copy this file to your Geneva server.
  8. On the Geneva Server:
    1. In the Geneva Server Admin, go into Policy...Relying Parties and start the Add Relying Party wizard.
    2. Choose the option to import relying party information from a local XML file.  Import the FederationMetadata.xml file that you created in Visual Studio and copied over to the Geneva Server.
    3. Type in any Display Name and click Next.
    4. Click Save, uncheck the box to Launch the rules editor and click Close.  NOTE: STEPS 8.5 THRU 8.8 ARE NOT NECESSARY IF YOU PUT THE URL FOR YOUR APPLICATION IN AS THE APPLICATION URI IN STEP 1.
    5. Right click on the Relying Party you just created and select Properties.
    6. Click on the Endpoints tab.
    7. Click the Add button, click WS-Federation in the Endpoint drop down, then type the Url to your application (including the trailing slash and/or page if you don't have a default page set up) in the Url.  So if your ASP.NET app is running on https://localhost/test, that's what you would type in, or https://myserver/mydirectory/mypage.aspx, or whatever the Url is to the home page for the application.  The Url will be resolved by the client, so it needs to be a name and Url that the appropriate client desktop browser can resolve.
    8. Click the OK button to save your changes.
    9. Right click on the Relying Party and select Edit Claim Rules...
    10. Create a new rule to Create claims from an LDAP attribute store.
    11. Select Enterprise AD User Account Store in the Atribute store drop down.
    12. Map attributes to outgoing claims for at least Name and Role, and as many other claims as you want to create.
    13. Save the Rule changes and close the Rules editor.
  9. Try your application.  Close the browser first if it was already open.  Close it and reopen it each time you change your configuration on the asp.net or Geneva Server side.

That's pretty much it; you should play with different claims, roles and integration with ASP.NET roles-based authentication - it's pretty slick.  One additional point about claims though.  If a claim doesn't show up even though you are sending it out, make sure the user actually has a value in the directory for that attribute.  If he doesn't, it won't send a claim with an empty or null value; it just doesn't send the claim at all!  This can cause all sorts of hair pulling to try and figure out what's going on.

Hope you check out Geneva, and if you do hopefully this will help you get things moving along a little more quickly.

Steve