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

  • Article

Updated: June 19, 2015

Applies To: Azure

Applies To

  • Microsoft® Azure™ Access Control Service (ACS)

  • Microsoft Active Directory® Federation Services (AD FS) 2.0

Summary

This topic explains how to add the identity provider to a namespace or relying party application. To perform this task, you can 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.

Contents

  • 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

Objectives

  • Identify the requirements and configuration information.

  • List the required steps.

  • Verify that the configuration is successful.

Overview

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 as an identity provider to ACS allows you to reuse the investment made in corporate identity management for cloud-based solutions. To configure as identity provider, you need to write code that follows specific steps. This topic outlines these basic steps.

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

Step 1 – Collect Configuration Information

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 deployment.

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

  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) 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.)

  2. Click Management Service and then select a management service, such as ManagementClient.

  3. The value of the Name field is the Management Service identity username.

  4. 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 as an identity provider:

  1. Start Visual Studio and create a new console application project.

  2. 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";

Step 2 – Add References to the Required Services and Assemblies

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

To add the required dependencies to the services and assemblies

  1. Add a reference to System.Web.Extensions.

  2. 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

  3. Add the following declarations.

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

Step 3 – Implement the Management Service Proxy

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

To implement the Management Service proxy

  1. 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;
        }

  2. 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;

        }

Step 4 – Add an Identity Provider

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

To add AD FS 2.0 as an identity provider

  1. Initialize the Management Service proxy.

    ManagementService svc = CreateManagementServiceClient();

  2. Add your identity provider as the issuer.

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

  3. Create an identity provider.

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

  4. 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);

  5. 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);

  6. 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);

Step 5 – Test Your Work

To test your work

  2. On the Access Control Service page, click the Rule Groups link in the Trust Relationships section.

  3. Click any of the available rules.

  4. On the Edit Rule Group page, click the Add Rule link.

  5. On the Add Claim Rule page, choose the newly added identity provider from the drop-down list in the Claim Issuer section.

  6. Leave the rest of the default values.

  7. Click Save.

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