使用 Microsoft Graph 和僅限應用程式驗證建置 Go 應用程式
本教學課程會教導您如何建置使用 Microsoft Graph API 的 Go 控制台應用程式,以使用僅限應用程式的驗證來存取數據。 對於需要存取組織中所有用戶數據的背景服務或應用程式而言,僅限應用程式驗證是不錯的選擇。
注意
若要瞭解如何使用 Microsoft Graph 代表使用者存取數據,請參閱此 使用者 (委派) 驗證教學課程。
在本教學課程中,您將:
提示
除了遵循本教學課程,您可以下載或複製 GitHub 存放庫 ,並遵循自述檔中的指示來註冊應用程式並設定專案。
必要條件
開始本教學課程之前,您應該已在開發計算機上安裝 Go 。
您也應該擁有具有全域管理員角色Microsoft公司或學校帳戶。 如果您沒有Microsoft 365 租使用者,您可能有資格透過 Microsoft 365 開發人員計劃;如需詳細資訊,請參閱 常見問題。 或者,您可以 註冊 1 個月的免費試用版,或購買Microsoft 365 方案。
注意
本教學課程是使用 Go 1.19.3 版所撰寫。 本指南中的步驟可能適用於其他版本,但尚未經過測試。
在入口網站中註冊應用程式
在此練習中,您將在 Azure Active Directory 中註冊新的應用程式,以啟用 僅限應用程式的驗證。 您可以使用 Microsoft Entra 系統管理中心或使用 Microsoft Graph PowerShell SDK 來註冊應用程式。
註冊應用程式以進行僅限應用程式驗證
在本節中,您將使用 用戶端認證流程註冊支援僅限應用程式驗證的應用程式。
開啟瀏覽器並流覽至 Microsoft Entra 系統管理中心 ,並使用全域系統管理員帳戶登入。
選Microsoft左側導覽中的 [Entra ID ],依序展開 [ 身分識別]、[ 應用程式],然後選取 [ 應用程式註冊]。
選取 [新增註冊]。 輸入應用程式名稱,例如
Graph App-Only Auth Tutorial
。將 [支持的帳戶類型] 設定為 [僅限此組織目錄中的帳戶]。
將 [重新導向 URI ] 保留空白。
選取 [登錄]。 在應用程式的 [ 概觀 ] 頁面上,複製應用程式 (用戶端) 標識 符和 目錄 (租使用者) 標識 符的值並加以儲存,您在下一個步驟中將需要這些值。
在 [管理] 底下,選取 [API 權限]。
選取其數據列中的省略號 (...) ,然後選取 [移除許可權],以移除 [設定的許可權] 下的默認 User.Read 許可權。
選 取 [新增許可權],然後 Microsoft圖形]。
選取 應用程式權限。
選 取 [User.Read.All],然後選取 [ 新增許可權]。
選 取 [授與系統管理員同意...],然後選取 [ 是 ] 以提供所選許可權的管理員同意。
選取 [管理] 底下的 [憑證和秘密],然後選取 [新增客戶端密碼]。
輸入描述,選擇持續時間,然後選取 [ 新增]。
從 [ 值 ] 資料行複製秘密,您在後續步驟中將需要它。
重要
此用戶端密碼永不再顯示,因此現在請您確認將其複製。
注意
請注意,與註冊用戶驗證時的步驟不同,在本節中,您已設定Microsoft應用程式註冊的 Graph 許可權。 這是因為僅限應用程式的驗證會使用客戶端 認證流程,這需要在應用程式註冊上設定許可權。 如需詳細資訊,請參閱 .default 範圍。
建立 Go 控制台應用程式
從使用 Go CLI 初始化新的 Go 模組開始。 在您要建立項目的目錄中, (CLI) 開啟命令行介面。 執行下列指令:
go mod init graphapponlytutorial
安裝相依性
繼續之前,請新增一些您稍後將使用的額外相依性。
- 適用於 Go 的 Azure 身分識別用戶端模組 可驗證使用者並取得存取令牌。
- Microsoft Graph SDK for Go 呼叫 Microsoft Graph。
- GoDotEnv ,用於從 .env 檔案讀取環境變數。
在 CLI 中執行下列命令以安裝相依性。
go get github.com/Azure/azure-sdk-for-go/sdk/azidentity
go get github.com/microsoftgraph/msgraph-sdk-go
go get github.com/joho/godotenv
載入應用程式設定
在本節中,您會將應用程式註冊的詳細數據新增至專案。
在名為 .env 的 go.mod 相同目錄中建立檔案,並新增下列程序代碼。
CLIENT_ID=YOUR_CLIENT_ID_HERE CLIENT_SECRET=YOUR_CLIENT_SECRET_HERE TENANT_ID=YOUR_TENANT_ID_HERE
根據下表更新值。
設定 值 CLIENT_ID
應用程式註冊的用戶端識別碼 CLIENT_SECRET
應用程式註冊的客戶端密碼 TENANT_ID
貴組織的租用戶標識碼 提示
您可以選擇性地在名為 .env.local 的個別檔案中設定這些值。
設計應用程式
在本節中,您將建立簡單的控制台型功能表。
在名為 graphhelper 的 go.mod 相同目錄中建立新目錄。
在 graphhelper.go 的 graphhelper 目錄中新增檔案,並新增下列程序代碼。
package graphhelper import ( "context" "os" "github.com/Azure/azure-sdk-for-go/sdk/azcore/policy" "github.com/Azure/azure-sdk-for-go/sdk/azidentity" auth "github.com/microsoft/kiota-authentication-azure-go" msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go" "github.com/microsoftgraph/msgraph-sdk-go/models" "github.com/microsoftgraph/msgraph-sdk-go/users" ) type GraphHelper struct { clientSecretCredential *azidentity.ClientSecretCredential appClient *msgraphsdk.GraphServiceClient } func NewGraphHelper() *GraphHelper { g := &GraphHelper{} return g }
這會建立基本 的 GraphHelper 類型,您將在稍後的章節中擴充以使用 Microsoft Graph。
在名為 graphapponlytutorial.go 的 go.mod 相同目錄中建立檔案。 新增下列程式碼。
package main import ( "fmt" "graphapponlytutorial/graphhelper" "log" "github.com/joho/godotenv" ) func main() { fmt.Println("Go Graph App-Only Tutorial") fmt.Println() // Load .env files // .env.local takes precedence (if present) godotenv.Load(".env.local") err := godotenv.Load() if err != nil { log.Fatal("Error loading .env") } graphHelper := graphhelper.NewGraphHelper() initializeGraph(graphHelper) var choice int64 = -1 for { fmt.Println("Please choose one of the following options:") fmt.Println("0. Exit") fmt.Println("1. Display access token") fmt.Println("2. List users") fmt.Println("3. Make a Graph call") _, err = fmt.Scanf("%d", &choice) if err != nil { choice = -1 } switch choice { case 0: // Exit the program fmt.Println("Goodbye...") case 1: // Display access token displayAccessToken(graphHelper) case 2: // List users listUsers(graphHelper) case 3: // Run any Graph code makeGraphCall(graphHelper) default: fmt.Println("Invalid choice! Please try again.") } if choice == 0 { break } } }
在文件尾新增下列佔位符方法。 您將在後續步驟中實作它們。
func initializeGraph(graphHelper *graphhelper.GraphHelper) { // TODO } func displayAccessToken(graphHelper *graphhelper.GraphHelper) { // TODO } func listUsers(graphHelper *graphhelper.GraphHelper) { // TODO } func makeGraphCall(graphHelper *graphhelper.GraphHelper) { // TODO }
這會實作基本功能表,並從命令行讀取用戶的選擇。
新增僅限應用程序驗證
在本節中,您會將僅限應用程式的驗證新增至應用程式。 需要 his 才能取得必要的 OAuth 存取令牌,才能呼叫 Microsoft Graph。 在此步驟中,您會將 適用於 Go 的 Azure 身 分識別用戶端模組整合到應用程式中,併為 Microsoft Graph SDK for Go 設定驗證。
Azure 身分識別連結庫提供數個實作 OAuth2 令牌流程的 TokenCredential
類別。 Microsoft Graph SDK 會使用這些類別來驗證對 Microsoft Graph 的呼叫。
設定僅限應用程式驗證的 Graph 用戶端
在本節中, ClientSecretCredential
您將使用 類別,使用 用戶端認證流程來要求存取令牌。
將下列函式新增至 ./graphhelper/graphhelper.go。
func (g *GraphHelper) InitializeGraphForAppAuth() error { clientId := os.Getenv("CLIENT_ID") tenantId := os.Getenv("TENANT_ID") clientSecret := os.Getenv("CLIENT_SECRET") credential, err := azidentity.NewClientSecretCredential(tenantId, clientId, clientSecret, nil) if err != nil { return err } g.clientSecretCredential = credential // Create an auth provider using the credential authProvider, err := auth.NewAzureIdentityAuthenticationProviderWithScopes(g.clientSecretCredential, []string{ "https://graph.microsoft.com/.default", }) if err != nil { return err } // Create a request adapter using the auth provider adapter, err := msgraphsdk.NewGraphRequestAdapter(authProvider) if err != nil { return err } // Create a Graph client using request adapter client := msgraphsdk.NewGraphServiceClient(adapter) g.appClient = client return nil }
提示
如果您使用 goimports,某些模組可能已從
import
graphhelper.go on save 的語句中自動移除。 您可能需要重新新增模組以進行建置。以下列內容取代 graphapponlytutorial.go 中的空白
initializeGraph
函式。func initializeGraph(graphHelper *graphhelper.GraphHelper) { err := graphHelper.InitializeGraphForAppAuth() if err != nil { log.Panicf("Error initializing Graph for app auth: %v\n", err) } }
此程式代碼會初始化兩個 DeviceCodeCredential
屬性:物件和 GraphServiceClient
物件。 函 InitializeGraphForUserAuth
式會建立 的新實例 DeviceCodeCredential
,然後使用該實例來建立 的新實 GraphServiceClient
例。 每次透過 Microsoft Graph userClient
進行 API 呼叫時,它都會使用提供的認證來取得存取令牌。
測試 ClientSecretCredential
接下來,新增程式代碼以從 ClientSecretCredential
取得存取令牌。
將下列函式新增至 ./graphhelper/graphhelper.go。
func (g *GraphHelper) GetAppToken() (*string, error) { token, err := g.clientSecretCredential.GetToken(context.Background(), policy.TokenRequestOptions{ Scopes: []string{ "https://graph.microsoft.com/.default", }, }) if err != nil { return nil, err } return &token.Token, nil }
以下列內容取代 graphapponlytutorial.go 中的空白
displayAccessToken
函式。func displayAccessToken(graphHelper *graphhelper.GraphHelper) { token, err := graphHelper.GetAppToken() if err != nil { log.Panicf("Error getting user token: %v\n", err) } fmt.Printf("App-only token: %s", *token) fmt.Println() }
執行 來建置並執行
go run graphapponlytutorial
應用程式。 當系統提示您輸入選項時,請輸入1
。 應用程式會顯示存取令牌。Go Graph App-Only Tutorial Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 1 App-only token: eyJ0eXAiOiJKV1QiLCJub25jZSI6IlVDTzRYOWtKYlNLVjVkRzJGenJqd2xvVUcwWS...
提示
僅供驗證和偵錯之用,您可以在 使用 Microsoft 的在線令牌剖析器https://jwt.ms來譯碼僅限應用程式的存取令牌。 如果您在呼叫 Microsoft Graph 時遇到令牌錯誤,這會很有用。 例如,確認
role
令牌中的宣告包含預期的 Microsoft Graph 許可權範圍。
列出使用者
在本節中,您將新增使用僅限應用程式驗證列出 Azure Active Directory 中所有使用者的功能。
將下列函式新增至 ./graphhelper/graphhelper.go。
func (g *GraphHelper) GetUsers() (models.UserCollectionResponseable, error) { var topValue int32 = 25 query := users.UsersRequestBuilderGetQueryParameters{ // Only request specific properties Select: []string{"displayName", "id", "mail"}, // Get at most 25 results Top: &topValue, // Sort by display name Orderby: []string{"displayName"}, } return g.appClient.Users(). Get(context.Background(), &users.UsersRequestBuilderGetRequestConfiguration{ QueryParameters: &query, }) }
以下列內容取代 graphapponlytutorial.go 中的空白
listUsers
函式。func listUsers(graphHelper *graphhelper.GraphHelper) { users, err := graphHelper.GetUsers() if err != nil { log.Panicf("Error getting users: %v", err) } // Output each user's details for _, user := range users.GetValue() { fmt.Printf("User: %s\n", *user.GetDisplayName()) fmt.Printf(" ID: %s\n", *user.GetId()) noEmail := "NO EMAIL" email := user.GetMail() if email == nil { email = &noEmail } fmt.Printf(" Email: %s\n", *email) } // If GetOdataNextLink does not return nil, // there are more users available on the server nextLink := users.GetOdataNextLink() fmt.Println() fmt.Printf("More users available? %t\n", nextLink != nil) fmt.Println() }
執行應用程式、登入,然後選擇選項 2 來列出使用者。
Please choose one of the following options: 0. Exit 1. Display access token 2. List users 3. Make a Graph call 2 User: Adele Vance ID: 05fb57bf-2653-4396-846d-2f210a91d9cf Email: AdeleV@contoso.com User: Alex Wilber ID: a36fe267-a437-4d24-b39e-7344774d606c Email: AlexW@contoso.com User: Allan Deyoung ID: 54cebbaa-2c56-47ec-b878-c8ff309746b0 Email: AllanD@contoso.com User: Bianca Pisani ID: 9a7dcbd0-72f0-48a9-a9fa-03cd46641d49 Email: NO EMAIL User: Brian Johnson (TAILSPIN) ID: a8989e40-be57-4c2e-bf0b-7cdc471e9cc4 Email: BrianJ@contoso.com ... More users available? true
程式代碼說明
請考慮函式中的程序 GetUsers
代碼。
- 它會取得使用者的集合
- 它會使用
Select
來要求特定屬性 - 它會使用
Top
來限制傳回的用戶數目 - 它會使用
OrderBy
來排序回應
選擇性:新增您自己的程序代碼
在本節中,您會將自己的 Microsoft Graph 功能新增至應用程式。 這可能是來自 Microsoft Graph 檔 或 Graph 總管的代碼段,或您所建立的程式碼。 此區段為選擇性。
更新應用程式
將下列函式新增至 ./graphhelper/graphhelper.go。
func (g *GraphHelper) MakeGraphCall() error { // INSERT YOUR CODE HERE return nil }
以下列內容取代 graphapponlytutorial.go 中的空白
makeGraphCall
函式。func makeGraphCall(graphHelper *graphhelper.GraphHelper) { err := graphHelper.MakeGraphCall() if err != nil { log.Panicf("Error making Graph call: %v", err) } }
選擇 API
在您想要嘗試Microsoft圖形中尋找 API。 例如, 建立事件 API。 您可以使用 API 檔中的其中一個範例,也可以在 Graph 總管中自定義 API 要求,並使用產生的代碼段。
設定許可權
請查看所選取 API 參考檔的 [許可權] 區段, 以查看支援哪些驗證方法。 例如,某些 API 不支援僅限應用程式或個人Microsoft帳戶。
- 若要在 API 支援使用者 (委派的) 驗證) 時,使用使用者驗證 (呼叫 API,請參閱 使用者 (委派的) 驗證 教學課程。
- 若要使用僅限應用程式的驗證來呼叫 API (如果 API 支援它) ,請在 Azure AD 系統管理中心新增必要的許可權範圍。
新增您的程序代碼
將您的程式代碼複製到 MakeGraphCall
graphhelper.go 中的 函式。 如果您要從檔案或 Graph 總管複製代碼段,請務必將 重新命名 GraphServiceClient
為 appClient
。
恭喜!
您已完成 Go Microsoft Graph 教學課程。 既然您有一個可呼叫 Microsoft Graph 的工作應用程式,您可以實驗並新增新功能。
- 瞭解如何使用 使用者 (委派的) 驗證 搭配 Microsoft Graph Go SDK。
- 請造訪 Microsoft Graph 概觀 ,以查看您可以使用 Microsoft Graph 存取的所有數據。
在這個區段有遇到問題嗎? 如果有,請提供意見反應,好讓我們可以改善這個區段。