OAuth 2.0 Certificate Authentication Readme
This sample illustrates how to authenticate to ACS using the OAuth 2.0 protocol by presenting a SAML token signed by an X.509 certificate. This certificate corresponds to a ServiceIdentity configured on ACS, and
ACS issues a SWT with a nameidentifier claim of the ServiceIdentity. This SWT is used to authenticate to an OAuth 2.0 protected resource. This sample conforms to
draft 13 of the OAuth 2.0 protocol. The code for this sample is in the
OAuth2 folder of the
ACS 2.0 samples package.
Prerequisites
To run this sample, you will need:
1. To create an account at
http://windows.azure.com and create an Access Control Service namespace.
2. Visual Studio 2010 (any version)
See Prerequisites
for more details. Note that it may be beneficial to walkthrough the Getting Started
sample before running this sample.
Configuring the Sample
The ACS configuration required for this sample can be performing using either the ACS management portal, or the ACS management service. Select one
of the two options below to go to the relevant section.
Option 1: Configuring via the ACS Management Portal
1. Open a browser and navigate to
http://windows.azure.com and sign in. From there, navigate to the
Service Bus, Access Control, and Caching section to configure your ACS service namespace. Once you have created a namespace, select it and click
Manage > Access Control Service at the top of the page. This should launch the following page in a new window:
2. Next, register your application with ACS by creating a relying party application. Click the
Relying party applications link on the main page, then select
Add and enter the following information in the subsequent form. Be sure to select
SWT as the token type, and click Generate to create a key below. When complete, click the
Save button and then navigate back to the main page.
3. With your relying party registered, it is now time to create the rules that determine the claims that ACS will issue to your application. In this sample we will create a rule that grants any
claim generated by ACS to passthrough. To do this, navigate to the main portal page and select
Rule Groups. From there, select the Default Rule Group for OAuth2 RP. Add a new rule, similar to the following:
4. In contrast to the web site samples, this sample relies on credentials managed by ACS. The last step in configuring ACS is registering the client certificate for the client application to use.
To configure a new client certificate, select the Service Identities link on the main portal page. Click the
Add link and type a name. Add a Credential Type of X.509 Certificate, and browse for the ACS2ClientCertificate.cer file in the Certificates folder of this sample. Click
Save and return to the main portal page.
5. With ACS now configured, open Visual Studio.
Option 2: Configuring via the ACS Management Service
The Visual Studio sample solution has a console application called
ConfigureSample which uses the ACS Management Service and the common helpers defined in the
Common class library. This application can be used to configure your ACS service namespace for use with this sample.
1. Update the
Common class library with information about your Service Namespace. Open
SamplesConfiguration.cs and enter your:
- ServiceNamespace -
This is the namespace used with ACS.
- ManagementServiceIdentityName -
This is a management service account’s Name
- ManagementServiceIdentityKey
- This is the password associated with the management service account.
- AcsHostUrl -
This is the host name of the ACS
2. Run the
ConfigureSample application in Visual Studio, which will configure ACS to run this sample.
3. When the
ConfigureSample application completes, it will output the generated relying party signing key to the console. Copy this key to the clipboard.
Running the Sample
1. Open the sample in Visual Studio. In addition to
ConfigureSample and Common, the solution consists of two projects:
ProtectedResourceWebApp and Client.
2. If you did not do so during configuration, enter your Service Namespace details in
Common\SamplesConfiguration.cs. See step 1 of
“Option 2: Configuring via the ACS Management Service” above. This file is also used by the
Client project.
3. Open the web.config in the
ProtectedResourceWebApp
project.
4. Enter your token signing key in the appropriate AppSettings elements. If you configured ACS using the management service, this is the value that you copied to the clipboard. If needed, refer back to the
Certificates and Keys area of the portal to obtain the token signing key. Below is a code snippet showing this area of the web.config file.
<appSettings>
<add key="SigningKey" value="...Copy Signing Key..."/>
</appSettings>
5. It is time to run the sample! Start the
ProtectedResourceWebApp. A web browser appears, but the text box is empty because the web browser is unauthenticated.
6. Run Client. HTML is displayed in a console window similar to the following. Note that the HTML indicates that the user is authenticated and displays the claims from ACS.
