Hands-On Lab

Using Certificate based Authentication to Consume a Windows Azure WCF Service from SharePoint

Lab version:1.0.0

Last updated:11/6/2018

Contents

Overview

Exercise 1: Creating and Managing the Certificates

Task 1 – Creating the Certificates

Task 2 – Managing the Certificates

Task 3 – Exporting the Certificates

Exercise 2: Creating the Azure WCF Service

Task 1 – Configuring the WCF Service

Task 2 – Testing the Service

Exercise 3: Create Client Application to consume the WCF Service

Task 1 – Creating the Client Application

Task 2 – Displaying the Web Part

Summary

Overview

The cloud security design ensures that a customer’s data is only accessible by authorized entities. Windows Azure provides confidentiality via several mechanisms, one of which is Identity and Access Management. This Ensures that only properly authenticated entities are allowed access.

Certificates and private keys are uploaded via Service Management API (SMAPI) or the Windows Azure Portal as PKCS12 (PFX) files protected in transit by SSL.PKCS12 is one of the Public-Key Cryptography Standards (PKCS), published by RSA Laboratories, which defines a file format commonly used to store X.509 private keys with accompanying public key certificates, protected with a password-based symmetric key. SMAPI removes the password protection (if necessary) and encrypts the entire PKCS12 blob using SMAPI’s public key and stores it in a secret store on the fabric controller, along with a short certificate name and the public key as metadata. The configuration data associated with any role within the same subscription specifies the certificates that should be made available to the role. When a role is instantiated on a VM, the Fabric controller retrieves the appropriate certificate, decrypts the PKCS12 blob, and re-encrypts it using the Fabric agent's public transport key. For more information on using Certificates with Windows Azure, please read the Windows Azure Security Overview Whitepaper.

Objectives

In this lab, you will:

  • Create a signing certificate and store it in the machine root.
  • Create self-signed client and server certificates and store them in the appropriate certificate stores
  • Create a Windows Azure hosted WCF service that authenticates users based on the certificates
  • Create a SharePoint Web Part application that reads the client's certificate store for a valid certificate to consume the Windows Azure service.

System Requirements

You must have the following items to complete this lab:

  • Windows Azure SDK and Windows Azure Tools for Microsoft Visual Studio (March 2011)
  • KB981002- WCF: Hotfix rollup in .NET 3.5 SP1 for Win 7 and Win 2k8 R2
  • Access to a Windows Azure account.

Setup

The Windows Azure SDK (included in Windows Azure Tools for Visual Studio) installs a simulation environment on your development machine for testing Azure applications locally before deploying them to the cloud. The simulation environment consists of the development fabric to host web and worker roles, and the development storage which simulates cloud blob, table and queue storage locally.

Development storage uses SQL Server as its underlying storage mechanism, and by default the SDK will attempt to configure it to use SQL Server Express. If you do not have SQL Server Express installed before installing the SDK, or you wish to simply use an existing SQL Server instance to host the development storage database, you must run the dsinit command to select the SQL Server instance where the database will be created.

Using dsinit to Configure Development Storage
  1. Open a command prompt.
  2. Edit the following command line as appropriate for your environment, where [AzureSDKInstallDrive] is the drive where you installed the Azure SDK (or Windows Azure Tools for Visual Studio), and [YourSqlInstance] is the SqlServer where you want to create the development storage database.
    [AzureSDKInstallDrive]\ Program Files\Windows Azure SDK\v1.4\bin\devstore\dsinit.exe /sqlinstance:[YourSqlInstance].

Example Command Line:
“C:\Program Files\Windows Azure SDK\v1.4\bin\devstore\dsinit.exe” /sqlinstance:.

  1. Note that the sample command line above uses the value “.” for the sqlinstance argument, which specifies that the local default SQL instance will be used for development storage.

Estimated time to complete this lab: 60minutes.

Exercise 1: Creating and Managing the Certificates

Task 1 – Creating the Certificates

A self-signed certificate is an identity certificate that is signed by its own creator. That is, the person that created the certificate also signed off on its legitimacy. In this exercise, you will create 3 certificates - The signing certificate, the client certificate and the server certificate.

  1. Log into your Windows Azure Portal at
  2. Click New Hosted Service

Figure 1

Windows Azure Ribbon menu

  1. Create a new hosted service as follows:

Note: Use a unique name and URL prefix for your service, and ensure that the Do not deploy is selected as the deployment option. By selecting this option, you are just blocking the name and the URL of your service. This URL is needed to create the service certificate

Figure 2

Create a New Hosted Service

  1. Click OK.
  2. Wait for a few minutes till the new hosted service is created and ready.
  3. Open the Visual studio 2010 command prompt

Figure 3

Windows Start menu

  1. Create the signing certificate and store it in the machine root by running the following command:
    makecert -r -pe -a sha1 -n "CN=azurehol2011_ca" -ss Root -srLocalMachine -len 2048 -sp "Microsoft Enhanced RSA and AES Cryptographic Provider" -sy 24 azurehol2011_ca.cer

Note: The azurehol2011_ca.cer is the file name of the certificate file and the azurehol2011_ca is the certificate common name (CN).

  1. Create a client certificate and store it in the personal certificate store by running the following command:

makecert -pe -n "CN=Azure HOL Client Certificate, O=My Company Name" -ss my -srCurrentUser -a sha1 -sky exchange -eku 1.3.6.1.5.5.7.3.2 -in "azurehol2011_ca" -is Root -irLocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12

Note: The azurehol2011_ca in the above command should match the common name (CN) from the step 7

Figure 4

Visual Studio Command Prompt

  1. Replace the [Your Hosted Service] in the below command with the URL prefix of the Azure service (Ex :azureholusingcerts). Create a server certificate and store it in the machine personal store by running the following command:

makecert -pe -n "CN=[Your Hosted Service].cloudapp.net" -ss my -srLocalMachine -a sha1 -sky exchange -eku 1.3.6.1.5.5.7.3.1 -in "azurehol2011_ca" -is Root -irLocalMachine -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 azurehol2011_server.cer

Note: The azurehol2011_ca in the above command should match the common name (CN) from the step 7.

Figure 5

Azure Command

Task 2 – Managing the Certificates

  1. Click Windows Start, and type MMC and click the mmc.exe.

Figure 6

Windows Start menu

  1. On the File menu, click Add/Remove Snap-in
  2. Select Certificates and click the Add button.

-

Figure 7

Add or Remove Snap-ins Dialog

  1. Select My user account and then click Finish.
  2. In the Add or Remove Snap-ins dialog box, select Certificates again and click the Add button again.
  3. Select Computer Account and then click Next.
  4. Click Finish.
  5. Click OK.
  6. Expand Certificates (Local Computer) and then expand Trusted Root Certification Authority. Double-click Certificates.
  7. Locate the signing certificate (ex: azurehol2011_ca). Right-click the certificate name and then click Copy.

Figure 8

Certificates explorer

  1. Under Certificates (Local Computer), expand Personal. Right-click Certificates and then click Paste.

Figure 9

Certificates context menu

  1. Now the Local Computer Personal store should look as follows:

Figure 10

Certificates explorer

Task 3 – Exporting the Certificates

  1. Right-click the signing certificate (Ex: azurehol2011_ca), click All Tasks, and then click Export.

Figure 11

Certificates explorer

  1. Click Next.
  2. Select Yes, export the private key option and then click Next.
  3. Leave the defaults (Personal Information Exchange selection), and then click Next

Figure 12

Certificate Export Wizard

  1. Type and Confirm the password for this certificate (Ex: pass@word1). Click Next.
  2. Browse to a location on your development machine and save this certificate. Use the same name (ex: azurehol2011_ca.pfx) and save the certificate

Figure 13

Certificate Export Wizard

  1. Click Finish.
  2. Repeat the steps to save the Server certificate located at Certificates (local computer) > Personal > Certificates > [your hosted service].cloudapp.net to your development machine as azurehol2011_server.pfx. This certificate along with the signing certificate will be uploaded to the Azure hosted service instance
  3. Similarly, Repeat the steps to save the Client certificate located at Certificates - Current Users > Personal > Certificates > Azure HOL Client Certificate to your development machine as azurehol2011_client.pfx. This certificate should be distributed to the clients seeking to consume the Azure hosted WCF service.
  4. When this is done, you should have 3 certificates as follows:

Figure 14

Certificate Explorer

  1. Log into your Windows Azure Portal (
  2. Expand the name of the hosted service that you created in exercise 1 , and then click Certificates.
  3. Click Add Certificate.

Figure 15

Windows Azure Platform

  1. Click the Browse button, and locate the Server Certificate (azurehol2011_server.pfx) and upload it. Type the certificate password and click Create.

Figure 16

File Browser

  1. Similarly, upload the Signing Authority certificate (azurehol2011_ca.pfx).

Figure 17

Certificates Explorer

The certificates needed for the WCF service is now ready.

Exercise 2: Creating the Azure WCF Service

Task 1 – Configuring the WCF Service

In this task, you will create the WCF service and host it on Azure.

  1. Browse to theBeforefolder of the Lab.
  2. Open the solution SPToWinAzureUsingCerts.sln
  3. Right-click the SalaryServiceWebRole under Roles, and click Properties. Then, click the Certificates tab on the left

Figure 18

Web Roles

  1. Click Add Certificate.
  2. Type ServerCertificate as the name of the Certificate. Leave the default Store Location to LocalMachine and Store Name to My.
  3. Click the Thumbprint button to bring up the Certificate list. Select the Server Certificate and click OK.

Figure 19

Windows Security – Certificate List

  1. Similarly add another certificate CA (for certificate authority), and choose the signing authority certificate (Ex: azurehol2011_ca)

Figure 20

Windows Security – Certificate List

  1. The Certificate section should now look as follows:

Figure 21

Certificate Section

  1. Click Endpoints on the left tab
  2. Set the following attributes for the EndPoint.

Type: Input

Protocol: https

Public Port: 443

SSL Certificate Name: ServerCertificate

Figure 22

EndPoint fields

  1. Save the project.
  2. Open the Startup.cmd file.
  3. Replace the [THUMBPRINT] with the thumbprint of your signing authority certificate

Figure 23

Sartup.cmd file

Since the signing certificate is self-signed, it must be installed in Root of the Azure Hosted Service. The configuration options do not support this (as a security measure) so this must be done using a Startup task. Also required in the Startup task is the unlocking of the SSL configuration section of Web.config. This step specifies a Startup task with elevated privileges running Startup.cmd

  1. After the changes, the Startup.cmd will look as follows:

Figure 24

Startup.cmd file

  1. Open the Servicedefinition.csdef file, and add the following XML element to the TODO: 5.8.1 section.

XML

Startup

<TaskcommandLine="Startup.cmd"executionContext="elevated"taskType="simple"

</Task

</Startup>

  1. Save, Publish and Deploy (Production Deployment) the solution to the hosted service that you created earlier in Exercise 1 (Ex: AzureHolUsingCerts.CloudApp.net)
  2. The hosted service should now look as follows:

Figure 25

Hosted Service

Task 2 – Testing the Service

  1. On the development machine, open a new instance of the internet explorer browser and navigate to your service URL. Note: You must https
    (Ex: https://azureholusingcerts.cloudapp.net/salaryservice.svc)
  2. Since your development machine has the client certificate installed in the Personal certificate store, the browser would prompt you to confirm the certificate
    (Note: Since self-signed certificate is used, you see this Window Security message. When a certificate issues by an authority is used, you will not see this message)

Figure 26

Windows Security Pop-up

  1. Select the Client Certificate and click OK.
  2. You should be able to see the service details

Figure 27

Service details

  1. Now, try to access the same service from a differentmachine, where the certificate is not installed. You will notice that the browser shows a server error, and the access to the service is denied

Figure 28

Acces is denied error

To enable access to this service from the machines that does not have access to service, distribute the client certificate and install it on the end-user machine. All end-user machines requiring access to the service should have the client certificate installed in their personal certificate store.

  1. To test the AdjustSalary method from the machine that has the client certificate, open the browser window and navigate to:
    [Your URL Prefix].cloudapp.net/salaryservice.svc/adjustedsalary?a=1000&b=7
    Note: Replace the [Your URL Prefix] with the URL prefix of your hosted service
    Example:
  1. Save/download the resulting file (Json output) as adjustedSalary.txt to your local machine. Open the text file. The text file contains the result of the calculation

Exercise 3: Create Client Application to consume the WCF Service

Task 1 – Creating the Client Application

  1. Open the SalaryDisplayPage.htm in the SalaryDisplayWeb project.
  2. Under the section //TODO: 5.8.2, replace the [Your URL Prefix] with the URL prefix of your Azure hosted WCF Service.
    Ex:

Figure 29

SalaryDisplayPage.htm

  1. Copy the Full Path of the SalaryDisplayPage.htm to your clipboard

Figure 30

SalaryDisplayPage.htm properties

  1. Open a new instance of Internet Explorer. Copy the Full Path and browse the html page.
  2. Note, the URL should point a local file

Figure 31

Internet Explorer

  1. Click the Internet Explorer Security bar, and click Allow Blocked Content.

Figure 32

Internet Explorer security bar

  1. Enter a Starting Salary and Inflation and click the Get Adjusted Salary button. You will see a Windows security alert asking you to confirm the client certificate. Click the client certificate and click OK.

Figure 33

Windows Security Alert

This Windows Security dialog is displayed when using self-signed certificate. However using a certificate signed by a certificate authority will eliminate this problem; in the meantime, you can ignore the error.

For more details refer to:

  1. The result of the calculation (inflation adjusted salary) is now displayed.

Task 2 – Displaying the Web Part

  1. The html code snippet can be inserted into a SharePoint HTML Web Part (As explained in JQuery Labs - Labs 5 and 6). However, you will run into an access denied error message. This is due to the use of a self-signed certificate. The self-signed certificate that was used in the lab is used for authentication in the development environment only. However using a certificate signed by a certificate authority will eliminate this problem.
    For more details refer to:

Summary

The cloud security design ensures that a customer’s data is only accessible by authorized entities. Windows Azure provides confidentiality via several mechanisms one of which is Identity and Access Management using private key and certificates.

In this lab, you learned to create a signing certificate and store it in the machine root. You also created a self-signed client and server certificates and stored them in the appropriate certificate stores. You also learned how to create SharePoint Web Parts to consume a Windows hosted WCF service over https.