Free Trial *Internet Service Required
2 out of 4 rated this helpful - Rate this topic

Code Sample: OAuth 2.0 Delegation

Published: April 7, 2011

Updated: April 9, 2013

Applies To: Windows Azure

This sample illustrates an end-to-end scenario that includes a resource protected by Windows Azure Active Directory Access Control (also known as Access Control Service or ACS) and a client application that consumes this resource. The web application uses the OAuth protocol, version 2.0, draft 13, and accesses the ACS OAuth 2.0 endpoint to obtain an access token for the resource. This version of the sample targets the ACS production environment in the Windows Azure portal (http://go.microsoft.com/fwlink/?LinkId=130560).

The code for this sample is part of the Windows Identity Foundation Extension for OAuth CTP and can be downloaded at http://go.microsoft.com/fwlink/?LinkID=244575.

Follow the steps outlined below to run the sample.

Prerequisites

  1. Windows Server 2008 R2 or Windows 7

  2. Visual Studio 2010

  3. Internet Information Services (IIS) enabled with IIS Metabase and IIS6 Configuration Compatibility

  4. Windows Identity Foundation (http://go.microsoft.com/fwlink/?LinkId=204657)

Scenario Description

This sample depicts two different companies. One company, Contoso, has a Representational State Transfer (REST) web service for information about certain Contoso employees that is exposed on the web. This service contains two components: the End-user endpoint, which allows users of the service to log in and delegate permission to applications to access their data, and the Service endpoint, which requires an OAuth access token issued by ACS in order to access data in it.

The second company in the solution, Fabrikam, offers a portal in which subscribers to the Contoso employee information can view the information. This web server application performs the role of the “OAuth client”. If an access token has expired, the Fabrikam site is configured to automatically obtain a new token using the refresh token that ACS sent with the original access token.

Projects included in this sample

 

AuthorizationServer

An ASP.NET web application that serves as the end-user endpoint for the Contoso Customer Information service that allows customers to log in and give consent to applications accessing the service.

Common

This project contains the helper functions to interact with ACS as well as the configuration information for the solution.

ConfigureAcsConsoleApplication

A console application that must be run once the configuration information has been added to the solution.

CustomerInformationService

A WCF REST service that is protected using OAuth and accepts tokens from ACS to allow access.

WebClient

An ASP.NET web application that accesses data at the CustomerInformationService.

Set up the Sample

The sample must be configured to target a tenant. Use the following procedure:

  1. Run SetupSample.bat in the Sample Root Directory

  2. Open the Solution File

  3. Set up the ACS

  4. Enter the configuration information into the sample file.

Run SetupSample.bat in the Sample Root Directory

Run the SetupSample.bat batch file with administrator permissions. The directory which you run the samples from must not be located in the folder C:\Users (which includes the Desktop and Documents folders) for the samples to function correctly. This will set up the Internet Information Services (IIS) with virtual directories for the samples and will set up the certificates necessary to use https in the samples.

Open the Solution File

Open the solution file, OAuth with ACS.sln, in Visual Studio 2010 as an administrator.

Set up ACS

To create an Access Control namespace

  1. Go to the Windows Azure Management Portal, sign in, and then click Active Directory.

  2. To create an Access Control namespace, click New, click App Services, click Access Control, and then click Quick Create. (Or, click Access Control Namespaces before clicking New.)

  3. Enter a name for your namespace. This name will be a unique subdomain in the accesscontrol.windows.net domain. For example, if you enter contoso, your Access Control namespace endpoints will reside as paths of https://contoso.accesscontrol.windows.net.

    Also, in the value of the ServiceNamespace variable in the SamplesConfiguration.cs sample application, enter the name of your Access Control namespace.

    noteNote
    You do not have to use the same for both client and service applications.

  4. The portal verifies that the name that you selected for your Access Control namespace is valid and available. If it is not, enter a different name.

  5. Select a region and then click OK.

  6. The system now creates and activates your Access Control namespace.

    You might have to wait several minutes as the system provisions resources for your account.

To create a new Service Identity

  1. To manage an Access Control namespace, select the namespace, and then click Manage. (Or, click Access Control Namespaces, select the namespace, and then click Manage.)

    This action opens the ACS portal. You can use the portal to configure the Access Control namespace. It allows you to add identity providers, configure relying parties, define rules and groups of rules, establish the credentials your relying party will trust, and it offers tips about how to integrate into your relying party.

  2. Click Service identities.

    In this sample, we will create a new service identity to be used as the OAuth credential that the Fabrikam site uses to access the Customer Information Service.

  3. To create a new service identity, click Add.

  4. In the Name field, enter FabrikamClient.

  5. From the Type list, select Password, and in the Password field, enter FabrikamSecret.

To add a new Relying Party Application

  1. Click Relying party applications. To create a new application, click Add.

  2. Enter Customer Information Service for the name of the relying party application, enter http://contoso/CustomerInformationService/ for the Realm, and http://localhost/ for the Return URL.

  3. For the token format, select SWT, and clear the Windows Live ID box.

  4. To generate a symmetric key that will be used by the service to validate the signature of the SWT tokens it receives, under Token Signing Options, click Generate. Enter this key in the sample application in SamplesConfiguration.cs as the value of the RelyingPartySigningKey variable.

  5. Click Save.

Enter the Configuration Information into the Sample

To enter the configuration information into the sample

  1. By now, the Access Control namespace name and the Relying Party Signing Key have been entered in the SamplesConfiguration.cs file in the Visual Studio solution.

  2. To enter the Management Service Key in the ManagementServiceIdentityKey variable in SamplesConfiguration.cs, click Management service, click Management Client, and then click Symmetric Key. This key is used to communicate with the ACS Management Service.

  3. To add the final configuration to ACS, in Visual Studio, right-click ConfigureAcsConsoleApplication, click Debug, and then click Start new instance. When the console application completes, press any button to continue.

Scenario walkthrough

The following diagram shows a high-level view of the OAuth protocol flow of this sample.

In this diagram, the green boxes represent OAuth-specific components that use the WIF extensions to handle the protocol flow separately from the main web site. The red box represents ACS as a cloud service that has been configured to interact with the various sample components. The blue boxes represent the other components that a developer implementing this scenario would consider.

This flow uses the Authorization Code access grant type. This is used when the OAuth client is capable of interacting with the end-user’s web browser or other user agent. In this case, the client redirects the user’s browser to the End-user endpoint to authenticate with the service that will be accessed. After the user has been authenticated, the user has to consent to the client’s access request. When the user grants access, the browser is redirected back to the client with an Authorization code with which an access token can be requested. The access token is stored once it is received and will be attached to subsequent requests to the service until it expires. ACS also sends refresh tokens which can be used to request new access tokens without having to redirect the user away from your site.

Running the Sample

To run the sample

  1. If the solution is not already open, open it in Visual Studio. Build the solution.

  2. In a web browser, navigate to https://localhost/WebClient. This site will access data from the CustomerInformationService on your behalf.

  3. Click Populate all data. Your browser will be redirected to the Customer Information Service login page. Enter the following credentials:

    • User name: John

    • Password: password

  4. Click Log In. You will be directed to the delegation site where you can choose to allow the Fabrikam Information Portal to have access to your data. Click Submit.

  5. This will return you to the original site with the data populated. The OAuth Client has used the information in the response to request an OAuth “Access token” that it attaches to a request to the Customer Information Service. This token will be used in subsequent requests so that you no longer need to provide credentials to log in to the site. The contents of the token are displayed in a table.

Using Refresh Tokens

The Fabrikam website is configured to store and use the refresh token provided by ACS when the access token expires. Use the following steps to configure ACS to issue short-lived tokens and see new tokens issued.

To use refresh tokens

  1. In the ACS Management Portal, click Relying Party Applications.

  2. Click Customer Information Service. This will take you to the Edit Relying Party Application page.

  3. Change the value of Token lifetime (secs) to 5 so that the tokens will only be valid for a short period of time.

  4. Click Save.

  5. Open a new browser window or clear your browser’s cache.

  6. On the Fabrikam OAuth Client website, click Populate all data or Get customer data by ID multiple times and notice the contents of the access token change. The information in the token will be the same except for the ExpiresOn time and the signature.

Troubleshooting

  • If you receive an HTTP Error 500.21 or 500.19 Internal Server Error when running the sample on a computer with more than one version of the .NET Framework installed or where .NET was installed before IIS, follow the instructions at ASP.NET IIS Registration Tool (http://go.microsoft.com/fwlink/?LinkId=202577) to register ASP.NET with IIS.

  • If after clicking the Populate all data button on the Fabrikam Client Website, the page remains unchanged, verify that you have run the ConfigureAcsConsoleApplication project. Alternatively, attach a program to monitor the Http traffic to see any error messages contained in the URL as the browser is redirected.

Did you find this helpful?
(1500 characters remaining)
© 2013 Microsoft. All rights reserved.
facebook page visit twitter rss feed newsletter