合作夥伴中心驗證

發行項
03/12/2024

適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府Microsoft雲端合作夥伴中心

合作夥伴中心使用 Microsoft Entra ID 進行驗證。與合作夥伴中心 API、SDK 或 PowerShell 模組互動時，您必須正確地設定 Microsoft Entra 應用程式，然後要求存取權杖。使用「僅限應用程式」或「應用程式 + 使用者」驗證取得的存取權杖可與合作夥伴中心搭配使用。不過，有兩個需要考量的重要項目

使用應用程式 + 使用者驗證存取合作夥伴中心 API 時，請使用多重要素驗證。如需有關此變更的詳細資訊，請參閱啟用安全應用程式模型。
合作夥伴中心 API 並非在所有作業上都支援「僅限應用程式」驗證。在某些情況下，您必須使用「應用程式 + 使用者」驗證。 在每篇文章的先決條件標題底下，您會發現檔指出是否只支援應用程式驗證、應用程式 + 使用者驗證或兩者。

重要

自 2023 年 6 月 30 日起，Azure Active Directory （Azure AD） Graph 已淘汰。接下來，我們不會對 Azure AD Graph 進行進一步的投資。 Azure AD Graph API 除了安全性相關修正之外，沒有 SLA 或維護承諾。我們只會對 Microsoft Graph 投資發展新的功能。

我們會以累加步驟淘汰 Azure AD Graph，讓您有足夠的時間將應用程式移轉至 Microsoft Graph API。在稍後宣佈的日期，我們將封鎖使用 Azure AD Graph 建立任何新的應用程式。

若要深入瞭解，請參閱重要事項：Azure AD Graph 淘汰和 Powershell 模組淘汰。

初始設定

若要開始，您必須確定您有主要合作夥伴中心帳戶及整合沙箱合作夥伴中心帳戶。如需詳細資訊，請參閱設定合作夥伴中心帳戶以存取 API。請記下主要帳戶和整合沙盒帳戶Microsoft Entra 應用程式註冊標識碼和秘密（僅限應用程式識別需要客戶端密碼）。
從 Azure 入口網站登入 Microsoft Entra ID。在 [其他應用程式的權限] 中，將 [Windows Azure Active Directory] 的權限設定為 [委派的權限]，然後選取 [以登入的使用者身分存取目錄] 和 [登入並讀取使用者設定檔]。
在 Azure 入口網站中，新增應用程式。搜尋「Microsoft合作夥伴中心」，這是Microsoft合作夥伴中心應用程式。將 [委派的權限] 設定為 [存取合作夥伴中心 API]。如果您使用美國政府Microsoft雲端合作夥伴中心，則此步驟是強制性的。如果您使用合作夥伴中心全域實例，此步驟是選擇性的。 CSP 合作夥伴可以使用合作夥伴中心的應用程式管理功能，略過合作夥伴中心全域實例的此步驟。

僅限應用程式驗證

如果您想要使用僅限應用程式驗證來存取合作夥伴中心 REST API、.NET API、Java API 或 PowerShell 模組，您可以使用下列指示來執行此動作。

.NET (僅限應用程式驗證)

public static IAggregatePartner GetPartnerCenterTokenUsingAppCredentials()
{
    IPartnerCredentials partnerCredentials =
        PartnerCredentials.Instance.GenerateByApplicationCredentials(
            PartnerApplicationConfiguration.ApplicationId,
            PartnerApplicationConfiguration.ApplicationSecret,
            PartnerApplicationConfiguration.ApplicationDomain);

    // Create operations instance with partnerCredentials.
    return PartnerService.Instance.CreatePartnerOperations(partnerCredentials);
}

Java (僅限應用程式驗證)

合作夥伴中心 Java SDK 可用來管理合作夥伴中心資源。這是合作夥伴社群維護的開放原始碼專案，Microsoft未正式支援。如果您遇到問題，可以從社群取得協助或在 GitHub 上提出問題。

public IAggregatePartner getAppPartnerOperations()
{
    IPartnerCredentials appCredentials =
        PartnerCredentials.getInstance().generateByApplicationCredentials(
        PartnerApplicationConfiguration.getApplicationId(),
        PartnerApplicationConfiguration.getApplicationSecret(),
        PartnerApplicationConfiguration.getApplicationDomain());

    return PartnerService.getInstance().createPartnerOperations( appCredentials );
}

REST (僅限應用程式驗證)

REST 要求

POST https://login.microsoftonline.com/{tenantId}/oauth2/token HTTP/1.1
Accept: application/json
return-client-request-id: true
Content-Type: application/x-www-form-urlencoded; charset=utf-8
Host: login.microsoftonline.com
Content-Length: 194
Expect: 100-continue

resource=https%3A%2F%2Fgraph.windows.net&client_id={client-id-here}&client_secret={client-secret-here}&grant_type=client_credentials

REST 回應

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store
Pragma: no-cache
Content-Type: application/json; charset=utf-8
Expires: -1
Content-Length: 1406

{"token_type":"Bearer","expires_in":"3600","ext_expires_in":"3600","expires_on":"1546469802","not_before":"1546465902","resource":"https://graph.windows.net","access_token":"value-has-been-removed"}

應用程式 + 使用者驗證

安全應用程式模型現在可用來為合作夥伴中心 API 存取提供安全、可調整和未來的驗證。此方法會透過 Azure AD 使用僅限應用程式與 app+使用者存取令牌等新式驗證機制來改善安全性。如需詳細資訊，請參閱啟用安全應用程式模型。

合作夥伴同意程式是互動式程式，合作夥伴會使用多重要素驗證、同意應用程式，以及重新整理令牌儲存在安全存放庫中，例如 Azure 金鑰保存庫。我們建議您針對此程序使用可用於整合的專用帳戶。

重要

應該為合作夥伴同意程式中所使用的服務帳戶啟用適當的多重要素驗證解決方案。如果不這麼做，則產生的重新整理權杖將不符合安全性需求。

「應用程式 + 使用者」驗證的範例

合作夥伴同意程式可以透過許多方式執行。為了協助合作夥伴瞭解如何執行每個必要作業，我們已開發下列範例。當您在環境中實作適當的解決方案時，請務必開發符合程式代碼撰寫標準和安全策略的解決方案。

.NET (應用程式 + 使用者驗證)

合作夥伴同意範例專案會示範如何利用以 ASP.NET 開發的網站來擷取同意、要求重新整理權杖，並將其安全地儲存在 Azure Key Vault 中。請執行下列步驟來建立此範例所需的必要條件。

使用 Azure 入口網站或下列 PowerShell 命令，建立 Azure Key Vault 的執行個體。在執行命令之前，請務必據以修改參數值。存放庫名稱必須是唯一的。
```
Login-AzureRmAccount

# Create a new resource group
New-AzureRmResourceGroup -Name ContosoResourceGroup -Location EastUS

New-AzureRmKeyVault -Name 'Contoso-Vault' -ResourceGroupName 'ContosoResourceGroup' -Location 'East US'
```
如需建立 Azure 金鑰保存庫的詳細資訊，請參閱快速入門：使用 Azure 入口網站或快速入門從 Azure 金鑰保存庫設定和擷取秘密：使用 PowerShell 從 Azure 金鑰保存庫設定和擷取秘密。然後設定及擷取秘密。

使用 Azure 入口網站或下列命令建立Microsoft Entra Application 和索引鍵。

Connect-MgGraph -Scopes "Application.ReadWrite.OwnedBy"

$Context = Get-MgContext

$app = New-MgApplication -DisplayName 'My Vault Access App' -Web @{ RedirectUris = 'https://$($Context.TenantId)/$((New-Guid).ToString())' }
$password = Add-MgApplicationPassword -ApplicationId $app.AppId

Write-Host "ApplicationId       = $($app.AppId)"
Write-Host "ApplicationSecret   = $($password.SecretText)"

請務必記下 [應用程式識別碼] 和 [密碼] 值，因為這些值將用於下列步驟。

使用 Azure 入口網站或下列命令，將新建立Microsoft Entra 應用程式授與讀取秘密許可權。

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "User.Read"

# Get the application
$app = Get-MgApplication -Filter "appId eq 'ENTER-APP-ID-HERE'"

# Set the Key Vault access policy
Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -ObjectId $app.Id -PermissionsToSecrets get

建立已針對合作夥伴中心設定的 Microsoft Entra 應用程式。執行下列動作來完成此步驟。
- 瀏覽至合作夥伴中心的應用程式管理功能
- 選取 [新增 Web 應用程式 ] 以建立新的 Microsoft Entra 應用程式。
請務必記錄 應用程式標識碼、 帳戶標識元*和金鑰值，因為它們將用於下列步驟。
使用 Visual Studio 或下列命令，複製 Partner-Center-DotNet-Samples 存放庫。
```
git clone https://github.com/Microsoft/Partner-Center-DotNet-Samples.git
```
開啟在 Partner-Center-DotNet-Samples\secure-app-model\keyvault 目錄中找到的 PartnerConsent 專案。

填入在 web.config 中找到的應用程式設定

<!-- AppID that represents CSP application -->
<add key="ida:CSPApplicationId" value="" />
<!--
    Please use certificate as your client secret and deploy the certificate to your environment.
    The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CSPApplicationSecret" value="" />

<!--
    Endpoint address for the instance of Azure KeyVault. This is
    the DNS Name for the instance of Key Vault that you provisioned.
 -->
<add key="KeyVaultEndpoint" value="" />

<!-- App ID that is given access for KeyVault to store refresh tokens -->
<add key="ida:KeyVaultClientId" value="" />

<!--
    Please use certificate as your client secret and deploy the certificate
    to your environment. The following application secret is for sample
    application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="" />

重要

敏感性資訊 (例如應用程式祕密) 不應儲存在設定檔中。由於這是範例應用程式，所以已設定完成。在您的生產應用程式中，我們強烈建議您使用憑證式驗證。如需詳細資訊，請參閱適用於應用程式驗證的憑證認證。

當您執行此範例專案時，會提示您進行驗證。成功驗證之後，會從 Microsoft Entra ID 要求存取令牌。從 Microsoft Entra ID 傳回的資訊包含儲存在 Azure 金鑰保存庫設定實例中的重新整理令牌。

Java (應用程式 + 使用者驗證)

合作夥伴同意範例專案會示範如何利用以 JSP 開發的網站來擷取同意、要求重新整理權杖及安全地儲存在 Azure Key Vault 中。請執行下列步驟來建立此範例所需的必要條件。

使用 Azure 入口網站或下列 PowerShell 命令，建立 Azure Key Vault 的執行個體。在執行命令之前，請務必據以修改參數值。存放庫名稱必須是唯一的。
```
Login-AzureRmAccount

# Create a new resource group
New-AzureRmResourceGroup -Name ContosoResourceGroup -Location EastUS

New-AzureRmKeyVault -Name 'Contoso-Vault' -ResourceGroupName 'ContosoResourceGroup' -Location 'East US'
```
如需建立 Azure 金鑰保存庫的詳細資訊，請參閱快速入門：使用 Azure 入口網站或快速入門從 Azure 金鑰保存庫設定和擷取秘密：使用 PowerShell 從 Azure 金鑰保存庫設定和擷取秘密。

使用 Azure 入口網站或下列命令建立Microsoft Entra Application 和密鑰。

Connect-MgGraph -Scopes "Application.ReadWrite.OwnedBy"

$Context = Get-MgContext

$app = New-MgApplication -DisplayName 'My Vault Access App' -IdentifierUri 'https://$($Context.TenantDomain)/$((New-Guid).ToString())'
$password = Add-MgApplicationPassword -ApplicationId $app.AppId

Write-Host "ApplicationId       = $($app.AppId)"
Write-Host "ApplicationSecret   = $($password.SecretText)"

請務必記下 [應用程式識別碼] 和 [密碼] 值，因為這些值將用於下列步驟。

使用 Azure 入口網站或下列命令，將新建立的 Microsoft Entra 應用程式授與讀取秘密許可權。

Connect-MgGraph -Scopes "User.Read"
$app = Get-MgApplication -Filter "appId eq 'ENTER-APP-ID-HERE'"

Set-AzKeyVaultAccessPolicy -VaultName ContosoVault -ObjectId $app.Id -PermissionsToSecrets get

建立已針對合作夥伴中心設定的 Microsoft Entra 應用程式。執行下列動作來完成此步驟。
- 瀏覽至合作夥伴中心的應用程式管理功能
- 選取 [新增 Web 應用程式 ] 以建立新的 Microsoft Entra 應用程式。
請務必記錄 應用程式標識碼、 帳戶標識元*和金鑰值，因為它們將用於下列步驟。

使用下列命令，複製 Partner-Center-Java-Samples 存放庫

git clone https://github.com/Microsoft/Partner-Center-Java-Samples.git

開啟在 Partner-Center-Java-Samples\secure-app-model\keyvault 目錄中找到的 PartnerConsent 專案。

填入在 web.xml 檔案中找到的應用程式設定

<filter>
    <filter-name>AuthenticationFilter</filter-name>
    <filter-class>com.microsoft.store.samples.partnerconsent.security.AuthenticationFilter</filter-class>
    <init-param>
        <param-name>client_id</param-name>
        <param-value></param-value>
    </init-param>
    <init-param>
        <param-name>client_secret</param-name>
        <param-value></param-value>
    </init-param>
    <init-param>
        <param-name>keyvault_base_url</param-name>
        <param-value></param-value>
    </init-param>
    <init-param>
        <param-name>keyvault_client_id</param-name>
        <param-value></param-value>
    </init-param>
    <init-param>
        <param-name>keyvault_client_secret</param-name>
        <param-value></param-value>
    </init-param>
    <init-param>
        <param-name>keyvault_certifcate_path</param-name>
        <param-value></param-value>
    </init-param>
</filter>

重要

敏感性資訊 (例如應用程式祕密) 不應儲存在設定檔中。由於這是範例應用程式，所以已設定完成。在您的生產應用程式中，我們強烈建議您使用憑證式驗證。如需詳細資訊，請參閱 Key Vault 憑證驗證。

當您執行此範例專案時，會提示您進行驗證。成功驗證之後，會從 Microsoft Entra ID 要求存取令牌。從 Microsoft Entra ID 傳回的資訊包含儲存在 Azure 金鑰保存庫設定實例中的重新整理令牌。

雲端解決方案提供者驗證

雲端解決方案提供者合作夥伴可以使用透過合作夥伴同意程序取得的重新整理權杖。

雲端解決方案提供者驗證的範例

為了協助合作夥伴瞭解如何執行每個必要作業，我們已開發下列範例。當您在環境中實作適當的解決方案時，請務必開發符合程式代碼撰寫標準和安全策略的解決方案。

.NET (CSP 驗證)

如果您尚未這麼做，請執行合作夥伴同意程式。
使用 Visual Studio 或下列命令，複製 Partner-Center-DotNet-Samples 存放庫
```
git clone https://github.com/Microsoft/Partner-Center-DotNet-Samples.git
```
開啟在 Partner-Center-DotNet-Samples\secure-app-model\keyvault 目錄中找到的 CSPApplication 專案。

更新在 App.config 檔案中找到的應用程式設定。

<!-- AppID that represents CSP application -->
<add key="ida:CSPApplicationId" value="" />
<!--
    Please use certificate as your client secret and deploy the certificate to your environment.
    The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CSPApplicationSecret" value="" />

<!-- Endpoint address for the instance of Azure KeyVault -->
<add key="KeyVaultEndpoint" value="" />

<!-- AppID that is given access for keyvault to store the refresh tokens -->
<add key="ida:KeyVaultClientId" value="" />

<!--
    Please use certificate as your client secret and deploy the certificate to your environment.
    The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="" />

針對在 Program.cs 檔案中找到的 PartnerId 和 CustomerId 變數設定適當的值。

// The following properties indicate which partner and customer context the calls are going to be made.
string PartnerId = "<Partner tenant id>";
string CustomerId = "<Customer tenant id>";

當您執行此範例專案時，此專案會取得您在合作夥伴同意程序期間取得的重新整理權杖。然後要求存取權杖代表合作夥伴與合作夥伴中心 SDK 互動。並在最後要求存取權仗代表指定客戶與 Microsoft Graph 互動。

Java (CSP 驗證)

如果您尚未這麼做，請執行合作夥伴同意程式。
使用 Visual Studio 或下列命令，複製 Partner-Center-Java-Samples 存放庫
```
git clone https://github.com/Microsoft/Partner-Center-Java-Samples.git
```
開啟在 Partner-Center-Java-Samples\secure-app-model\keyvault 目錄中找到的 cspsample 專案。

更新在 application.properties 檔案中找到的應用程式設定。

azuread.authority=https://login.microsoftonline.com
keyvault.baseurl=
keyvault.clientId=
keyvault.clientSecret=
partnercenter.accountId=
partnercenter.clientId=
partnercenter.clientSecret=

當您執行此範例專案時，此專案會取得您在合作夥伴同意程序期間取得的重新整理權杖。然後要求存取權杖代表合作夥伴與合作夥伴中心 SDK 互動。
選擇性 - 如果您要查看如何代表客戶與 Azure Resource Manager 和 Microsoft Graph 互動，請取消 RunAzureTask 和 RunGraphTask 函式呼叫的註解。

控制台提供者驗證

控制台廠商必須讓每個支援的合作夥伴執行合作夥伴同意程序。完成後，透過該程序取得的重新整理權杖就會用來存取合作夥伴中心 REST API 和 .NET API。

注意

控制面板廠商至少應擁有 客戶租使用者中的雲端應用程式管理員 角色。

雲端控制台提供者驗證的範例

為了協助控制面板廠商瞭解如何執行每個必要作業，我們已開發下列範例。當您在環境中實作適當的解決方案時，請務必開發符合程式代碼撰寫標準和安全策略的解決方案。

.NET (CPV 驗證)

為雲端解決方案提供者合作夥伴開發及部署流程，以提供適當的同意。如需詳細資訊和範例，請參閱合作夥伴同意。

重要

您不應儲存來自雲端解決方案提供者合作夥伴的使用者認證。應儲存透過合作夥伴同意程序取得的重新整理權杖，並用來要求存取權杖，以便與任何 Microsoft API 互動。
使用 Visual Studio 或下列命令，複製 Partner-Center-DotNet-Samples 存放庫
```
git clone https://github.com/Microsoft/Partner-Center-DotNet-Samples.git
```
開啟在 Partner-Center-DotNet-Samples\secure-app-model\keyvault 目錄中找到的 CPVApplication 專案。

更新在 App.config 檔案中找到的應用程式設定。

<!-- AppID that represents Control panel vendor application -->
<add key="ida:CPVApplicationId" value="" />

<!--
    Please use certificate as your client secret and deploy the certificate to your environment.
    The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:CPVApplicationSecret" value="" />

<!-- Endpoint address for the instance of Azure KeyVault -->
<add key="KeyVaultEndpoint" value="" />

<!-- AppID that is given access for keyvault to store the refresh tokens -->
<add key="ida:KeyVaultClientId" value="" />

<!--
    Please use certificate as your client secret and deploy the certificate to your environment.
    The following application secret is for sample application only. please do not use secret directly from the config file.
-->
<add key="ida:KeyVaultClientSecret" value="" />

針對在 Program.cs 檔案中找到的 PartnerId 和 CustomerId 變數設定適當的值。

// The following properties indicate which partner and customer context the calls are going to be made.
string PartnerId = "<Partner tenant id>";
string CustomerId = "<Customer tenant id>";

當您執行此範例專案時，該專案會取得指定合作夥伴的重新整理權杖。然後，它會要求存取令牌，以代表合作夥伴存取合作夥伴中心並Microsoft Graph。其執行的下一個工作是在客戶租用戶中刪除和建立授權授與。由於控制台廠商與客戶之間沒有任何關聯性，因此必須使用合作夥伴中心 API 來新增這些權限。下列範例會示範如何完成此作業。

JObject contents = new JObject
{
    // Provide your application display name
    ["displayName"] = "CPV Marketplace",

    // Provide your application id
    ["applicationId"] = CPVApplicationId,

    // Provide your application grants
    ["applicationGrants"] = new JArray(
        JObject.Parse("{\"enterpriseApplicationId\": \"00000003-0000-0000-c000-000000000000\", \"scope\":\"Domain.ReadWrite.All,User.ReadWrite.All,Directory.Read.All\"}"), // for Microsoft Graph access,  Directory.Read.All
        JObject.Parse("{\"enterpriseApplicationId\": \"797f4846-ba00-4fd7-ba43-dac1f8f63013\", \"scope\":\"user_impersonation\"}")) // for Azure Resource Manager access
};

/**
 * The following steps have to be performed once per customer tenant if your application is
 * a control panel vendor application and requires customer tenant Microsoft Graph access.
 **/

// delete the previous grant into customer tenant
JObject consentDeletion = await ApiCalls.DeleteAsync(
    tokenPartnerResult.Item1,
    string.Format("https://api.partnercenter.microsoft.com/v1/customers/{0}/applicationconsents/{1}", CustomerId, CPVApplicationId));

// create new grants for the application given the setting in application grants payload.
JObject consentCreation = await ApiCalls.PostAsync(
    tokenPartnerResult.Item1,
    string.Format("https://api.partnercenter.microsoft.com/v1/customers/{0}/applicationconsents", CustomerId),
    contents.ToString());

建立這些許可權之後，此範例會代表客戶使用 Microsoft Graph 來執行作業。

注意

如需 Microsoft Graph 的詳細資訊，請參閱 Microsoft Graph 概觀。

Java (CPV 驗證)

為雲端解決方案提供者合作夥伴開發及部署流程，以提供適當的同意。如需詳細資訊和範例，請參閱合作夥伴同意。

重要

您不應儲存來自雲端解決方案提供者合作夥伴的使用者認證。應儲存透過合作夥伴同意程序取得的重新整理權杖，並用來要求存取權杖，以便與任何 Microsoft API 互動。