在國家雲端環境中使用 MSAL

文章
07/02/2024

國家雲端 (也稱為主權雲端) 是實際隔離的 Azure 執行個體。這些 Azure 區域可協助確保符合地理界限內的資料落地、主權及合規性需求。

除了 Microsoft 全球雲端，Microsoft 驗證程式庫 (MSAL) 可讓國家雲端中的應用程式開發人員取得權杖，以驗證及呼叫受保護的 Web API。這些 Web API 可以是 Microsoft Graph 或其他 Microsoft API。

包括全域 Azure 雲端，Microsoft Entra ID 部署在下列國家/地區雲端中：

Azure Government
由 21Vianet 營運的 Microsoft Azure
Azure 德國 (已於 2021 年 10 月 29 日關閉)

本指南示範如何登入公司和學校帳戶、取得存取權杖，以及在 Azure Government 雲端環境中呼叫 Microsoft Graph API。

Azure 德國 (Microsoft Cloud Deutschland)

警告

Azure 德國 (Microsoft Cloud Deutschland) 將於 2021 年 10 月 29 日關閉。您選擇在該日期前不移轉至全域 Azure 中區域的服務和應用程式將變成無法存取。

如果您尚未從 Azure 德國移轉應用程式，請遵循用於從 Azure 德國移轉的 Microsoft Entra 資訊開始使用。

必要條件

開始之前，請確保您符合這些必要條件。

選擇適當的身分識別

Azure Government 應用程式可以使用 Microsoft Entra Government 身分識別和 Microsoft Entra 公用身分識別來驗證使用者。由於您可以使用任何這些身分識別，因此請決定您應為情節選擇哪個授權單位端點：

Microsoft Entra Public：如果您的組織已經有Microsoft Entra 公用租用戶，可支援 Microsoft 365 (公用或 GCC) 或其他應用程式，則通常使用。
Microsoft Entra Government：如果您的組織已經有 Microsoft Entra Government 租用戶來支援 Office 365 (GCC High 或 DoD)，或正在 Microsoft Entra Government 中建立新租用戶，則通常使用。

在您決定之後，有個特殊考慮是您要在哪裡執行應用程式註冊。如果您為 Microsoft Entra 應用程式選擇 Azure AD 公用身分識別，您必須在 Microsoft Entra 公用租用戶中註冊該應用程式。

取得 Azure Government 訂用帳戶

若要取得 Azure Government 訂用帳戶，請參閱在 Azure Government 中管理及連接到訂用帳戶。

如果您沒有 Azure Government 訂用帳戶，請在開始前建立免費帳戶。

如需使用國家雲端搭配特定程式設計語言的詳細資訊，請選擇符合您語言的索引標籤：

您可以使用 MSAL.NET 來登入使用者、取得權杖，並在國家雲端中呼叫 Microsoft Graph API。

下列教學課程示範如何建置 ASP.NET Core Web 應用程式。此應用程式會使用 OpenID Connect，在屬於國家雲端的組織中使用公司和學校帳戶來登入使用者。

若要登入使用者並取得權杖，請遵循本教學課程：使用 Microsoft 身分識別平台在主權雲端中建置 ASP.NET Core Web 應用程式登入使用者。
若要呼叫 Microsoft 圖形 API，請遵循本教學課程：使用 Microsoft 身分識別平台，代表使用者在 Microsoft National Cloud 中使用其工作和學校帳戶登入，從 ASP.NET Core Web 應用程式呼叫 Microsoft 圖形 API。

若要讓 MSAL.js 應用程式能夠使用主權雲端：

根據雲端在特定入口網站中註冊應用程式。如需如何選擇入口網站的詳細資訊，請參閱應用程式註冊端點
使用存放庫中的任何樣本，其中包含一些設定的變更，視接下來所述的雲端而定。
根據您在其中註冊應用程式的雲端而定，使用特定授權單位。如需不同雲端授權單位的詳細資訊，請參閱 Microsoft Entra 驗證端點。
呼叫 Microsoft Graph API 需要您所使用之雲端專用的端點 URL。若要尋找所有國家雲端的 Microsoft Graph 端點，請參閱 Microsoft Graph 和 Graph Explorer 服務根端點。

以下是範例授權單位：

"authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"

以下是 Microsoft Graph 端點的範例 (包含範圍)：

"endpoint" : "https://graph.microsoft.us/v1.0/me"
"scope": "User.Read"

以下是使用主權雲端驗證使用者並呼叫 Microsoft Graph 的最基本程式碼：

const msalConfig = {
    auth: {
        clientId: "Enter_the_Application_Id_Here",
        authority: "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here",
        redirectUri: "/",
    }
};

// Initialize MSAL
const msalObj = new PublicClientApplication(msalConfig);

// Get token using popup experience
try {
    const graphToken = await msalObj.acquireTokenPopup({
        scopes: ["User.Read"]
    });
} catch(error) {
    console.log(error)
}

// Call the Graph API
const headers = new Headers();
const bearer = `Bearer ${graphToken}`;

headers.append("Authorization", bearer);

fetch("https://graph.microsoft.us/v1.0/me", {
    method: "GET",
    headers: headers
})

若要讓 MSAL Python 應用程式能夠使用主權雲端：

根據雲端在特定入口網站中註冊應用程式。如需如何選擇入口網站的詳細資訊，請參閱應用程式註冊端點
使用存放庫中的任何樣本，其中包含一些設定的變更，視接下來所述的雲端而定。
根據您在其中註冊應用程式的雲端而定，使用特定授權單位。如需不同雲端授權單位的詳細資訊，請參閱 Microsoft Entra 驗證端點。

以下是範例授權單位：
```
"authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"
```
呼叫 Microsoft Graph API 需要您所使用之雲端專用的端點 URL。若要尋找所有國家雲端的 Microsoft Graph 端點，請參閱 Microsoft Graph 和 Graph Explorer 服務根端點。

以下是 Microsoft Graph 端點的範例 (包含範圍)：
```
"endpoint" : "https://graph.microsoft.us/v1.0/me"
"scope": "User.Read"
```

若要讓適用於 Java 的 MSAL 應用程式能夠使用主權雲端：

根據雲端在特定入口網站中註冊應用程式。如需如何選擇入口網站的詳細資訊，請參閱應用程式註冊端點
使用存放庫中的任何樣本，其中包含一些設定的變更，視接下來所述的雲端而定。
根據您在其中註冊應用程式的雲端而定，使用特定授權單位。如需不同雲端授權單位的詳細資訊，請參閱 Microsoft Entra 驗證端點。

以下是範例授權單位：

"authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"

呼叫 Microsoft Graph API 需要您所使用之雲端專用的端點 URL。若要尋找所有國家雲端的 Microsoft Graph 端點，請參閱 Microsoft Graph 和 Graph Explorer 服務根端點。

以下圖表端點的範例 (包含範圍)：

"endpoint" : "https://graph.microsoft.us/v1.0/me"
"scope": "User.Read"

適用於 iOS 和 macOS 的 MSAL 可以用來取得國家雲端中的權杖，但在建立 MSALPublicClientApplication 時需要額外的設定。

例如，如果您想要讓應用程式成為國家雲端 (在此為美國政府) 中的多租用戶應用程式，您可以撰寫如下：

MSALAADAuthority *aadAuthority =
                [[MSALAADAuthority alloc] initWithCloudInstance:MSALAzureUsGovernmentCloudInstance
                                                   audienceType:MSALAzureADMultipleOrgsAudience
                                                      rawTenant:nil
                                                          error:nil];

MSALPublicClientApplicationConfig *config =
                [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"
                                                                redirectUri:@"<your-redirect-uri-here>"
                                                                  authority:aadAuthority];

NSError *applicationError = nil;
MSALPublicClientApplication *application =
                [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&applicationError];

適用於 iOS 和 macOS 的 MSAL 可以用來取得國家雲端中的權杖，但在建立 MSALPublicClientApplication 時需要額外的設定。

例如，如果您想要讓應用程式成為國家雲端 (在此為美國政府) 中的多租用戶應用程式，您可以撰寫如下：

let authority = try? MSALAADAuthority(cloudInstance: .usGovernmentCloudInstance, audienceType: .azureADMultipleOrgsAudience, rawTenant: nil)

let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>", redirectUri: "<your-redirect-uri-here>", authority: authority)
if let application = try? MSALPublicClientApplication(configuration: config) { /* Use application */}

下一步

請參閱國家雲端驗證端點，以取得每個雲端的 Azure 入口網站 URL 和權杖端點的清單。

國家雲端文件：

分享方式：