When working with Claims Based Authentication a lot of things are similar between the two different models, Active and Passive. However, there are a few cases where things differ… a lot. The biggest of course being how a Request for Security Token (RST) is authenticated. In a passive model the user is given a web page where they can essentially have full reign over how credentials are handled. Once the credentials have been received and authenticated by the web server, the server generates an identity and passes it off to SecurityTokenService.Issue(…) and does it’s thing by gathering claims, packaging them up into a token, and POST’ing the token back to the Relying Party.
Basically we are handling authentication any other way an ASP.NET application would, by using the Membership provider and funnelling all anonymous users to the login page, and then redirecting back to the STS. To hand off to the STS, we can just call:
FederatedPassiveSecurityTokenServiceOperations.ProcessRequest(
HttpContext.Current.Request,
HttpContext.Current.User,
MyTokenServiceConfiguration.Current.CreateSecurityTokenService(),
HttpContext.Current.Response);
However, it’s a little different with the active model.
Web services manage identity via tokens but they differ from passive models because everything is passed via tokens including credentials. The client consumes the credentials and packages them into a SecurityToken object which is serialized and passed to the STS. The STS deserializes the token and passes it off to a SecurityTokenHandler. This security token handler validates the credentials and generates an identity and pushes it up the call stack to the STS.
Much like with ASP.NET, there is a built in Membership Provider for username/password combinations, but you are limited to the basic functionality of the provider. 90% of the time, this is probably just fine. Other times you may need to create your own SecurityTokenHandler. It’s actually not that hard to do.
First you need to know what sort of token is being passed across the wire. The big three are:
- UserNameSecurityToken – Has a username and password pair
- WindowsSecurityToken – Used for Windows authentication using NTLM or Kerberos
- X509SecurityToken – Uses x509 certificate for authentication
Each is pretty self explanatory.
Some others out of the box are:
Reflector is an awesome tool. Just sayin’.
Now that we know what type of token we are expecting we can build the token handler. For the sake of simplicity let’s create one for the UserNameSecurityToken.
To do that we create a new class derived from Microsoft.IdentityModel.Tokens.UserNameSecurityTokenHandler. We could start at SecurityTokenHandler, but it’s an abstract class and requires a lot to get it working. Suffice to say it’s mostly boilerplate code.
We now need to override a method and property: ValidateToken(SecurityToken token) and TokenType.
TokenType is used later on to tell what kind of token the handler can actually validate. More on that in a minute.
Overriding ValidateToken is fairly trivial*. This is where we actually handle the authentication. However, it returns a ClaimsIdentityCollection instead of bool, so if the credentials are invalid we need to throw an exception. I would recommend the SecurityTokenValidationException. Once the authentication is done we get the identity for the credentials and bundle them up into a ClaimsIdentityCollection. We can do that by creating an IClaimsIdentity and passing it into the constructor of a ClaimsIdentityCollection.
public override ClaimsIdentityCollection ValidateToken(SecurityToken token)
{
UserNameSecurityToken userToken = token as UserNameSecurityToken;
if (userToken == null)
throw new ArgumentNullException("token");
string username = userToken.UserName;
string pass = userToken.Password;
if (!Membership.ValidateUser(username, pass))
throw new SecurityTokenValidationException("Username or password is wrong.");
IClaimsIdentity ident = new ClaimsIdentity();
ident.Claims.Add(new Claim(WSIdentityConstants.ClaimTypes.Name, username));
return new ClaimsIdentityCollection(new IClaimsIdentity[] { ident });
}
Next we need set the TokenType:
public override Type TokenType
{
get
{
return typeof(UserNameSecurityToken);
}
}
This property is used as a way to tell it’s calling parent that it can validate/authenticate any tokens of the type it returns. The web service that acts as the STS loads a collection SecurityTokenHandler’s as part of it’s initialization and when it receives a token it iterates through the collection looking for one that can handle it.
To add the handler to the collection you add it via configuration or if you are crazy doing a lot of low level work you can add it to the SecurityTokenServiceConfiguration in the HostFactory for the service:
securityTokenServiceConfiguration.SecurityTokenHandlers.Add(new MyAwesomeUserNameSecurityTokenHandler())
To add it via configuration you first need to remove any other handlers that can validate the same type of token:
<microsoft.identityModel>
<service>
<securityTokenHandlers>
<remove type="Microsoft.IdentityModel.Tokens.WindowsUserNameSecurityTokenHandler,
Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
<remove type="Microsoft.IdentityModel.Tokens.MembershipUserNameSecurityTokenHandler,
Microsoft.IdentityModel, Version=3.5.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" />
<add type="Syfuhs.IdentityModel.Tokens.MyAwesomeUserNameSecurityTokenHandler, Syfuhs.IdentityModel" />
</securityTokenHandlers>
That’s pretty much all there is to it. Here is the class for the sake of completeness:
using System;
using System.IdentityModel.Tokens;
using System.Web.Security;
using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.Protocols.WSIdentity;
using Microsoft.IdentityModel.Tokens;
namespace Syfuhs.IdentityModel.Tokens
{
public class MyAwesomeUserNameSecurityTokenHandler : UserNameSecurityTokenHandler
{
public override bool CanValidateToken { get { return true; } }
public override ClaimsIdentityCollection ValidateToken(SecurityToken token)
{
UserNameSecurityToken userToken = token as UserNameSecurityToken;
if (userToken == null)
throw new ArgumentNullException("token");
string username = userToken.UserName;
string pass = userToken.Password;
if (!Membership.ValidateUser(username, pass))
throw new SecurityTokenValidationException("Username or password is wrong.");
IClaimsIdentity ident = new ClaimsIdentity();
ident.Claims.Add(new Claim(WSIdentityConstants.ClaimTypes.Name, username));
return new ClaimsIdentityCollection(new IClaimsIdentity[] { ident });
}
}
}
* Trivial in the development sense, not trivial in the security sense.
At a presentation a few weeks ago someone asked me about capturing session details during authentication at an STS by way of frames and JavaScript. To paraphrase the question: “What prevents a malicious developer from sticking an RP within an iframe, cause a redirect to an STS, get some user to log in, and then capture the details through JavaScript from the parent page?” There are a couple of ways this problem can be solved. It’s a defense-in-depth problem where on their own, each piece won’t close every attack vector, but when used together you end up with a pretty solid solution.
- First, a lot of new browsers will actually prevent cross-frame JavaScript calls when SSL is involved. Depending on the browser, the JavaScript will throw the equivalent of an Access Denied exception. This is not the case with all browser versions though. Older browsers may not do this.
- Second, some browsers will not allow you to host an SSL page in a frame if the parent page is not using SSL. The easy fix for the malicious developer is to simply use SSL for the parent site, but that could be problematic as the CA’s theoretically verify the sites requesting certificates.
- Third, you could write some JavaScript for the STS to bust out of the frame. It would look something like this:
if (top != self)
{
try
{
top.location.replace(self.location.href);
}
catch (e)
{
}
}
The problem with this is that it wouldn’t work if the browser has JavaScript disabled.
- Fourth, there is a new HTTP header that Microsoft introduced in IE 8 that tells the browser that if the requested page is hosted in a frame to simply stop processing the request. Safari and Chrome support it natively, and Firefox supports it with the NoScript add on. The header is called X-Frame-Options and it can have two values: “DENY” which prevents all requests, and “SAMEORIGIN” which allows a page to be rendered if the parent page is the same page. E.g. the parent is somesite.com/page and the framed page is somesite.com/page.
There are a couple of ways to add this header to your page. First you can add it via ASP.NET:
Context.Response.AddHeader("x-frame-options", "DENY");
Or you could add it to all pages via IIS. To do this open the IIS Manager and select the site in question. Then select the Feature “HTTP Response Headers”:
Select Add… and then set the name to x-frame-options and the value to DENY:
By keeping in mind these options you can do a lot to prevent any exploits that use frames.
In a previous post we looked at what it takes to actually write a Security Token Service. If we knew what the STS offered and required already, we could set up a relying party relatively easily with that setup. However, we don’t always know what is going on. That’s the purpose of federation metadata. It gives us a basic breakdown of the STS so we can interact with it.
Now, if we are building a custom STS we don’t have anything that is creating this metadata. We could do it manually by hardcoding stuff in an xml file and then signing it, but that gets ridiculously tedious after you have to make changes for the third or fourth time – which will happen. A lot. The better approach is to generate the metadata automatically. So in this post we will do just that.
The first thing you need to do is create a endpoint. There is a well known path of /FederationMetadata/2007-06/FederationMetadata.xml that is generally used, so let’s use that. There are a lot of options to generate dynamic content and in Programming Windows Identity Foundation, Vitorrio uses a WCF Service:
[ServiceContract]
public interface IFederationMetadata
{
[ServiceBehavior]
[webGet(UriTemplate = "2007-06/FederationMetadata.xml")]
XElement FederationMetadata();
}
It’s a great approach, but for some reason I prefer the way that Dominick Baier creates the endpoint in StarterSTS. He uses an IHttpHandler and a web.config entry to create a handler:
<location path="FederationMetadata/2007-06">
<system.webServer>
<handlers>
<add
name="MetadataGenerator"
path="FederationMetadata.xml"
verb="GET"
type="Syfuhs.TokenService.WSTrust.FederationMetadataHandler" />
</handlers>
</system.webServer>
<system.web>
<authorization>
<allow users="*" />
</authorization>
</system.web>
</location>
As such, I’m going to go that route. Let’s take a look at the implementation for the handler:
using System.Web;
namespace Syfuhs.TokenService.WSTrust
{
public class FederationMetadataHandler : IHttpHandler
{
public void ProcessRequest(HttpContext context)
{
context.Response.ClearHeaders();
context.Response.Clear();
context.Response.ContentType = "text/xml";
MyAwesomeTokenServiceConfiguration
.Current.SerializeMetadata(context.Response.OutputStream);
}
public bool IsReusable { get { return false; } }
}
}
All the handler is doing is writing metadata out to a stream, which in this case is the response stream. You can see that it is doing this through the MyAwesomeTokenServiceConfiguration class which we created in the previous article. The SeriaizeMetadata method creates an instance of a MetadataSerializer and writes an entity to the stream:
public void SerializeMetadata(Stream stream)
{
MetadataSerializer serializer = new MetadataSerializer();
serializer.WriteMetadata(stream, GenerateEntities());
}
The entities are generated through a collection of tasks:
private EntityDescriptor GenerateEntities()
{
if (entity != null)
return entity;
SecurityTokenServiceDescriptor sts = new SecurityTokenServiceDescriptor();
FillOfferedClaimTypes(sts.ClaimTypesOffered);
FillEndpoints(sts);
FillSupportedProtocols(sts);
FillSigningKey(sts);
entity = new EntityDescriptor(new EntityId(string.Format("https://{0}", host)))
{
SigningCredentials = this.SigningCredentials
};
entity.RoleDescriptors.Add(sts);
return entity;
}
The entity is generated, and an object is created to describe the STS called a SecurityTokenServiceDescriptor. At this point it’s just a matter of sticking in the data and defining the credentials used to sign the metadata:
private void FillSigningKey(SecurityTokenServiceDescriptor sts)
{
KeyDescriptor signingKey
= new KeyDescriptor(this.SigningCredentials.SigningKeyIdentifier)
{
Use = KeyType.Signing
};
sts.Keys.Add(signingKey);
}
private void FillSupportedProtocols(SecurityTokenServiceDescriptor sts)
{
sts.ProtocolsSupported.Add(new System.Uri(WSFederationConstants.Namespace));
}
private void FillEndpoints(SecurityTokenServiceDescriptor sts)
{
EndpointAddress activeEndpoint
= new EndpointAddress(string.Format("https://{0}/TokenService/activeSTS.svc", host));
sts.SecurityTokenServiceEndpoints.Add(activeEndpoint);
sts.TargetScopes.Add(activeEndpoint);
}
private void FillOfferedClaimTypes(ICollection<DisplayClaim> claimTypes)
{
claimTypes.Add(new DisplayClaim(ClaimTypes.Name, "Name", ""));
claimTypes.Add(new DisplayClaim(ClaimTypes.Email, "Email", ""));
claimTypes.Add(new DisplayClaim(ClaimTypes.Role, "Role", ""));
}
That in a nutshell is how to create a basic metadata document as well as sign it. There is a lot more information you can put into this, and you can find more things to work with in the Microsoft.IdentityModel.Protocols.WSFederation.Metadata namespace.
Last week at TechDays in Toronto I ran into a fellow I worked with while I was at Woodbine. He works with a consulting firm Woodbine uses, and he caught my session on Windows Identity Foundation. His thoughts were (essentially—paraphrased) that the principle of Claims Authentication was sound and a good idea, however implementing it requires a major investment. Yes. Absolutely. You will essentially be adding a new tier to the application. Hmm. I’m not sure if I can get away with that analogy. It will certainly feel like you are adding a new tier anyway.
What strikes me as the main investment is the Security Token Service. When you break it down, there are a lot of moving parts in an STS. In a previous post I asked what it would take to create something similar to ADFS 2. I said it would be fairly straightforward, and broke down the parts as well as what would be required of them. I listed:
- 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)
These aren’t all that hard to develop. With the exception of the proxy services and token service itself, there’s a good chance we have created something similar to each one if user authentication is part of an application. We have the authentication endpoint: a login form to do SQL Authentication, or the Windows Authentication Provider for ASP.NET. We have the attribute store and something like a claims mapper: Active Directory, SQL databases, etc. We even have an application management tool: anything you used to manage users in the first place. This certainly doesn’t get us all the way there, but they are good starting points.
Going back to my first point, the STS is probably the biggest investment. However, it’s kind of trivial to create an STS using WIF. I say that with a big warning though: an STS is a security system. Securing such a system is NOT trivial. Writing your own STS probably isn’t the best way to approach this. You would probably be better off to use an STS like ADFS. With that being said it’s good to know what goes into building an STS, and if you really do have the proper resources to develop one, as well as do proper security testing (you probably wouldn’t be reading this article on how to do it in that case…), go for it.
For the sake of simplicity I’ll be going through the Fabrikam Shipping demo code since they did a great job of creating a simple STS. The fun bits are in the Fabrikam.IPSts project under the Identity folder. The files we want to look at are CustomSecurityTokenService.cs, CustomSecurityTokenServiceConfiguration.cs, and the default.aspx code file. I’m not sure I like the term “configuration”, as the way this is built strikes me as factory-ish.
The process is pretty simple. A request is made to default.aspx which passes the request to FederatedPassiveSecurityTokenServiceOperations.ProcessRequest() as well as a newly instantiated CustomSecurityTokenService object by calling CustomSecurityTokenServiceConfiguration.Current.CreateSecurityTokenService().
The configuration class contains configuration data for the STS (hence the name) like the signing certificate, but it also instantiates an instance of the STS using the configuration. The code for is simple:
namespace Microsoft.Samples.DPE.Fabrikam.IPSts
{
using Microsoft.IdentityModel.Configuration;
using Microsoft.IdentityModel.SecurityTokenService;
internal class CustomSecurityTokenServiceConfiguration
: SecurityTokenServiceConfiguration
{
private static CustomSecurityTokenServiceConfiguration current;
private CustomSecurityTokenServiceConfiguration()
{
this.SecurityTokenService = typeof(CustomSecurityTokenService);
this.SigningCredentials =
new X509SigningCredentials(this.ServiceCertificate);
this.TokenIssuerName = "https://ipsts.fabrikam.com/";
}
public static CustomSecurityTokenServiceConfiguration Current
{
get
{
if (current == null)
{
current = new CustomSecurityTokenServiceConfiguration();
}
return current;
}
}
}
}
It has a base type of SecurityTokenServiceConfiguration and all it does is set the custom type for the new STS, the certificate used for signing, and the issuer name. It then lets the base class handle the rest. Then there is the STS itself. It’s dead simple. The custom class has a base type of SecurityTokenService and overrides a couple methods. The important method it overrides is GetOutputClaimsIdentity():
protected override IClaimsIdentity GetOutputClaimsIdentity(
IClaimsPrincipal principal, RequestSecurityToken request, Scope scope)
{
var inputIdentity = (IClaimsIdentity)principal.Identity;
Claim name = inputIdentity.Claims.Single(claim =>
claim.ClaimType == ClaimTypes.Name);
Claim email = new Claim(ClaimTypes.Email,
Membership.Provider.GetUser(name.Value, false).Email);
string[] roles = Roles.Provider.GetRolesForUser(name.Value);
var issuedIdentity = new ClaimsIdentity();
issuedIdentity.Claims.Add(name);
issuedIdentity.Claims.Add(email);
foreach (var role in roles)
{
var roleClaim = new Claim(ClaimTypes.Role, role);
issuedIdentity.Claims.Add(roleClaim);
}
return issuedIdentity;
}
It gets the authenticated user, grabs all the roles from the RolesProvider, and generates a bunch of claims then returns the identity. Pretty simple.
At this point you’ve just moved the authentication and Roles stuff away from the application. Nothing has really changed data-wise. If you only cared about roles, name, and email you are done. If you needed something more you could easily add in the logic to grab the values you needed.
By no means is this production ready, but it is a good basis for how the STS creates claims.
Update: I should have mentioned this when I first posted, but some of these thoughts are the result of me reading Programming Windows Identity Foundation. While I hope I haven’t copied the ideas outright, I believe the interpretation is unique-ish. 
One of the main reasons we as developers shy away from new technologies is because we are afraid of it. As we learned in elementary school, the reason we are afraid usually boils down to not having enough information about the topic. I’ve found this especially true with anything security related. So, lets think about something for a minute.
I’m not entirely sure how valid a method this is for measure, but I like to think that as developers we measure our understanding of something by how much we abstract away the problems it creates. Now let me ask you this question:
How much of an abstraction layer do we create for identity?
Arguably very little because in most cases we half-ass it.
I say this knowing full well I’m extremely guilty of it. Sure, I’d create a User class and populate with application specific data, but to populate the object I would call Active Directory or SQL directly. That created a tightly coupled dependency between the application and the user store. That works perfectly up until you need to migrate those users in a SQL database to Active Directory. Oops.
So why do we do this?
My reason for doing this is pretty simple. I didn’t know any better. The reason I didn’t know better was also pretty simple. Of the available options to abstract away the identity I didn’t understand how the technology worked, or more likely, I didn’t trust it. Claims based authentication is a perfect example of this. I thought to myself when I first came across this: “are you nuts? You want me to hand over authentication to someone else and then I have to trust them that what they give me is valid? I don’t think so.”
Well, yes actually.
Authentication, identification, and authorization are simply processes in the grand scheme of an application lifecycle. They are privileged, but that just means we need to be careful about it. Fear, as it turns out, is the number one reason why we don’t abstract this part out.*
With that, I thought it would be a perfect opportunity to take a look at a few of the reasons why Claims based authentication is reasonably secure. I would also like to take this time to compare some of these reasons to why our current methods of user authentication are usually done wrong.
Source
First and foremost we trust the source. Obviously a bank isn’t going to accept a handwritten piece of paper with my name on it as proof that I am me. It stands to reason that you aren’t going to accept an identity from some random 3rd party provider for important proof of identity.
Encryption + SSL
The connection between RP and STS is over SSL. Therefore no man in the middle attacks. Then you encrypt the token. Much like the SSL connection, the STS encrypts the payload with the RP’s public key, which only the RP can decrypt with its private key. If you don’t use SSL anyone eavesdropping on the connection still can’t read the payload. Also, the STS usually keeps a local copy of the certificate for token encryption.
How many of us encrypt our SQL connections when verifying the user’s password? How many of us use secured LDAP queries to Active Directory? How many of us encrypt our web services? I usually forget to.
Audience whitelist
Most commercial STS applications require that each request come from an approved Relying Party. Moreover, most of those applications require that the endpoint that it responds to also be on an approved list. You could probably fake it through DNS poisoning, but the certificates used for encryption and SSL would prevent you from doing anything meaningful since you couldn’t decrypt the token.
Do we verify the identity of the application requesting information from the SQL database? Not usually the application. However, we could do it via Kerberos impersonation. E.g. lock down the specific data to the currently logged in/impersonated user.
Expiration and Duplication Prevention
All tokens have authentication timestamps. They also normally have expiration timestamps. Therefore they have a window of time that defines how long they are valid. It is up to the application accepting the token to make sure the window is still acceptable, but it is still an opportunity for verification. This also gives us the opportunity to prevent replay attacks. All we have to do is keep track of all incoming tokens within the valid time window and see if the tokens repeat. If so, we reject them.
There isn’t much we can do in a traditional setting to prevent this from happening. If someone eavesdrops on the connection and grabs the username/password between the browser and your application, game over. They don’t need to spoof anything. They have the credentials. SSL can fix this problem pretty easily though.
Integrity
Once the token has been created by the STS, it will be signed by the STS’s private key. If the token is modified in any way the signature wont match. Since it is being signed by the private key of the STS, only the STS can resign it, however anyone can verify the signature through the STS’s public key. And since it’s a certificate for the STS, we can use it as strong proof that the STS is who they say they are. For a good primer on public key/private key stuff check out Wikipedia.
It's pretty tricky to modify payloads between SQL and an application, but it is certainly possible. Since we don’t usually encrypt the connections (I am guilty of this daily – It’s something I need to work on 
), intercepting packets and modifying them on the fly is possible. There isn’t really a way to verify if the payload has been tampered with.
Sure, there is a level of trust between the data source and the application if they are both within the same datacenter, but what if it’s being hosted offsite by a 3rd party? There is always going to be a situation where integrity can become an issue. The question at that point then is: how much do you trust the source, as well as the connection to the source?
Authentication Level
Finally, if we are willing to accept that each item above increases the security and validity of the identity, there is really only one thing left to make sure is acceptable. How was the user authenticated? Username/password, Kerberos, smart card/certificates, etc. If we aren’t happy with how they were authenticated, we don’t accept the token.
So now that we have a pretty strong basis for what makes the tokens containing claims as well as the relationship between the RP’s and STS’s secure, we don’t really need to fear the Claims model.
Now we just need to figure out how to replace our old code with the identity abstraction.
* Strictly anecdotal evidence, mind you.
Yet another presentation on the docket! I submitted an abstract to SharePoint Summit 2011 and they accepted! I will be presenting on SharePoint and how it manages Identity. More specifically, how SharePoint 2010 uses WIF to handle Claims based authentication and Federation.
Here are the details
Event: SharePoint Summit 2011, January 31st 2011 – February 2nd, 2011
When: 11:30 a.m. - 12:45 p.m. February 1st, 2011
Where: Four Seasons Hotel, Toronto
Abstract: Managing identities within an organization is relatively easy. However, as business changes, we need to be able to adapt quickly. Identity is something that often gets overlooked in adaptation. In this session we will discuss the Windows Identity Foundation and how SharePoint uses it to adapt easily to change.
Link: http://www.sharepointsummit2011.com/Toronto/conference_day2.htm#session_7_3
Earlier this morning I got an email from John
Bristowe congratulating me on being selected to present a session for the local
flavours track at TechDays in Toronto!
This bumps
up my count to 2. Needless to say I am REALLY excited.
I was a little disappointed to find out there weren’t any sessions on the Windows
Identity Foundation, so that just meant I had to submit my own to the local flavours
track…and they accepted it! Here are the details:
October 27, 3:40 PM to 4:45 PM
Breakout | LFT330: Windows Identity Foundation Simplified: All the Scary Things
Made Un-Scary
The Windows Identity Foundation helps simplify user access for developers by externalizing
user access from applications via claims and reducing development effort with pre-built
security logic and integrated .NET tools. This presentation is an intimate discussion
on the basics of the Windows Identity Foundation and its claims model. In this session,
you’ll learn how to refactor an existing sample set of applications to use WIF, to
connect identities to the Cloud, and to remove the burden of managing multiple disparate
user stores.
Location: Metro Toronto Convention
Centre - South Building (255 Front Street West, Toronto)
Room: TBA
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…
Telling SharePoint about the STS
Once you’ve collected all the information you need, open up PowerShell as an Administrator
and add the SharePoint snap-in on the server.
Add-PSSnapin Microsoft.SharePoint.PowerShell
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.
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.
In a domain environment it is really useful to switch user contexts in a web application.
This could be if you are needing to log in with credentials that have elevated permissions
(or vice-versa) or just needing to log in as another user.
It’s pretty easy to do this with Windows Identity Foundation and Claims Authentication.
When the WIF framework is installed, a service is installed (that is off by default)
that can translate Claims to Windows Tokens. This is called (not surprisingly)
the Claims to Windows Token Service or (c2WTS).
Following the deploy-with-least-amount-of-attack-surface methodology, this
service does not work out of the box. You need to turn it on and enable which
user’s are allowed to impersonate via token translation. Now, this doesn’t mean
which users can switch, it means which users running the process are allowed to switch.
E.g. the process running the IIS application pools local service/network service/local
system/etc (preferably a named service user other than system users).
To allow users to do this go to C:\Program Files\Windows Identity Foundation\v3.5\c2wtshost.exe.config
and add in the service users to <allowedCallers>:
<windowsTokenService>
<!--
By default no callers are allowed to use the Windows
Identity Foundation Claims To NT Token Service.
Add the identities you wish to allow below.
-->
<allowedCallers>
<clear/>
<!-- <add value="NT AUTHORITY\Network Service"
/> -->
<!-- <add value="NT AUTHORITY\Local Service" />
–>
<!-- <add value="nt authority\system" /> –>
<!-- <add value="NT AUTHORITY\Authenticated Users"
/> -->
</allowedCallers>
</windowsTokenService>
You should notice that by default, all users are not allowed. Once you’ve done
that you can start up the service. It is called Claims to Windows Token
Service in the Services MMC snap-in.
That takes care of the administrative side of things. Lets write some code.
But first, some usings:
using System;
using System.Linq;
using System.Security.Principal;
using System.Threading;
using Microsoft.IdentityModel.Claims;
using Microsoft.IdentityModel.WindowsTokenService;
The next step is to actually generate the token. From an architectural perspective,
we want to use the UPN claims type as that’s what the service wants to see.
To get the claim, we do some simple LINQ:
IClaimsIdentity identity = (ClaimsIdentity)Thread.CurrentPrincipal.Identity;
string upn = identity.Claims.Where(c => c.ClaimType == ClaimTypes.Upn).First().Value;
if (String.IsNullOrEmpty(upn))
{
throw new Exception("No UPN claim found");
}
Following that we do the impersonation:
WindowsIdentity windowsIdentity = S4UClient.UpnLogon(upn);
using (WindowsImpersonationContext ctxt = windowsIdentity.Impersonate())
{
DoSomethingAsNewUser();
ctxt.Undo(); // redundant with using { } statement
}
To release the token we call the Undo() method, but if you are within a using { }
statement the Undo() method is called when the object is disposed.
One thing to keep in mind though. If you do not have permission to impersonate
a user a System.ServiceModel.Security.SecurityAccessDeniedException will be thrown.
That’s all there is to it.
Implementation Details
In my opinion, these types of calls really shouldn’t be made all that often.
Realistically you need to take a look at how impersonation fits into the application
and then go from there. Impersonation is pretty weighty topic for discussion,
and frankly, I’m not an expert.
