How to: Use ACS Management Service to Configure AD FS 2.0 as an Enterprise Identity Provider

Microsoft® Windows Azure™ Access Control Service (ACS)
Microsoft Active Directory® Federation Services (AD FS) 2.0

This topic explains how to add the AD FS 2.0 identity provider to a namespace or relying party application. To perform this task, you can use the ACS Management Portal user interface at http://portal.windows.net (http://go.microsoft.com/fwlink/?LinkID=129428) or add the provider programmatically by using the ACS Management Service. The Management Service is particularly useful when you are building a custom user interface for managing ACS and when automating the addition of new tenants for multi-tenant Software as a Service (SaaS) solutions.

Objectives
Overview
Summary of Steps
Step 1 – Collect Configuration Information
Step 2 – Add References to the Required Services and Assemblies
Step 3 – Implement the Management Service Proxy
Step 4 – Add an Identity Provider
Step 5 – Test Your Work

Identify the requirements and configuration information.
List the required steps.
Verify that the configuration is successful.

The ACS Management Service is a web service that exposes ACS features to code. The ACS Management Service can access all ACS features, including the feature subset that is available in the ACS Management Portal user interface.

Adding Microsoft AD FS 2.0 as an identity provider to ACS allows you to reuse the investment made in corporate identity management for cloud-based solutions. To configure AD FS 2.0 as identity provider, you need to write code that follows specific steps. This topic outlines these basic steps.

Step 1 – Collect Configuration Information
Step 2 – Add References to the Required Services and Assemblies
Step 3 – Implement the Management Service Proxy
Step 4 – Add an Identity Provider
Step 5 – Test Your Work

This step explains how to collect the required configuration information. You need to collect the following information:

Management Service identity username. The default value is ManagementClient.
Management Service identity password.
Namespace name.
ACS hostname: accesscontrol.windows.net
Signing certificate string: Get the AD FS signing certificate string from your AD FS 2.0 deployment.

To find the Management Service identity username and password, use the following procedure.

Go to the Windows Azure Management Portal, sign in, and then click Active Directory. 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.)
Click Management Service and then select a management service, such as ManagementClient.
The value of the Name field is the Management Service identity username.
In the Credentials section, click Password. The value in the password field is the Management Service identity password.

After collecting the required information, follow these steps to create a sample console application that will execute the code to add AD FS 2.0 as an identity provider:

Start Visual Studio and create a new console application project.

In the Program class, assign the configuration information values to variables with module scope. The following code sample shows how this might be done.

static string serviceIdentityUsernameForManagement = "ManagementClient";
static string serviceIdentityPasswordForManagement = "ManagementClientPasswordValue";

static string serviceNamespace = "MyNameSpaceNoDots";
static string acsHostName = "accesscontrol.windows.net";

static string signingCertificate = "Very long string representing ADFS signing certificate";

static string cachedSwtToken;
static string identityProviderName = "My Other ADFS Identity Provider";

This step identifies and adds the required dependencies to the services and assemblies.

To add the required dependencies to the services and assemblies

Add a reference to System.Web.Extensions.
Add a service reference to the Management Service. The Management Service URL is unique to your namespace and looks similar to the following:

https://YOURNAMESPACE.accesscontrol.windows.net/v2/mgmt/service

Add the following declarations.

using System.Web; 
using System.Net; 
using System.Data.Services.Client; 
using System.Collections.Specialized; 
using System.Web.Script.Serialization;

This step creates a method that encapsulates the implementation of the Management Service proxy.

To implement the Management Service proxy

Add the following method to the Program class.

public static ManagementService CreateManagementServiceClient()
        {
            string managementServiceHead = "v2/mgmt/service/";
            string managementServiceEndpoint = 
string.Format("https://{0}.{1}/{2}", 
serviceNamespace, 
acsHostName, 
managementServiceHead);
            ManagementService managementService = 
new ManagementService(new Uri(managementServiceEndpoint));

            managementService.SendingRequest += GetTokenWithWritePermission;

            return managementService;
        }

Implement the GetTokenWithWritePermission method and its helper methods. It will add the SWT OAuth token to the Authorization header of the HTTP request.


        public static void GetTokenWithWritePermission(object sender, 
SendingRequestEventArgs args)
        {
            GetTokenWithWritePermission((HttpWebRequest)args.Request);
        }

        public static void GetTokenWithWritePermission(HttpWebRequest args)
        {
            if (cachedSwtToken == null)
            {
                cachedSwtToken = GetTokenFromACS();
            }

            args.Headers.Add(HttpRequestHeader.Authorization, 
 string.Format("OAuth {0}", 
 cachedSwtToken));
        }

        private static string GetTokenFromACS()
        {
            // request a token from ACS
            WebClient client = new WebClient();
            client.BaseAddress = string.Format("https://{0}.{1}", 
      serviceNamespace, 
      acsHostName);

            NameValueCollection values = new NameValueCollection();

            values.Add("grant_type", "password");
            values.Add("client_id", serviceIdentityUsernameForManagement);
            values.Add("username", serviceIdentityUsernameForManagement);
            values.Add("client_secret", serviceIdentityPasswordForManagement);
            values.Add("password", serviceIdentityPasswordForManagement);

            byte[] responseBytes = 
client.UploadValues("/v2/OAuth2-13/rp/AccessControlManagement", 
      "POST", 
      values);

            string response = Encoding.UTF8.GetString(responseBytes);

            // Parse the JSON response and return the access token 
            JavaScriptSerializer serializer = new JavaScriptSerializer();

            Dictionary<string, object> decodedDictionary = 
serializer.DeserializeObject(response) as Dictionary<string, object>;

            return decodedDictionary["access_token"] as string;

        }

This step adds AD FS 2.0 as an identity provider using the Management Service proxy you created earlier.

To add AD FS 2.0 as an identity provider

Initialize the Management Service proxy.

ManagementService svc = CreateManagementServiceClient();

Add your identity provider as the issuer.

Issuer issuer = new Issuer
       {
       Name = identityProviderName
};
       svc.AddToIssuers(issuer);
       svc.SaveChanges(SaveChangesOptions.Batch);

Create an identity provider.

IdentityProvider identityProvider = new IdentityProvider()
{
    DisplayName = identityProviderName,
    Description = identityProviderName,
    WebSSOProtocolType = "WsFederation",
    IssuerId = issuer.Id
};
       svc.AddObject("IdentityProviders", identityProvider);

Create an identity provider signing key based on the certificate you obtained earlier.

IdentityProviderKey identityProviderKey = new IdentityProviderKey()
{
    DisplayName = "SampleIdentityProviderKeyDisplayName",
    Type = "X509Certificate",
    Usage = "Signing",
    Value = Convert.FromBase64String(signingCertificate),
    IdentityProvider = identityProvider,
    StartDate = startDate,
    EndDate = endDate,
};
      svc.AddRelatedObject(identityProvider, 
"IdentityProviderKeys", 
identityProviderKey);

Update the identity provider sign-in address.

IdentityProviderAddress realm = new IdentityProviderAddress()
{
    Address = "http://SampleIdentityProvider.com/sign-in/",
    EndpointType = "SignIn",
    IdentityProvider = identityProvider,
};
svc.AddRelatedObject(identityProvider, "IdentityProviderAddresses", realm);

svc.SaveChanges(SaveChangesOptions.Batch);

Make the identity provider available to relying parties, except the Management Service.

foreach (RelyingParty rp in svc.RelyingParties)
{
    // skip the built-in management RP. 
    if (rp.Name != "AccessControlManagement")
    {
        svc.AddToRelyingPartyIdentityProviders(new RelyingPartyIdentityProvider()
        {
            IdentityProviderId = identityProvider.Id,
            RelyingPartyId = rp.Id
        });
    }
}

svc.SaveChanges(SaveChangesOptions.Batch);

To test your work

Log on to the Access Control Service Management Portal (http://go.microsoft.com/fwlink/?LinkID=129428).
On the Access Control Service page, click the Rule Groups link in the Trust Relationships section.
Click any of the available rules.
On the Edit Rule Group page, click the Add Rule link.
On the Add Claim Rule page, choose the newly added identity provider from the drop-down list in the Claim Issuer section.
Leave the rest of the default values.
Click Save.

You have just created a pass-through rule for the identity provider.

How to: Use ACS Management Service to Configure AD FS 2.0 as an Enterprise Identity Provider

Applies To

Summary

Contents

Objectives

Overview

Summary of Steps

Step 1 – Collect Configuration Information

Step 2 – Add References to the Required Services and Assemblies

To add the required dependencies to the services and assemblies

Step 3 – Implement the Management Service Proxy

To implement the Management Service proxy

Step 4 – Add an Identity Provider

To add AD FS 2.0 as an identity provider

Step 5 – Test Your Work

To test your work