Code Sample: OAuth 2.0 Certificate Authentication

  • Article

Updated: June 19, 2015

Applies To: Azure

This sample illustrates how to authenticate to Microsoft Azure Active Directory Access Control (also known as Access Control Service or 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 located in the OAuth2 (C#\OAuth2) subdirectory of the Microsoft Azure Active Directory Access Control (ACS) Code Samples package.

Prerequisites

To run this sample, you will need:

  1. An account in the Azure portal and an Access Control namespace.

  2. Visual Studio 2010 (any version)

For more details, see ACS Prerequisites (https://go.microsoft.com/fwlink/?LinkId=221065).

Configuring the Sample

The ACS configuration required for this sample can be performed using either the ACS Management Portal or the ACS Management Service. This topic describes both options.

  1. Option 1: Configuring the Sample Using the ACS Management Portal

  2. Option 2: Configuring the Sample Using the ACS Management Service

Option 1: Configuring the Sample Using the ACS Management Portal

To configure the sample using the ACS Management Portal

  1. Go to the Microsoft Azure Management Portal (https://manage.WindowsAzure.com), sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

  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. 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 Access Control Service management portal.

  4. To register your application with ACS, click Relying party applications, click Add, and then type the following information in the form:

    • In the Name field, enter OAuth2 RP

    • In the Realm field, enter https://oauth2relyingparty/

    • In the Token format field, select SWT

    • Click Generate to create a new key

    • In the Expiration Date field, enter an appropriate expiration date for the key. The key will no longer be valid on this date.

  5. Click Save.

  6. 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 pass through.

    To create this rule, click Rule Groups, and then click Default Rule Group for OAuth2 RP. Use the following settings to add a new rule:

    • In the Claim issuer section, select Access Control Service

    • In the Input claim type section, select Any

    • In the Input claim value section, select Any

    • In the Output claim type section, select Pass through input claim type

    • In the Output claim value section, select Pass through input claim value

  7. This sample relies on credentials managed by ACS.

    To configure a new client certificate for the client application, click Service Identities, click Add, and then 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.

  8. Now that ACS is configured, open Visual Studio.

Option 2: Configuring the Sample Using the ACS Management Service

The Visual Studio sample solution has a console application called ConfigureSample that uses the ACS Management Service and the common helpers defined in the Common class library. This application can be used to configure your Access Control namespace for use with this sample.

To configure the sample using the ACS Management Service

  1. Update the Common class library with information about your Access Control namespace. Open SamplesConfiguration.cs and enter the following:

    • ServiceNamespace - This is the name of your Access Control namespace

    • 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 ACS

  2. Run the ConfigureSample application in Visual Studio. This 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

To run 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 have not already done so, enter your Access Control namespace details in Common\SamplesConfiguration.cs. For more information, 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 file in the ProtectedResourceWebApp project.

  4. Enter your token signing key in the appropriate AppSettings elements. If you used the Management Service to configure ACS, this is the value that you copied to the clipboard. To obtain the token signing key, in the ACS portal, click Certificates and Keys. Below is a code snippet that show this section of the web.config file:

    <appSettings>
   <add key="SigningKey" value="...Copy Signing Key..."/>
</appSettings>

  5. 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 will be displayed in a console window. Note that the HTML indicates that the user is authenticated and displays the claims from ACS.