如何：使用 ACS 管理服務配置規則和規則組

2015-11-09

已更新：June 19， 2015

適用對象：Azure

適用於

Microsoft Azure Active Directory 訪問控制（也稱為訪問控制服務或 ACS）

概觀

您可以使用 ACS 管理門戶（有關詳細資訊，請參閱規則組和規則）或 ACS 管理服務配置 ACS 規則和規則組。如果您正在構建用於管理 ACS 的自定義使用者介面，或者想要自動為多租戶軟體即服務（SaaS）解決方案載入新租戶，則使用 ACS 管理服務可能會更有效。

使用 ACS 管理服務配置規則和規則組的步驟

這很重要

在執行以下步驟之前，請確保您的系統滿足 ACS 先決條件中總結的所有 .NET 框架和平臺要求。

要使用 ACS 管理服務設定規則和規則組，請完成以下步驟：

步驟 1 - 收集 ACS 配置資訊
第 2 步 – 建立範例主控台應用程式
步驟 3 – 添加對所需服務和程式集的引用
第 4 步 – 實施管理服務用戶端
第 5 步 – 新增規則組
第 6 步 – 添加規則

步驟 1 - 收集 ACS 配置資訊

您可以使用 ACS 管理門戶收集必要的配置資訊。有關如何啟動 ACS 管理門戶的詳細資訊，請參閱 ACS 管理門戶。

收集 ACS 配置資訊

啟動 ACS 管理門戶。有關如何啟動 ACS 管理門戶的詳細資訊，請參閱 ACS 管理門戶。
獲取 ACS 管理服務帳戶的值。您可以使用預設的 ManagementClient 帳戶。若要查看此值，請在 ACS 管理門戶中，按下頁面左側樹中「管理」部分下的「管理服務」。
獲取 ACS 管理服務帳戶密碼的值。要檢視此值，請執行以下作：
1. 在ACS管理門戶中，按兩下頁面左側樹中管理部分下的管理服務。
2. 在 「管理服務」頁面上，按兩下 「管理服務帳戶」 下的 「ManagementClient」。。
3. 在 Edit Management Service Account （編輯管理服務帳戶 ）頁面的 Credentials （憑據）下，按兩下 Password （密碼）。
4. 在 Edit Management Credential （編輯管理憑證 ）頁面上，複製Password （密碼）字段中的值。
從 Azure 門戶或 ACS 管理門戶的 URL 獲取 Azure 命名空間的名稱。例如，在中 http://contoso.accesscontrol.windows.net，名稱為 contoso。
獲取 ACS 主機名。通常，它是 accesscontrol.windows.net。

第 2 步 – 建立範例主控台應用程式

在此步驟中，您將創建一個範例主控台應用程式，該應用程式可以運行用於添加 ACS 規則組和規則的代碼。

創建範例主控台應用程式

打開 Visual Studio 2012 並在 Windows 安裝範本下創建新的控制台應用程式專案。

將以下代碼添加到 Program 類中，然後將 serviceIdentityPasswordForManagement、serviceNamespace 和 acsHostName 變數分配給您在上一步中收集的相應配置資訊。

public const string serviceIdentityUsernameForManagement = "ManagementClient";
public const string serviceIdentityPasswordForManagement = "My Password/Key for ManagementClient";
public const string serviceNamespace = "MyNameSpaceNoDots";
public const string acsHostName = "accesscontrol.windows.net";
public const string acsManagementServicesRelativeUrl = "v2/mgmt/service/";
static string cachedSwtToken;

步驟 3 – 添加對所需服務和程式集的引用

在此步驟中，您將確定所需的依賴項並將其添加到服務和程式集中。

將所需的依賴項添加到服務和程式集

右鍵按兩下 References，按兩下 Add Reference，然後添加對 System.Web.Extensions 的引用。

備註

您可能必須在 解決方案資源管理器中右鍵按下示例控制台應用程式名稱，選擇 “屬性”，然後將示例應用程式的目標框架從 .NET Framework 4 用戶端配置檔 （在創建新的控制台應用程式時預設分配）更改為 .NET Framework 4。
右鍵按下 Service References，按兩下 Add Service Reference，然後添加對 Management Service 的服務引用。管理服務 URL 對於您的命名空間是唯一的，看起來類似於以下內容：

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

添加以下聲明，其中 MyConsoleApplication 是控制台應用程式的名稱， MyServiceReference 是服務引用的名稱：

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 MyConsoleApplication.MyServiceReference;

第 4 步 – 實施管理服務用戶端

在此步驟中，您將實施Management Service 用戶端。

實現管理服務用戶端

將下列方法加入至 Program 類別：

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

將以下代碼添加到 Program 類中，以創建 GetTokenWithWritePermission 方法及其幫助程式方法。 GetTokenWithWritePermission 及其幫助程式將 SWT OAuth 令牌添加到 HTTP 請求的 Authorization 標頭中。

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;

        }

第 5 步 – 新增規則組

在此步驟中，您將使用在上述步驟中創建的Management Service 用戶端添加規則組。

添加規則組

通過將以下代碼添加到 Program 類中的 Main 方法，初始化管理服務用戶端：
```
ManagementService svc = CreateManagementServiceClient();
```
添加新規則組（您可以將其稱為“mygroup”，如下面的代碼所示）並通過將以下代碼添加到 Program 類中的 Main 方法來保存更改：
```
RuleGroup rg = new RuleGroup();
            rg.Name = "mygroup";
            svc.AddToRuleGroups(rg);
            svc.SaveChanges(SaveChangesOptions.Batch);
```

第 6 步 – 添加規則

在此步驟中，您將使用 ACS 管理服務將規則添加到您在上一步中創建的規則組。

添加規則

通過將以下代碼添加到 Program 類中的 Main 方法，為「LOCAL AUTHORITY」建立變數，該變數是表示 Access Control 命名空間命名空間的內置頒發者名稱：

// "LOCAL AUTHORITY" is a built-in IDP name that represents the Access Control namespace. 
Issuer localAuthority = svc.Issuers.Where(m => m.Name == "LOCAL AUTHORITY").FirstOrDefault();

請執行下列其中一項動作：

若要添加基本規則，請將以下代碼添加到 Program 類中的 Main 方法中：

            //EXAMPLE #1 - BASIC RULE
            Rule basicRule = new Rule()
            {
                InputClaimType = "https://acs/your-input-type",
                InputClaimValue = "inputValue",
                OutputClaimType = "https://acs/your-output-type",
                OutputClaimValue = "outputValue",
            };

            basicRule.Description = string.Format(CultureInfo.InvariantCulture,
                "Transforms claim from {0} with type: {1}, value: {2}, into a new claim with type: {3}, value:{4}",
                "ACS",
                basicRule.InputClaimType,
                basicRule.InputClaimValue,
                basicRule.OutputClaimType,
                basicRule.OutputClaimValue);

            svc.AddToRules(basicRule);
            svc.SetLink(basicRule, "RuleGroup", rg);
            svc.SetLink(basicRule, "Issuer", localAuthority);                                              
              svc.SaveChanges(SaveChangesOptions.Batch);

若要添加將特定輸入聲明和值傳遞給應用程式的規則而不進行更改，請將以下代碼添加到 Program 類中的 Main 方法：

//EXAMPLE #2 - PASS TYPE AND VALUE RULE
            Rule passSpecificClaimRule = new Rule()
            {
                InputClaimType = "https://acs/your-input-type2",
                InputClaimValue = "inputValue2",
            };

            passSpecificClaimRule.Description = string.Format(CultureInfo.InvariantCulture,
                "Passthough claim from {0} with type: {1}, value: {2}",
                "ACS",
                passSpecificClaimRule.InputClaimType,
                passSpecificClaimRule.InputClaimValue);

            svc.AddToRules(passSpecificClaimRule);
            svc.SetLink(passSpecificClaimRule, "RuleGroup", rg);
            svc.SetLink(passSpecificClaimRule, "Issuer", localAuthority); 
svc.SaveChanges(SaveChangesOptions.Batch);

若要添加傳遞具有指定類型的任何聲明的規則，請將以下代碼添加到 Program 類中的 Main 方法中：

//EXAMPLE #3 PASS SPECIFIC TYPE RULE
            Rule passAnyClaimSpecificTypeRule = new Rule()
            {
                InputClaimType = "https://acs/your-input-type3",
            };

            passAnyClaimSpecificTypeRule.Description = string.Format(CultureInfo.InvariantCulture,
                "Pass claim from {0} with type: {1}, and any value",
                "ACS",
                passSpecificClaimRule.InputClaimType);

            svc.AddToRules(passAnyClaimSpecificTypeRule);
            svc.SetLink(passAnyClaimSpecificTypeRule, "RuleGroup", rg);
            svc.SetLink(passAnyClaimSpecificTypeRule, "Issuer", localAuthority); 
svc.SaveChanges(SaveChangesOptions.Batch);

若要添加傳遞具有指定值的任何輸入聲明的規則，請將以下代碼添加到 Program 類中的 Main 方法：

//EXAMPLE #4 PASS ANY CLAIM W/SPECIFIC VALUE RULE
            Rule passAnyClaimSpecificValueRule = new Rule()
            {
                InputClaimValue = "inputValue3",
            };

            passAnyClaimSpecificValueRule.Description = string.Format(CultureInfo.InvariantCulture,
                "Pass claim from {0} with any type, and specific value {1}",
                "ACS",
                passSpecificClaimRule.InputClaimValue);

            svc.AddToRules(passAnyClaimSpecificValueRule);
            svc.SetLink(passAnyClaimSpecificValueRule, "RuleGroup", rg);
            svc.SetLink(passAnyClaimSpecificValueRule, "Issuer", localAuthority); 
svc.SaveChanges(SaveChangesOptions.Batch);

若要添加將指定的輸入聲明類型轉換為其他輸出聲明類型但不更改聲明值的規則，請將以下代碼添加到 Program 類中的 Main 方法：

//EXAMPLE #5 COMPLEX RULE
            Rule complexTransformationRule = new Rule()
            {
                InputClaimType = "https://acs/your-input-type4",
                OutputClaimType = "https://acs/your-output-type2",
            };

            complexTransformationRule.Description = string.Format(CultureInfo.InvariantCulture,
                "Transforms claim from {0} with type: {1}, and any value, into a new claim with type: {2}, keeping(passingthough) old value",
                "ACS",
                complexTransformationRule.InputClaimType,
                complexTransformationRule.OutputClaimType);

            svc.AddToRules(complexTransformationRule);
            svc.SetLink(complexTransformationRule, "RuleGroup", rg);
            svc.SetLink(complexTransformationRule, "Issuer", localAuthority);

            svc.SaveChanges(SaveChangesOptions.Batch);

另請參閱

概念

ACS作方法

共用方式為