Introduction
Starting with .NET 4.5 we receive a completely integrated environment for managing security in the .NET Framework. By using Windows Identity Foundation (WIF) we're able no only consume identity providers like Windows Azure Access Control Service (ACS) and Active Directory Federation Services but also create our own Security Token Services (STS).
Currently Windows Azure ACS still not support custom Identity Providers except OpenID, WS-Federation and build-in Facebook OAuth apps, so when you plan to extend you Single Sign-on (SSO) endpoint with custom OAuth provider you should choose whether create OAuth to OpenID or OAuth to WS-Federation token translation service.
Since we want to add Twitter as a custom ACS Identity Provider and use Twitter's token in our apps we choose extensible WS-Federation STS.
Twitter Authorization
Twitter platform offers authorization via OAuth 1.0a protocol and limited (application-only) via OAuth 2.0. We need to provide browser-based user authentication so choose for user identity retrieving OAuth 1.0a protocol. In this scenario for user authorization we should use Twitter application. At the following picture we can see components interaction:
Here claims-aware app requests a list of identity providers from SSO and after that navigates to the authorization URL of our custom STS which in turn redirect user to the Twitter authorization page. After successful authorization process Twitter redirects user to our custom STS which transforms OAuth identity into custom WS-Federation token with a few claims. Following claims are available in our implementation:
- Name - user name in Twitter platform.
- Name Identifier - user identifier in Twitter platform.
- Twitter Token - Twitter token.
- Twitter Token Secret - Twitter Token Secret.
Twitter STS Implementation
Since our target framework is .NET 4.5 we got WIF out of the box. In the previous .NET framework versions we should use custom WIF nuget package. Please note, WIF classes in the .NET 4.5 located in the different namespaces. Latest source code can be obtained from the project page.
ASP.NET MVC STS
WS-Federation STS should provide following features:
- WS-Federation metadata endpoint.
- SSO authorization endpoint.
- Twitter callback request handler.
WS-Federation metadata endpoint of our custom STS generates responses with a service definition information which contains following payload: issuer service name, claims list and authorization endpoints. Metadata should be a digitally signed XML.
Generally SSO at the authorization stage appends query parameters which indicates authorization request context. Since before sending authorization request to Twitter we should obtain a request token and by leveraging it we can generate dynamical callback for Twitter, so we can easily pass SSO context information into Twitter callback URL.
After receiving authentication response from Twitter we should generate WS-Federation token with claims declared in the service's metadata and return that token to the SSO. Due to URL length restrictions we unable to use simple redirect to WS-Federation SSO. In the response stage we should send serialized token value as an application/x-www-form-urlencoded HTTP message. Fortunately WIF provides build-in support for generating HTML code for such forms.
SignInResponseMessage responseMessage = FederatedPassiveSecurityTokenServiceOperations
.ProcessSignInRequest(requestMessage, principal, this);
var htmlResponseForm = responseMessage.WriteFormPost();
Twitter Communication
For accessing Twitter REST APIs we wouldn't implement a new wheel and use TweetSharp nuget package. It allows us initialize Twitter authorization by using Twitter app's consumer key & secret and handles Twitter response.
var service = new TwitterService(consumerKey, consumerSecret);
var callbackUri = new UriBuilder(callback)
{
Query = string.Format("context={0}", context)
};
OAuthRequestToken requestToken = service.GetRequestToken(callbackUri.ToString());
var authorizationUri = service.GetAuthorizationUri(requestToken);
Consuming Twitter STS
Creating a Twitter App
Before running MVC application we should create a new Twitter application. Navigate to: https://dev.twitter.com/apps and click on "Create a new application". Fill the form and set in the callback URL field base STS URL, for instance in the example application its http://127.0.0.1:12525:
After creation of Twitter app click on the Settings tab, check the "Allow this application to be used to Sign in with Twitter" option and save changes by click on the "Update this Twitter application's settings" button.
Creating Azure ACS
Right now we should create a SSO service which should consume our WS-Federation STS. So go to the Azure Management Portal and choose New -> App Services -> Access Control -> Quick Create and fill simple form.
Configuring ASP.NET MVC STS Application
When we've a Twitter app and Azure ACS we should set our ASP.NET app's settings. For that open the Web.config and replace in the appSettings section "TwitterConsumerKey" and "TwitterConsumerSecret" settings with Twitter app's OAuth settings from Detailed tab. After that replace in the "TwitterWtRealm" and "TwitterWReply" settings {acs_namespace} value with your ACS namespace.
Adding Twitter STS as a new ACS Identity Provider
Since we've completely configured our Twitter STS we must run it. As a test we can request service metadata. For instance in our example application we should visit in the browser next page: http://127.0.0.1:12525/wsfederation/twittermetadata. If you unable to see Federation Metadata XML content checkout whether port 12525 is not used by other app and if so change it in the project settings and Twitter app's callback URL.
Save Federation Metadata XML file (Ctrl+S) on your computer - it'll be required at the next step.
Currently we should configure our STS as a new ACS WS-Federation Identity Provider. For that navigate to Azure Management Portal, click on Active Directory service group, select Access Control Namespaces select your ACS and press Manage button.
In the Access Control Service configuration click on Identity providers and press Add. At the next page select WS-Federation identity provider option and press Next. You'll see form where in the WS-Federation metadata section select file and choose saved on the previous step FederationMetadata XML file. If you run STS app on HTTP endpoint uncheck Require URLs in metadata to use HTTPS (recommended) option. After that configure Relying party applications and press Save button.
That's all. If you want to create a new example claims-aware application take a look at the reference for ASP.NET MVC or ASP.NET Web Forms applications.
