{"id":1163,"date":"2010-08-19T11:07:58","date_gmt":"2010-08-19T11:07:58","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/odatateam\/2010\/08\/19\/odata-and-authentication-part-8-oauth-wrap\/"},"modified":"2010-08-19T11:07:58","modified_gmt":"2010-08-19T11:07:58","slug":"odata-and-authentication-part-8-oauth-wrap","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/odata\/odata-and-authentication-part-8-oauth-wrap\/","title":{"rendered":"OData and Authentication \u2013 Part 8 \u2013 OAuth WRAP"},"content":{"rendered":"

OAuth WRAP is a claims based authentication protocol supported by the AppFabric<\/a> Access Control (ACS) which is part of Windows Azure<\/a>.<\/p>\n

But most importantly it is REST (and thus OData) friendly too.<\/p>\n

The idea is that you authenticate against an ACS server and acquire a Simple Web Token or SWT \u2013 which contains signed claims about identity \/ roles \/ rights etc \u2013 and then embed the SWT in requests to a resource server that trusts the ACS server.<\/p>\n

The resource server then looks for and verifies the SWT by checking it is correctly signed, before allowing access based on the claims made in the SWT.<\/p>\n

If you want to learn more about OAuth WRAP itself here\u2019s the spec<\/a>.<\/p>\n

Goal<\/h3>\n

Now we know the principles behind OAuth WRAP it\u2019s time to map those into the OData world.<\/p>\n

Our goal is simple. We want an OData service that uses OAuth WRAP for authorization and a client to test it end to end.<\/p>\n

Why OAuth WRAP?<\/h3>\n

You might be wondering why this post covers OAuth WRAP and not OAuth 2.0<\/a>. <\/p>\n

OAuth 2.0 essentially combines the best features of OAuth 1.0 and OAuth WRAP.<\/p>\n

Unfortunately OAuth 2.0 is not yet a ratified standard, so ACS doesn\u2019t support it yet. On the other hand OAuth 1.0 is cumbersome for RESTful protocols like OData. So that leaves OAuth WRAP.<\/p>\n

However once it is ratified OAuth 2.0 will essentially depreciate OAuth WRAP and ACS will rev to support it. When that happens you can expect to see a new post in this Authentication Series.<\/p>\n

Strategy<\/h3>\n

First we\u2019ll provision an ACS server to act as our identity server.<\/p>\n

Next we\u2019ll configure our identity server with appropriate roles, scopes and claim transformation rules etc.<\/p>\n

Then we\u2019ll create a HttpModule (see part 5<\/a>) to intercept all requests to the server, which will crack open the SWT, convert it into an IPrincipal and store it in HttpContext.Current.Request.User. This way it can be accessed later for authorization purposes inside the Data Service.<\/p>\n

Then we\u2019ll create a simple OData service using WCF Data Services and protect it with a custom HttpModule.<\/p>\n

Finally we\u2019ll write client code to authenticate against the ACS server and acquire a SWT token. We\u2019ll use the techniques you saw in part 3<\/a> to send the SWT as part of every request to our OData services.<\/p>\n

Step 1 \u2013 Provisioning an ACS server<\/h3>\n

First you\u2019ll need an Windows Azure account<\/a> and a running AppFabric namespace.<\/p>\n

Once your namespace is running you also have a running ACS server.<\/p>\n

Step 2 \u2013 Configuring the ACS server<\/h3>\n

To correctly configure the ACS server you\u2019ll need to Install the Windows Azure Platform AppFabric SDK which you can find here<\/a>.<\/p>\n

ACM.exe is a command line tool that ships as part of the AppFabric SDK, and that allows you to create Issuers, TokenPolicies, Scopes and Rules.<\/p>\n

For an introduction to ACM.exe and ACS look no further than this excellent guide<\/a> by Keith Brown<\/a>.<\/p>\n

To simplify our acm commands you should edit your ACM.exe.config file to include information about your ACS like this:<\/p>\n

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
  <appSettings>
    <add key="host" value="accesscontrol.windows.net"\/>
    <add key="service" value="{Your service namespace goes here}<\/strong>"\/>
    <add key="mgmtkey" value="{Your Windows Azure Management Key goes here}<\/strong>"\/>
  <\/appSettings>
<\/configuration><\/font><\/p>\n

Doing this saves you from having to re-enter this information every time you run ACM. <\/p>\n

Very handy.<\/p>\n

Claims Transformation<\/h4>\n

Before we start configuring our ACS we need to know a few principles\u2026<\/p>\n

Generally claims authentication is used to translate a set of input claims into a signed set of output claims. <\/p>\n

Sometimes this extends to Federation, which allows trust relationships to be established between identity providers, such that a user on one system can gain access to resources on another system.<\/p>\n

However in this blog post we are going to keep it simple and skip federation.  <\/p>\n

Don\u2019t worry though we\u2019ll add federation in the next post.<\/p>\n

Issuers<\/h4>\n

In ACS terms an Issuer represents a security principal. And whether we want federation or not our first step is to create a new issuer like this:<\/p>\n

> acm create issuer
    -name: partner
<\/strong><\/font><\/font>    -issuername: partner
    -autogeneratekey<\/strong><\/font><\/font> <\/p>\n

This will generate a key which you can retrieve by issuing this command:<\/p>\n

> acm getall issuer
      <\/strong><\/font>Count: 1 <\/strong><\/font><\/p>\n

         id: iss_89f12a7ed023c3b7b0a85f32dff96fed2014ad0a
       name: odata-issuer
issuername: odata-issuer
        key: 9QKoZgtxxU4ABv8uiuvaR+k0cOmUxfEOE0qfPK2lCJY=
previouskey: 9QKoZgtxxU4ABv8uiuvaR+k0cOmUxfEOE0qfPK2lCJY=
  algorithm: Symmetric256BitKey<\/strong><\/font> <\/p>\n

Our clients are going to need to know this key, so make a note of it for later.<\/p>\n

Token Policy <\/h4>\n

Next we need a token policy. Token Policies specify a timeout indicating how long a new Simple Web Token (or SWT) should be valid, or put another way, how long before the SWT expires.<\/p>\n

When creating a token policy you need to balance security versus ease of use and convenience. The shorter the timeout the more likely it is to be based on up to date Identity and Role information, but that comes at the cost of frequent refreshes, which have performance and convenience implications.<\/p>\n

For our purposes a timeout of 1 hour is probably about right. So we create a new policy like this:<\/p>\n

> acm create tokenpolicy
    -name: odata-service-policy
    -timeout: 3600
    -autogeneratekey<\/strong><\/font><\/p>\n

Where 3600 is the number of seconds in an hour. To see what you created issue this command:<\/p>\n

> acm getall tokenpolicy
<\/strong><\/font>  Count: 1 <\/strong><\/font><\/p>\n

     id: tp_aaf3fd9ca64d4471a5c7b5c572c087fb
   name: odata-service-policy
timeout: 3600
    key: WRwJkQ9PgbhnIUgKuuovw\/6yVAo\/Dh0qrb7rqQWnsBk=<\/strong><\/font><\/p>\n<\/p>\n

We\u2019ll need both the id and key later. <\/p>\n

This key is what we share with our resource servers, so that they can check SWTs are correctly signed. We\u2019ll come back to that later.<\/p>\n

Scope<\/h4>\n

A service may have multiple \u2018scopes\u2019 each with a different set of access rules and rights.<\/p>\n

Scopes are linked to a token policy, telling ACS how long SWTs should remain valid, how to sign the SWT, and scopes contain a set of rules which tell ACS how to translate incoming claims into claims embedded in the SWT.<\/p>\n

When requesting a SWT a client must include an \u2018applies_to\u2019 parameter, which tells ACS for which scope they need a SWT, and consequently which token policy and rules should apply when constructing the SWT.<\/p>\n

Here are just some of the reasons you might need multiple scopes:<\/p>\n