Wednesday, July 14, 2010
I recently had to work with some code that I wrote a few years ago, and stumbled upon this:
(Not that it's relevant to the rest of this blog post, but this code was responsible for deleting a Role in a custom membership provider, but due to foreign key relationships without cascading deletes, all of the User/Role assignments had to be deleted first)
Now, in all fairness to myself, there's really nothing wrong with this code. Array.ForEach<T> requires an Action<T> delegate, and this anonymous method certainly qualifies as one.
However, since the time that I wrote this particular piece of code, I started using Lambda expressions more often. To be consistent with the rest of the project's code, I should change this anonymous method into a Lambda expression.
Fortunately, CodeRush makes this a breeze! Simply put your cursor within with anonymous method itself, and then hit your
Refactor Key and choose the "Compress to Lambda Expression" refactoring:
As simple as that, the wordy "delegate" syntax of the anonymous method is compressed into the terse "=>" syntax of a Lambda expression:
But, suppose that you are just learning Lambda expressions, and come across one in code that you don't fully understand. CodeRush allows you to go the other way, too, and expand a Lambda expression into an anonymous method, which may be easier to understand. Similar to above, put your cursor on the Lambda expression, hit the Refactor Key, and then choose "Expand Lambda Expression":
Anonymous methods were introduced as a way to inline functionality that otherwise had to exist in its own named method. This is really only good if that functionality is used one time. But, what if you discover that the functionality is needed in multiple places?
CodeRush provides a refactoring for anonymous methods called "Name Anonymous Method" that will extract the logic into a named method that can then be called from other code:
Activating this refactoring will first display the Target Picker (red arrow and line) so that you can select where to add the new method. Then, the new method's name can be set by editing the text in the green box that will appear.
Finally, suppose that the opposite is true: you have a named method that is only used in one place, and would prefer to just inline that code. Or, perhaps you would like to create a one-off modification to an existing method, and don't need the new functionality to be in its own named method.
CodeRush has a refactoring called "Inline Delegate" that replaces a delegate referring to a named method with an anonymous method. If there is only a single reference to that named method, then this refactoring will also delete the named method altogether.
Since I was already familiar with the anonymous method syntax, CodeRush played an instrumental part in my learning Lambda expressions because I could write an anonymous method and then have it transformed into an equivalent Lambda for me. But, once I knew Lambdas, I found that I wanted to update my older code in order to replace anonymous methods with the newer syntax, and CodeRush made it a trivial task to do this.
Happy Coding!
Tuesday, July 13, 2010
Have you ever become distracted while scrolling through code, or switched to another tab and then forgot what you were working on? It happens all the time when we try to multitask while coding. If only there was a call stack for our brains that we could just unwind to find our way back to where we started....
Turns out, there is!
CodeRush includes a feature called "Markers". These are little placeholders, or breadcrumbs, for your cursor location that can be created just before your focus changes to another part of code. When you're done with whatever task distracted you, simply hit ESC (or ALT+End) to collect the most recent marker and your cursor will be returned to exactly where it was when the marker was created.
Sometimes, CodeRush will automatically create markers for you during refactoring and template expansions. These appear as small blue triangles within the newly created code:
When you collect a marker, your cursor will be returned to that location, and an animated Locator Beacon will display on top of the cursor to draw your attention to that spot:
But, you can manually drop your own markers, too, by using ALT+Home. The manually created markers will be red in color:
Some tricks that you can do with markers:
SHIFT+ALT+Home: Drops a marker at the current cursor location and collects the most recent marker (so you can swap between the locations)
Thanks Jay Wren for the clarification.
SHIFT+ALT+PgUp: Select text between the current cursor location and the most recently created marker
SHIFT+ESC: Collect the most recent marker and also paste whatever is in the clipboard at that location
Happy Coding!
Friday, July 09, 2010
CodeRush is full of templates. Thousands of them, when you combine the basic templates with the various types that are supported by each. How does someone start to learn all of the required mnemonics in order to use CodeRush effectively?
The answer to that is a brilliant feature known as the CodeRush Tool Window:
(DevExpress menu in Visual Studio, Tool Windows -> CodeRush)
The CodeRush Tool Window provides a context-sensitive list of "next characters" in CodeRush templates that are valid at the cursor's current location. As you start to work with CodeRush, leave this window open (perhaps on a second monitor) so that you can train yourself.
In the screenshot above, I have the CodeRush Tool Window docked on the left side of my IDE. Depending on where my cursor is located, the contents of the window will change.
For example, I can create a new Auto-Implemented Property at the cursor's current location (line 49 in the screenshot). In the CodeRush Tool Window, I see that mnemonics for Auto-Implemented Properties start with "a", so I can type that character. But, after typing "a", the contents of the CodeRush window will change:
The letter "a" by itself is a valid mnemonic for a CodeRush Template, as indicated by the the green "expansion" frame at the top of the CodeRush Tool Window. If I were to hit the spacebar here, I'd get code for a new abstract class (a preview of this code appears in the expansion frame). This is not what I want, so I can look in the list to see if typing more characters results in an appropriate mnemonic.
Note: If you do accidentally expand a wrong template, just perform an Undo (Ctrl-Z) to return to the pre-expansion state of your code.
Suppose that I was trying to create an Auto-Implemented Property of type Boolean. From the contents of the window, I see that "ab" is listed as "bool", and so I only need to type the second character ("b") and then hit the space bar.
Play around by moving your cursor to various places in your code, and observing how the contents of the CodeRush Tool Window changes. Try out some of the template mnemonics that are listed to see how they work. Remember that Undo (Ctrl-Z) will get you back to where you started.
Happy Coding!
There is A LOT of repetition in coding. To accomplish certain things, you often need to include boilerplate code that is repeated throughout your program.
Take Properties, for instance. Defining Properties on a class, especially a lot of them, can be a very tedious task.
Traditionally, you have to create a member variable of the class to serve as the Property's backing store, and then create the Property itself (with a getter and setter to interact with that member variable). Lather, rinse, repeat... ad nauseum.
This type of work is where CodeRush excels by providing you with mnemonic-driven code templates. In other words, you type a few characters (the mnemonic), hit the space bar, and it will expand into a much larger snippet of code for you (saving you scores of keystrokes in the process).
The most basic template to help with writing Properties is: p
Move your cursor to somewhere within your class { } block, where defining a Property is legal syntax, and then type 'p' followed by a space. This will expand into the following:
The cursor will be placed in the first orange box, where you can change the data type from "object" to whatever type your Property needs (i.e., "string"). Notice that the Property's type is linked to the backing store's type, so changing one of them will change the other.
The trick with the orange boxes in CodeRush is that you press Enter when you finish editing their contents. This will remove the orange coloring from that element, and move the focus to the next orange box within the template. Keep repeating this until there are no more orange boxes left to edit.
Since we knew this was a string Property, we could have saved even more keystrokes by using a mnemonic that included the type: ps
The only real difference between "p" and "ps" is that the type will already be set to "string" for you in the latter. There are other mnemonic templates that expand into Property definitions for other types, like "pi" for "int" and "pd8" for "DateTime". (I'll blog about an awesome discovery feature to help you learn these in my next blog post).
But, wait! There's more!
If you already have a member variable defined (maybe you used the "vs" mnemonic, which expands into a private string variable), and wish to create a Property in your class that uses this variable as a backing store... well, CodeRush has a trick to help you accomplish that!
Simply copy that line of source code into the copy buffer as you normally would (i.e., select the line, and then hit Ctrl-C). Now, paste it where you would like the Property to be created (i.e., maybe on the line directly below). Since it's illegal to define this variable twice, CodeRush does something awesome called a Intelligent Paste. In this case, based on the contents of the copy buffer, it expands a Property template that uses your variable as the backing store!
Similarly, you can also use the "Encapsulate Field" refactoring instead of the Intelligent Paste. Move your cursor to the line declaring the variable to use as a backing store, and then hit your
Refactor Key. Use the Down Arrow key to move through the list of available refactorings, and press Enter when "Encapsulate Field" is highlighted.
Next, CodeRush will prompt you where you would like to insert the code. Use the Up and Down arrows to move through valid places where the new code can be inserted. Press Enter to select the location designated by the Target Picker (red arrow).
The result will be a new property with a getter and setter that uses your variable as a backing store.
And, finally, as C# evolved, Microsoft recognized that a lot of Properties that were being created were very simple in nature, requiring no logic in the getters and setters other than reading and writing to their backing store. A new Property syntax was added that did not require a backing store to be explicitly defined (or rather, the compiler actually creates one for you behind the scenes). This new syntax is referred to as an Auto-Implemented Property.
Similar to the "ps" template, you can use "as" to create an Auto-Implemented Property of type "string".
Note: "a" by itself will not expand into an Auto-Implemented Property of type "object" similar to what "p" by itself does.
What? You didn't know about Auto-Implemented Properties, or you want to convert all of your old-style Properties to the new Auto-Implemented Properties? There happens to be a refactoring for that in CodeRush!
Move your cursor to the Property definition that you would like to convert, and then hit your Refactor Key. Use the Down Arrow to select "Convert to Auto-implemented Property", and observe the changes that CodeRush will be making to your code (the changes will be painted on top of the code that will be changed). Press the Enter key, and voila! No more backing store!
(credit goes to
Dennis Burton for telling me about this refactoring... which goes to prove that there are way more features in this tool than you'll likely ever master)
Thanks to the magic of CodeRush, you now have many different ways to quickly create properties in your code, saving hundreds (if not thousands) of keystrokes in the process.
Happy Coding!
Do a search, and you will find that there are a few IDE Productivity Tools available for Visual Studio. As far as feature sets go, you'll also find that there is quite a bit of overlap in what these tools offer. So, deciding on one is largely a matter of personal preference.
However, by not using an IDE Productivity Tool at all, you are doing yourself a great disservice. No, really! You are wasting a lot of time by manually doing things instead of allowing software do it for you. Since time is money, and these tools are not very expensive, you will quickly make up for the cost of the program in time savings alone (I think within the first week, if not the first day).
The one tool that I stand behind is
CodeRush by
DevExpress. Some of the finest people in the industry work for Devexpress, and over the years, some of these folks have become quite good friends of mine. The company has an outstanding commitment to supporting the developer community year after year, and you will surely find them sponsoring a developer event near you. Aside from the goodwill, their product suite is outstanding, so I'm proud to continue to use and recommend their entire product line whenever I can.
Sidebar: Personally, I think that DX has a bit of a branding problem with their IDE Productivity Tools, because CodeRush includes another product called Refactor! Pro. I would rather see them not offer Rafactor! Pro by itself, and only sell CodeRush with Refactor! Pro, since in my mind they are together one product (and I would never recommend Refactor! to someone without CodeRush). As such, I often refer to features from Refactor! as belonging to CodeRush. But, I digress.
Learning any new tool can be a bit daunting at first, and CodeRush is certainly no exception. DevExpress has produced
a collection of short tutorial videos to help new users come up to speed. It should be noted, though, that some of these videos are likely useful to experienced users as well: with so much functionality packed into the product, I find that it's common for someone to master a number of features, be familiar with just as many if not more features, and yet be totally unaware of half of the things that the tool has to offer.
Since you have to start somewhere, the first feature that I recommend that someone master is mapping and using their Refactor key. This is a shortcut key that will open a CodeRush "context menu" to show available refactorings for the code where the cursor is currently located.
Personally, this is the feature that I probably use the most, so finding an appropriate key binding that is easy to hit yet does not interfere with my ability to type code or use Visual Studio key bindings was important. The default is Ctrl-backtick ( ` ), but I landed on the just backtick key to save me from needing to hold Ctrl. I've heard of a few people who have picked F1 as a way of defeating the annoying help system in VS2008 and earlier. It's all a matter of personal preference, so choose something that works for you.
To set the Refactor key shortcut, open the Options from the DevExpress menu in Visual Studio. In the tree on the left, open IDE and click on Shortcuts. After admiring the entire collection of shortcuts that are available, locate the "Refactor!" section in the list. One of the defined shortcuts will be mapped to the "Refactor" command, and by clicking on this, you can set your own key to bind it to on the right.
Trivia: Notice the Alternate Bindings that also appear in the same section. Number Pad 0 is the one preferred by Mark Miller. Dustin Campbell has two bindings mapped: the default Ctrl-`, as well as Number Pad INS.
Now that you have a Refactor key, try moving your cursor to different places in your code and pressing it.
You'll still have to learn about different refactorings that are available in the tool, but hopefully the Refactor key will become your preferred portal for accessing those refactorings (instead of using smart tags or the mouse to right-click on code).
Happy Coding!
Monday, April 26, 2010
I’ve spent the last few week, or so, reading through Azure in Action by Chris Hay and Brian H. Prince. This book is not yet published, so my copy was in the form of a PDF provided by the Manning Early Access Program (http://manning.com/about/meap).
The book is broken into parts, with 2-4 chapters per part:
- Welcome to the cloud
- Understanding the Azure service model
- Running your site with web roles
- Working with blob storage
- Working with structured data
- Doing work with messages
Each chapter is written in the tutorial style, complete with plentiful background information, source code, and diagrams. And, as a testament to the authors' subtle sense of humor that appears throughout the book, there’s even a screenshot of Big Buck Bunny, almost certainly used to satisfy a wager (I’m just guessing, but the conversation probably started over frosty beverages as “I bet you can’t get a picture of a huge rabbit into your book about cloud computing.” and just went from there).
Azure is an internet-based platform, and as such, is not subject to the same long-term release cycles as traditional packaged software. One challenge that the authors have to deal with when writing about a platform that is built for rapid evolution is how to cover a topic without that content becoming stale soon after the book is published. From what I have seen in this book, as well as what I know about Azure futures, they took the approach of covering the baseline topics that will not be subject to change and not make assertions about the future.
For example, the chapters on SQL Azure do not go into the fact that certain data types, like Spatial, are not supported, but instead refer you to the official up-to-date documentation found on MSDN. It’s true that the Spatial data support is not available in the current version of SQL Azure. But, being a highly requested feature, I know that the product team is currently working to implement this, and that we should see Spatial support in SQL Azure around the same time that the book is published at the end of Summer 2010. If they would have stated “Spatial is not supported,” then that statement would have immediately been stale.
I’ve never met Chris Hay, but I know Brian Prince fairly well (count this as that “Full Disclosure” thing that Bloggers are supposed to do), and have seen many of his presentations about Windows Azure. I was fortunate to also be able to help him deliver a few of the Windows Azure Boot Camps around where I live. Brian is a man with a great wealth of knowledge about the Azure platform, and this book is the closest that you can get to having him sit beside you as you embark on your Azure journey.
I have no doubt that when finally released in August, this book will be the most up-to-date resource on Windows Azure development.
Tuesday, April 13, 2010
This is just a quick post to capture the outcome of about an hour’s worth of trial and error for me.
Here’s a SQL Server table that contained data that my application needed:
Of particular interest is the [Geocode] field, which holds a Geography instance (POINT) representing the location of a Facility. The [Geocode_Lat] and [Geocode_Lon] fields were from legacy requirements, and would be redundant when all is said and done.
Trying to include a Geography field in my ActiveRecord entity proved to be a challenge. NHibernate has a Spatial extension, but setting it up and trying to use it proved to be somewhat of a nightmare (read: I couldn’t get it to work). In reality, I wasn’t looking to use ActiveRecord to do spatial querying, but rather, was just looking to have the data passed between the database and my application.
SQL Server 2008 saves Geography and Geometry columns as binary data. This isn’t WKB, but rather, an internal serialization of the data.
To have the data pass through ActiveRecord, we need to configure the entity class to treat this data as a byte[] array. The application would then need to deserialize the bytes into a SqlGeography instance. Likewise, when updating the entity, the application would need to serialize the SqlGeography instance to an array of bytes.
My Entity class defines the [Geocode] property as:
[Property(SqlType = "geography", ColumnType = "BinaryBlob")]
public byte[] Geocode { get; set; }
Then, I created a couple Extension Methods to handle the serialization/deserialization:
public static class ExtensionMethods
{
public static SqlGeography AsGeography(this byte[] bytes)
{
var geo = new SqlGeography();
using (var stream = new System.IO.MemoryStream(bytes))
{
using (var rdr = new System.IO.BinaryReader(stream))
{
geo.Read(rdr);
}
}
return geo;
}
public static byte[] AsByteArray(this SqlGeography geography)
{
if (geography == null)
return null;
using (var stream = new System.IO.MemoryStream())
{
using (var writer = new System.IO.BinaryWriter(stream))
{
geography.Write(writer);
return stream.ToArray();
}
}
}
}
And, finally, code to use property. Here is a function that updates the geocode for a particular entity (notice the AsByteArray() extension method):
public static void SetGeocode(int FacilityID, double? Geocode_Lat, double? Geocode_Lon)
{
Facility f = Facility.TryFind(FacilityID);
if (f != null)
{
f.Geocode_Lat = Geocode_Lat;
f.Geocode_Lon = Geocode_Lon;
f.Geocode = SqlGeography.Point(Geocode_Lat.GetValueOrDefault(), Geocode_Lon.GetValueOrDefault(), 4326).AsByteArray();
f.SaveAndFlush();
}
}
Disclaimer: The method described here satisfied my immediate needs, so I didn’t spend additional time exploring other options. The code is provided AS IS, with no expressed warranty or guarantee. There probably are far better ways to include spatial data in ActiveRecord entities, and as such, I’d be interested in hearing about your own experiences.
Saturday, March 27, 2010
In previous articles (Part 1, Part 2, Part 3), ACS was configured to process token requests from different Issuers, and a Customer application obtained a SWT token from ACS using an intermediate service (that represented its particular Issuer).
Now that the application has a token, ACS is not needed again until that token expires. This article will show how to use that token in order for the Customer application to call the Bartender web service.
Note: OAuth WRAP defines terminology for parts of the system as follows:
- The Customer application is known as the Client.
- The Bouncer (ACS) is known as the Authorization Server.
- The Bartender web service is known as the Protected Resource.
Passing a Token from Client to Protected Resource
We had to conform to OAuth WRAP specifications while acquiring a token from ACS, but there’s no actual requirement for how a Client must pass that token to the Protected Resource. An Architect or Developer could come up with any contract that they would like to use. However, a best practice would be to continue using the OAuth WRAP specification as guidance.
WRAP defines three different ways that a Protected Resource can accept a token:
- In the HTTP header
- In the Query String
- In the Form contents
OAuth WRAP suggests that a Protected Resource at least support the HTTP header method, but makes no mandates. If a Protected Resource is able to implement all three, then it would be in the position to support the widest variety of Clients. However, if the Protected Resource is unable to use HTTP headers but could use a value passed in the Query String, then there would be nothing in the WRAP specification to prevent only that implementation.
Regardless of the method used, an unauthorized request (perhaps due to a bad or missing token) will result in a HTTP status of 401 Unauthorized, and a header in the response containing: WWW-Authenticate: WRAP
Tokens passed in the HTTP header are expected to use the “Authorization” header, with this header’s value containing the text: WRAP access_token="tokenstring". Note that tokenstring is a placeholder for the actual SWT token obtained from ACS and does not need to be URL Encoded.
Example (using a System.Net.WebClient class):
string headerValue = string.Format("WRAP access_token=\"{0}\"", HttpUtility.UrlDecode(token));
var client = new WebClient();
client.Headers.Add("Authorization", headerValue);
Tokens passed in either the Query String or in Form Contents are expected to use the name/value pair of: wrap_access_token=tokenstring. Again, tokenstring is a placeholder for the actual SWT token obtained from ACS, and should be URL Encoded as needed in order to properly construct the HTTP Request (this may be done automatically by the framework that is used).
Example (using a System.Net.WebClient class):
var values = new NameValueCollection();
values.Add("wrap_access_token", token);
var client = new WebClient();
client.UploadValues("BartenderWebservice", "POST", values));
Accepting and Validating a Token
SWT tokens are opaque to the Client. That is, since the Client cannot modify the token, they shouldn’t really care what’s in it or how it’s structured. The Protected Resource, however, must deconstruct, validate, and then use the claims that are contained within the tokens. If anything is invalid or malformed, then the Protected Resource should deny access by returning a 401 Unauthorized status in the response.
The Windows Azure platform AppFabric SDK V1.0 contains plenty of boilerplate code in the samples demonstrating how to parse and validate a SWT token (so I won’t be repeating that code here). In essence, all of the following needs to pass validation before the Client is authorized to access the Protected Resource:
- HMACSHA256 signature is valid
- Token has not yet expired
- The Issuer is trusted (i.e., contains the URL of the ACS server)
- The Audience is trusted (i.e., contains the URL of the Protected Resource)
- Additional required claims are present
For the nightclub example, the Customer’s Birthdate will be presented as a claim (#5 in the list above). So, in addition to checking the technical aspects of the token, a business rule must also ensure that the Customer is of legal age to order a drink from the Bartender (in the United States, this means at least 21 years old).
Conclusion
I wrote this series of blog posts because I myself was having a hard time grasping the Hows and Whys of using Windows Azure platform AppFabric Access Control to secure a Protected Resource. What I discovered was that by using claims based identity in conjunction with a federated identity model, you can incorporate a very scalable authorization scheme into your system without requiring complex code and/or special prerequisite software. Technically, an organization could build this same functionality into a system without using Azure AppFabric. However, Windows AppFabric Access Control offers the benefit of already being internet-facing and hosted in a high availability environment, and already includes a rich implementation of OAuth WRAP that supports many different kinds of Issuers.
Further Reading:
Monday, March 22, 2010
In this, the third part of a series of articles examining Windows Azure platform AppFabric Access Control (Part 1, Part2), I will continue developing the [somewhat contrived] nightclub web service scenario and demonstrate how to obtain a token from ACS that can be used to call into a Bartender web service.
A Quick Review
Our distributed nightclub system has four major components: A Customer application coupled with some external identity management system, a Bartender web service, and ACS, which acts as our nightclub’s Bouncer.
A Customer application ultimately represents a user that wishes to order a drink from the Bartender web service. The Bartender web service must not serve drinks to underage patrons, so it needs to know the user’s age (this is known as a “claim”). The nightclub has no interest in maintaining a comprehensive list of customers and their ages, so instead, a Bouncer ensures that the user’s claimed age comes from a trusted source (this is known as an “issuer”). If the claim’s source can be verified, the Bouncer will give the customer a token containing its own set of claims that the Bartender web service will recognize. In the end, the Bartender doesn’t have to concern itself with all of the possible issuers – it only needs to recognize a single token generated by the Bouncer (ACS).
Anatomy of a Token Request
ACS uses a subset of the OAuth Web Resource Authorization Protocol (WRAP) to request tokens. The tokens themselves use the Simple Web Token (SWT) format. The latest specification documents for both WRAP and SWT can be found in the Files section of the “OAuth WRAP WG” Google Group: http://groups.google.com/group/oauth-wrap-wg/files
The power of ACS derives from the simplicity of WRAP/SWT. All of the token requests are performed as regular HTTP POSTs, and the response is a URL Encoded string of name/value pairs (one of those being the token itself). Even if your Issuer (Identity Management System) does not natively know how to request a token from ACS, which is very likely, then it is easy to either build this into the application itself, or write a small service to perform this work.
At the HTTP protocol level, a token request may resemble:
REQUEST:
POST https://jasondemo.accesscontrol.windows.net/WRAPv0.9/ HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: jasondemo.accesscontrol.windows.net
Content-Length: 155
Expect: 100-continue
wrap_name=Ohio&wrap_password=LVMjImkJjIBDrJHbTzyrioeajIFpV27tW2uTuCCOYFY%3d
&wrap_scope=http%3a%2f%2fmyserver.domain%2fBartender&DOB=1979-05-25T00%3a00%3a00
RESPONSE:
HTTP/1.1 200 OK
Content-Length: 315
Content-Type: application/x-www-form-urlencoded
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: ca165b72-5d9f-4196-9272-1b80c8c3e02a
Date: Mon, 22 Mar 2010 13:26:44 GMT
wrap_access_token=Birthdate%3d1979-05-25T00%253a00%253a00%26Issuer%3dhttps%253a%252f%252f
jasondemo.accesscontrol.windows.net%252f%26Audience%3dhttp%253a%252f%252fmyserver.domain%
252fBartender%26ExpiresOn%3d1269307605%26HMACSHA256%3deSgT1Gwx3H6owK8hBR82ixG0DRTgM2osI3v
7NdJLQwY%253d&wrap_access_token_expires_in=43200
The response displayed here contains two name/value pairs: wrap_access_token and wrap_access_token_expires_in. If the token request was invalid, then a HTTP 401 status would have been returned instead of a 200.
Notice that “wrap_access_token_expires_in” contains the value 43200, which is the number of seconds that we defined in the Token Lifetime field of the “BouncerPolicy” token policy (in Part 2). This value is provided as a convenience to indicate how long the token will be valid. Taking a cue from systems that use lease lifetimes, like DHCP, it might be a good practice to acquire another token at 50% of the Token Lifetime (21600 seconds in this case, or 6 hours).
As the name suggests, “wrap_access_token” contains the SWT token itself. This is a URL Encoded set of name/value pairs that also includes a HMACSHA256 signature to prevent the token from being tampered with. This token does not need to be parsed by the client application; it can be treated as a magic string. However, there is nothing special about its contents:
Birthdate=1979-05-25T00%3a00%3a00
&Issuer=https%3a%2f%2fjasondemo.accesscontrol.windows.net%2f
&Audience=http%3a%2f%2fmyserver.domain%2fBartender
&ExpiresOn=1269309326
&HMACSHA256=NLmcGYITc8aWvhNp6Ge54TGJxhJCVX4Q67DDLBKoIy4%3d
“Birthdate” is the result of the Passthrough Claim Mapping (Part 2) that took the inbound claim called “DOB” and mapped it to this outbound claim called “Birthdate”. ACS has no idea that this is a date – it just knows that it’s a string of characters that will be understood by the destination. The other claims that are present in this SWT token (Issuer, Audience, ExpiresOn, and HMACSHA256) are all system claim types that are reserved for use by SWT.
Note the value of “Issuer” in this token. In our Request, the stated Issuer was “Ohio”, which was a trusted Issuer that we defined when configuring the Service Namespace using AcmBrowser. The Issuer of this SWT token is now the Service Namespace. Our Bartender web service has no direct trust with the Ohio Issuer, but it will trust tokens signed by the Service Namespace (which trusts the Ohio Issuer). Just as ACS can trust multiple Issuers, it’s also possible that the Bartender web service could trust multiple ACS Issuers (maintaining a symmetric key for each one to verify the HMACSHA256 signature). There is a lot of flexibility in how ACS can be incorporated into your own system’s architecture.
Implementation
Because the “Ohio” issuer was created in ACS using a Symmetric 256-bit key, we have two choices for how to use this key in order to request a token from ACS. We could send the key itself in plaintext, sort of like a password (in fact, this uses a WRAP profile that is intended for username/password authentication). Alternatively, we could create a SWT of our own, using the key to sign it, and then send that token to ACS as part of the token request.
A simple WRAP request that provides the Issuer’s name and password (symmetric key) in plaintext would contain the following name/value pairs:
- wrap_name (Issuer Name, as defined in the Issuer definition in ACS)
- wrap_password (Current Key, as defined in the Issuer definition in ACS)
- wrap_scope (Applies To, as defined in the Scope definition)
- additional claims (will be processed by the defined Scope Rules for claim mapping)
private static string RequestTokenFromACS_usingPassword(DateTime dob)
{
var values = new NameValueCollection();
values.Add("wrap_name", "Ohio");
values.Add("wrap_password", "LVMjImkJjIBDrJHbTzyrioeajIFpV27tW2uTuCCOYFY=");
values.Add("wrap_scope", "http://myserver.domain/Bartender");
values.Add("DOB", dob.ToString("s"));
var client = new WebClient { BaseAddress = "https://jasondemo.accesscontrol.windows.net" };
return Encoding.UTF8.GetString(client.UploadValues("WRAPv0.9", "POST", values));
}
Using a SWT within a WRAP request is just as simple, but the difficulty is in creating the SWT itself. The WRAP request would contain the following name/value pairs:
- wrap_assertion_format (SWT in this case)
- wrap_assertion (the SWT token that we generate and sign using the Current Key)
- wrap_scope (Applies To, as defined in the Scope definition)
The SWT token itself would contain the following name/value pairs:
- Issuer (Issuer Name, as defined in the Issuer definition in ACS)
- Audience (STS Endpoint, as listed on the Service Namespace overview page)
- ExpiresOn (integer containing the number of seconds after the Epoch date of January 1, 1970 00:00 UTC that the token will expire)
- additional claims (will be processed by the defined Scope Rules for claim mapping)
- HMACSHA256 (URL Encoded Base64 signature of the unsigned token)
private static string RequestTokenFromACS_usingSWT(DateTime dob)
{
string requestToken = GetRequestToken(dob);
var values = new NameValueCollection();
values.Add("wrap_assertion_format", "SWT");
values.Add("wrap_assertion", requestToken);
values.Add("wrap_scope", "http://myserver.domain/Bartender");
var client = new WebClient { BaseAddress = "https://jasondemo.accesscontrol.windows.net" };
return Encoding.UTF8.GetString(client.UploadValues("WRAPv0.9", "POST", values));
}
private static string GetRequestToken(DateTime dob)
{
StringBuilder sb = new StringBuilder();
sb.AppendFormat("DOB={0}&", dob.ToString("s"));
sb.Append("Issuer=Ohio&");
sb.Append("Audience=https://jasondemo.accesscontrol.windows.net/WRAPv0.9&");
sb.AppendFormat("ExpiresOn={0:0}", (DateTime.UtcNow.AddMinutes(10) - new DateTime(1970, 1, 1)).TotalSeconds);
return AddSignature(sb.ToString());
}
private static string AddSignature(string unsignedToken)
{
HMACSHA256 hmac = new HMACSHA256(Convert.FromBase64String("LVMjImkJjIBDrJHbTzyrioeajIFpV27tW2uTuCCOYFY="));
var sig = hmac.ComputeHash(Encoding.ASCII.GetBytes(unsignedToken));
string signedToken = String.Format("{0}&HMACSHA256={1}",
unsignedToken,
HttpUtility.UrlEncode(Convert.ToBase64String(sig)));
return signedToken;
}
Where to Execute this Code
The code to request a token can easily be implemented within an application that uses that token to call into a protected resource. In the nightclub example, this code could be incorporated right into the Customer application. However, this would mean that the claim (Birthdate) would originate from the application itself. It also means that the application would need to have access to the Issuer key, making it possible for a nefarious user to obtain the key and bypass the application to directly access the protected resource. These may not be concerns for your specific system, though.
A better solution for the nightclub example, which tries to mimic the real-life State ID system, would be to create a service for each Issuer that their Customer applications call into. This service would then be able to obtain claim information from a source of authority (such as a LDAP directory), obtain a token from ACS, and then return that token to the Customer application. The Customer application would never communicate with ACS directly, so there would be no reason for the application to have the Issuer key (making it harder for that nefarious user to discover the key).
From Here
This article demonstrated how to obtain a token from ACS. In the next article, I will show how to use this token in order to access a protected resource (such as our Bartender web service) and how to validate a token when a protected resource receives one.
(Continued in Part 4)
Further Reading:
Wednesday, March 17, 2010
In the previous article, I provided an example scenario of how claims-based access control might map to the real-world event of a customer entering a bar. This article will build upon that concept, eventually enabling a Customer application to obtain a token from our Bouncer (ACS), and then use that token to order a drink from the Bartender web service.
Now let’s walk through how to create a Service Namespace in Windows Azure, which is needed to permit your application and/or web service to utilize AppFabric Access Control.
Service Namespace
At this time, Windows Azure platform AppFabric provides two services for developers to use: Service Bus and Access Control. Within a Project (i.e., the unit of billing for an Azure account), a “Service Namespace” is used to organize a set of these AppFabric service endpoints. Services within a Service Namespace share the same DNS naming convention, geography (datacenter where the services are hosted) and owner key (security for managing the services).
To create a new Service Namespace, start by logging into the Windows Azure portal (http://windows.azure.com). Navigate to the AppFabric section, choose the Project in which the Service Namespace will be created, and then click the “Add Service Namespace” link. The next screen will prompt for a Name, a Region, and the size of the ServiceBus Connection Packs for the new Service Namespace:
- The name must be unique among all Service Namespaces in existence because this name will be incorporated into DNS aliases. The Windows Azure portal provides a “Validate Name” function to ensure that the name entered meets the required syntax criteria and that it has not already been used.
- Region maps to the Microsoft data center where the services will run. Ideally, this should be as close to the users as possible.
- “ServiceBus Connection Packs” is to support the Windows Azure platform AppFabric Service Bus. Since this article is only examining Access Control, the number of ServiceBus connections can be set to zero.
Once you click the “Create” button, Windows Azure will generate the services and DNS entries for your new Service Namespace. However, looking at the information page on the portal for the Service Namespace reveals nothing that is noticeably useful for configuring these services:
Configuring Access Control
On the portal, the only actions that you can perform are “Generate a New [Management] Key” and “Delete the Service Namespace”. How then do we configure Access Control?
Access Control, like most things in Windows Azure, is configured via a set of web services. While robust tooling is something that is currently being developed (or something that you could develop on your own), there are a few demo tools included as source code in the Windows Azure platform AppFabric SDK V1.0, including a Windows (GUI) application called Access Control Service Management Browser (AcmBrowser).
By default, after installing the SDK, you can find the Visual Studio solution for the AcmBrowser application in:
C:\Program Files\Windows Azure platform AppFabric SDK\V1.0\Samples\AccessControl\ExploringFeatures\Management\AcmBrowser
To use this application, you will need the Service Namespace’s name (the one that you entered during the creation process) and Management Key for that namespace (this is “Current Management Key” string on the screenshot above). After providing these values to AcmBrowser, you can then click the “Load from the Cloud” button to see what is already configured. As you would expect, new namespaces will have nothing pre-configured, as indicated by the “Resources” tree on the left showing Issuers, Scopes, and Token Policies, but these nodes contain no children.
Token Policy
The first thing that we need to create is a Token Policy. This item defines a length of time, in seconds, that a token will be valid until it expires, as well as a symmetric key that is used to sign tokens. This symmetric key will be shared with our Bartender web service, but not the Customer application (else the customer would be able to generate tokens themselves, bypassing ACS and being capable of spoofing any claim).
To create a Token Policy using AcmBrowser, right click on the “Token Policy” node and choose “Create…”:
In this example, tokens created using the “BouncerPolicy” will expire 12 hours (60 * 60 * 12 = 43200 seconds) after they have been generated, and the Signing Key was created by clicking the “Generate” button. Should this key ever be compromised, a new key can be generated in the same way.
Scope
ACS is not an identity provider. You don’t maintain users in ACS, but rather, maintain a list of trusted identity providers (Issuers) that can supply claims on behalf of their users. With this federated model, the claims presented may be named different things, but convey the same information. For example, a claim containing a Birthdate may be named “DOB” by one Issuer and “Date of Birth” by another Issuer, but both sources supply the same type of information.
The web service that will eventually consume these claims, however, shouldn’t be concerned with knowing all of the variations. Instead, ACS provides Claim Mapping capabilities that can rename claims, or express a new claim based on the presence of a known claim in the token request. Before we can configure the claim mappings, though, we need to define a Scope and Issuers.
During the token request, one piece of information that is required is the URL where the token will eventually be used (known as the “Applies To”). ACS uses this in order to know what set of rules to apply when generating that token.
A Scope is the mechanism that ties a URL to a Token Policy, and is created within AcmBrowser by right clicking on the “Scopes” node and choosing “Create…”. In this example, our Scope is defined with the Applies To URL of the Bartender web service and associated to the BouncerPolicy Token Policy. Note that this “Applies To” URL is actually a substring of the real web service URL; any URL that is provided during the token request that starts with this same “Applies To” string will match to this scope, and it’s possible that an actual URL will match multiple Scopes (allowing for chaining of rules from the longest substring match to the shortest).
Issuers
In a Claims-Based Identity and Access Control system, the destination application or web service does not concern itself with end-user authentication. Instead, the user authenticates itself with its own identity management system (known as an Issuer), and this system then becomes a trusted source of claims about that user. This Issuer might be a standalone application, a custom web service running on an intranet server, another AppFabric Service Namespace, or even an Active Directory Federation Services 2.0 system. As a result, there are different ways to prove that information presented during a token request came from a trusted Issuer.
In the nightclub example, the customer presents a driver’s license that was issued by their state of residence. Keeping with this concept, let’s define a few Issuers in ACS named after states (Ohio, Michigan, Indiana, etc) by first right clicking on the “Issuers” node in AcmBrowser and selecting “Create…”:
ACS is able to recognize and validate a token request originating from an Issuer in many different ways. In this example, the “Ohio” Issuer is defined using a Symmetric 256-bit Key (other choices that could have been used include X509 and FedMetadata). After sharing this secret with the Issuer, the “Issuer Name” and “Current Key” can be provided as claims during a token request, much like a username and password, or the key can be used by the Issuer to sign a token request. But, more on that in another article.
[Scope] Rules
During the token request, an arbitrary number of claims will be presented to ACS. The application that will finally consume the token generated by ACS may only require a subset of those claims, if any. To decide what claims should be included in the output token, we need to create a set of Rules (one per output claim).
To create rules for a Scope, you first expand the Scope’s node in AcmBrowser, right-click on the “Rules” node, and then choose “Create…”:
A Rule can be defined as either PassThrough or Simple. A PassThrough rule is used to rename a claim from whatever the Issuer called it to whatever the final application will expect it to be called (the value will be preserved). A Simple rule, on the other hand, will generate a claim (name and value) in the output if a specific claim (name and value) was present in the input. Note that the input and output claim values in a Simple rule must be explicitly defined – you cannot use pattern matching, etc.
For the example scenario, we’ll assume that the Ohio Issuer uses “DOB” as the name of the “Birthdate” claim that the Bartender web service will be expecting. A PassThrough rule is used to rename that claim so that the resulting token will include a claim called “Birthdate” instead (the provided value will be preserved).
Wrapping Up
At this point, everything has been defined in memory on your machine, and nothing has actually been saved to the cloud. To commit your changes, you will need to click on the “Save to Cloud” button in AcmBrowser. Note that AcmBrowser is not sophisticated enough to merge with an existing set of configuration, so if your Service Namespace is not already empty, then you will need to click the “Clear Service Namespace in Cloud” button prior to saving to the cloud. You can also load and save local copies of the configuration using the tool, which is useful for backup purposes as well as working on a particular configuration over the course of multiple days without disturbing what is already running in the cloud.
In the next part of this series, I’ll show code for how everything finally comes together for this contrived example.
(Continued in Part 3)
Further Reading: