How to: Use ACS Management Service to Configure an OpenID Identity Provider

  • Article

Updated: June 19, 2015

Applies To: Azure

Applies To

  • Microsoft® Azure™ Access Control Service (ACS)

  • OpenID 2.0

Summary

This topic outlines the basic steps required for adding identity providers that support the OpenID protocol. OpenID identity providers can be added to ACS using the Management Service. OpenID identity providers cannot be added using the ACS Management Portal. In this topic we refer to the OpenID 2.0 specification because this is the specification version that ACS supports.

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 Client

  • Step 4 – Add an Identity Provider

Objectives

  • Identify the required prerequisites and configuration information.

  • List the steps required to add an OpenID identity provider.

Overview

The Management Service is a web service that is one of the key components of ACS. The Management Service exposes functionality that is available by means of the Management Portal user interface. Anything that can be accomplished in the Management Portal can also be done using the Management Service. Adding OpenID identity providers ACS allows you to save on developing and maintaining the identity management mechanism of Internet scale. To accomplish the task of adding an OpenID identity provider, 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 Client

  • Step 4 – Add an Identity Provider

Step 1 – Collect Configuration Information

This step identifies and shows how to collect the required configuration information. You need to collect the following information:

  • Management Service identity username—ManagementClient.

  • Management Service identity password—To obtain the service identity password for the management service:

    1. Log on to the Access Control Service Management Portal.

    2. In the Administration section, click the Management Service link.

    3. On the Management Service page, click the ManagementClient link (ManagementClient is the actual username for the service).

    4. In the Credentials section, click either the Symmetric Key or the Password link. The value in each is the same. This is the password.

  • Your service’s namespace

  • ACS hostname—Usually accesscontrol.windows.net.

After collecting the required information, follow these steps to create a sample console application that will run the code for adding OpenID identity provider:

  1. Open Visual Studio® 2010 and create a new console application project.

  2. In the Program class, assign the information collected earlier to the module scope variables, using code similar to the following.

        static string serviceIdentityUsernameForManagement = "ManagementClient";
        static string serviceIdentityPasswordForManagement = "...update to your password...";

        static string serviceNamespace = "...update to your namespace...";
        static string acsHostName = "accesscontrol.windows.net";
        static string acsManagementServicesRelativeUrl = "v2/mgmt/service/";

        static string identityProviderName = "My Open ID Identity Provider";

        static string cachedSwtToken;

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;
using System.Globalization;
using System.Runtime.Serialization.Json;
using ConsoleApplication1.ServiceReference1;

Notice the last declaration, ConsoleApplication1.ServiceReference1. It may vary in your case if you changed default values when you created your console application or when you added the reference to the management service.

Step 3 – Implement the Management Service Client

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

To implement the Management Service client

  1. Add the following method to the Program class.

    public static ManagementService CreateManagementServiceClient()
        {
            string managementServiceEndpoint = String.Format(CultureInfo.InvariantCulture, "https://{0}.{1}/{2}",
                serviceNamespace,
                acsHostName,
                acsManagementServicesRelativeUrl);
            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, "Bearer " + cachedSwtToken);
        }

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

            NameValueCollection values = new NameValueCollection();
            values.Add("grant_type", "client_credentials");
            values.Add("client_id", serviceIdentityUsernameForManagement);
            values.Add("client_secret", serviceIdentityPasswordForManagement);
            values.Add("scope", client.BaseAddress + acsManagementServicesRelativeUrl);

            byte[] responseBytes = client.UploadValues("/v2/OAuth2-13", "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 an OpenID identity provider using the Management Service client you created earlier.

To add an OpenID identity provider

  1. Inside the Main method, initialize the Management Service client.

    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.

                var openId = new IdentityProvider
            {
                DisplayName = identityProviderName,
                Description = identityProviderName,
                WebSSOProtocolType = "OpenId",
                IssuerId = issuer.Id
            };

            svc.AddObject("IdentityProviders", openId);

  4. Update the identity provider sign-in address. In this exercise you will use www.myopenid.com as the sign-in address. Other OpenID identity providers include Google and Yahoo!, and they have their own sign-in addresses. They are https://www.google.com/accounts/o8/ud and https://open.login.yahooapis.com/openid/op/auth, respectively.

                var openIdAddress = new IdentityProviderAddress
            {
                Address = "https://www.myopenid.com/server",
                EndpointType = "SignIn"
            };

            svc.AddRelatedObject(openId, "IdentityProviderAddresses", openIdAddress);
            svc.SaveChanges();

  5. 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 = openId.Id,
                        RelyingPartyId = rp.Id
                    });
                }
            }

            svc.SaveChanges(SaveChangesOptions.Batch);