Создание приложений Go с помощью Microsoft Graph и проверки подлинности только для приложений - Microsoft Graph

В этом руководстве описано, как создать консольное приложение Go, которое использует microsoft API Graph для доступа к данным с помощью проверки подлинности только для приложений. Проверка подлинности только для приложений — это хороший выбор для фоновых служб или приложений, которым требуется доступ к данным для всех пользователей в организации.

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Примечание.

Сведения о том, как использовать Microsoft Graph для доступа к данным от имени пользователя, см. в этом руководстве по проверке подлинности пользователя (делегированная).

В этом руководстве описан порядок выполнения перечисленных ниже задач.

Перечисление пользователей

Совет

Кроме того, вы можете скачать или клонировать репозиторий GitHub и следовать инструкциям в файле README, чтобы зарегистрировать приложение и настроить проект.

Предварительные требования

Прежде чем приступить к работе с этим руководством, на компьютере разработки должна быть установлена программа Go .

У вас также должна быть рабочая или учебная учетная запись Майкрософт с ролью глобальный администратор. Если у вас нет учетной записи Майкрософт, вы можете зарегистрироваться в программе для разработчиков Microsoft 365 , чтобы получить бесплатную подписку На Microsoft 365.

Примечание.

Это руководство было написано с go версии 1.19.3. Действия, описанные в этом руководстве, могут работать с другими версиями, но не были протестированы.

Регистрация приложения на портале

Осталось 18 мин

В этом упражнении вы зарегистрируете новое приложение в Azure Active Directory, чтобы включить проверку подлинности только для приложений. Вы можете зарегистрировать приложение с помощью Центра администрирования Azure Active Directory или с помощью пакета SDK Для Microsoft Graph PowerShell.

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Регистрация приложения для проверки подлинности только для приложений

В этом разделе описано, как зарегистрировать приложение, которое будет поддерживать проверку подлинности пользователей с помощью потока учетных данных клиента.

Центр администрирования Azure AD
PowerShell

Откройте браузер, перейдите в Центр администрирования Azure Active Directory и выполните вход с помощью учетной записи глобальный администратор.
Выберите Azure Active Directory на панели навигации слева, затем выберите Регистрация приложений в разделе Управление.
Выберите Новая регистрация. Введите имя приложения, например Go App-Only Graph Tutorial.
Задайте для параметра Поддерживаемые типы учетных записейзначение Учетные записи только в этом каталоге организации.
Оставьте поле URI перенаправления пустым.
Нажмите Зарегистрировать. На странице Обзор приложения скопируйте значение идентификатора приложения (клиента) и идентификатора каталога (клиента) и сохраните их. Эти значения потребуются на следующем шаге.
Выберите Разрешения API в разделе Управление.
Удалите разрешение User.Read по умолчанию в разделе Настроенные разрешения , выбрав многоточие (...) в строке и выбрав Удалить разрешение.
Выберите Добавить разрешение, а затем — Microsoft Graph.
Выберите Разрешения приложения.
Выберите User.Read.All, а затем выберите Добавить разрешения.
Выберите Предоставить согласие администратора для..., а затем нажмите кнопку Да , чтобы предоставить согласие администратора для выбранного разрешения.
Выберите Сертификаты и секреты в разделе Управление, а затем выберите Новый секрет клиента.
Введите описание, выберите длительность и нажмите кнопку Добавить.
Скопируйте секрет из столбца Значение . Он понадобится на следующих шагах.

Важно!

Система никогда не покажет секрет клиента повторно, поэтому убедитесь, что вы скопировали его.

Чтобы использовать PowerShell, вам потребуется пакет SDK Для Microsoft Graph PowerShell. Если у вас его нет, инструкции по установке см. в разделе Установка пакета SDK Для Microsoft Graph PowerShell .

Создайте файл с именем RegisterAppForAppOnlyAuth.ps1 и добавьте следующий код.

param(
  [Parameter(Mandatory=$true,
  HelpMessage="The friendly name of the app registration")]
  [String]
  $AppName,

  [Parameter(Mandatory=$true,
  HelpMessage="The application permission scopes to configure on the app registration")]
  [String[]]
  $GraphScopes,

  [Parameter(Mandatory=$false)]
  [Switch]
  $StayConnected = $false
)

$graphAppId = "00000003-0000-0000-c000-000000000000"

# Requires an admin
Connect-MgGraph -Scopes "Application.ReadWrite.All User.Read" -UseDeviceAuthentication -ErrorAction Stop

# Get context for access to tenant ID
$context = Get-MgContext -ErrorAction Stop
$authTenant = $context.TenantId

# Create app registration
$appRegistration = New-MgApplication -DisplayName $AppName -SignInAudience "AzureADMyOrg" -ErrorAction Stop
Write-Host -ForegroundColor Cyan "App registration created with app ID" $appRegistration.AppId

# Create corresponding service principal
$appServicePrincipal = New-MgServicePrincipal -AppId $appRegistration.AppId -ErrorAction SilentlyContinue `
  -ErrorVariable SPError
if ($SPError)
{
  Write-Host -ForegroundColor Red "A service principal for the app could not be created."
  Write-Host -ForegroundColor Red $SPError
  Exit
}

Write-Host -ForegroundColor Cyan "Service principal created"

# Lookup available Graph application permissions
$graphServicePrincipal = Get-MgServicePrincipal -Filter ("appId eq '" + $graphAppId + "'") -ErrorAction Stop
$graphAppPermissions = $graphServicePrincipal.AppRoles

$resourceAccess = @()

foreach($scope in $GraphScopes)
{
  $permission = $graphAppPermissions | Where-Object { $_.Value -eq $scope }
  if ($permission)
  {
    $resourceAccess += @{ Id =  $permission.Id; Type = "Role"}
  }
  else
  {
    Write-Host -ForegroundColor Red "Invalid scope:" $scope
    Exit
  }
}

# Add the permissions to required resource access
Update-MgApplication -ApplicationId $appRegistration.Id -RequiredResourceAccess `
 @{ ResourceAppId = $graphAppId; ResourceAccess = $resourceAccess } -ErrorAction Stop
Write-Host -ForegroundColor Cyan "Added application permissions to app registration"

# Add admin consent
foreach ($appRole in $resourceAccess)
{
  $appServicePrincipal
  New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $appServicePrincipal.Id `
   -PrincipalId $appServicePrincipal.Id -ResourceId $graphServicePrincipal.Id `
   -AppRoleId $appRole.Id -ErrorAction SilentlyContinue -ErrorVariable SPError | Out-Null
  if ($SPError)
  {
    Write-Host -ForegroundColor Red "Admin consent for one of the requested scopes could not be added."
    Write-Host -ForegroundColor Red $SPError
    Exit
  }
}
Write-Host -ForegroundColor Cyan "Added admin consent"

# Add a client secret
$clientSecret = Add-MgApplicationPassword -ApplicationId $appRegistration.Id -PasswordCredential `
 @{ DisplayName = "Added by PowerShell" } -ErrorAction Stop

Write-Host
Write-Host -ForegroundColor Green "SUCCESS"
Write-Host -ForegroundColor Cyan -NoNewline "Client ID: "
Write-Host -ForegroundColor Yellow $appRegistration.AppId
Write-Host -ForegroundColor Cyan -NoNewline "Tenant ID: "
Write-Host -ForegroundColor Yellow $authTenant
Write-Host -ForegroundColor Cyan -NoNewline "Client secret: "
Write-Host -ForegroundColor Yellow $clientSecret.SecretText
Write-Host -ForegroundColor Cyan -NoNewline "Secret expires: "
Write-Host -ForegroundColor Yellow $clientSecret.EndDateTime

if ($StayConnected -eq $false)
{
  Disconnect-MgGraph
  Write-Host "Disconnected from Microsoft Graph"
}
else
{
  Write-Host
  Write-Host -ForegroundColor Yellow `
   "The connection to Microsoft Graph is still active. To disconnect, use Disconnect-MgGraph"
}

Сохраните файл.
Откройте PowerShell и измените текущий каталог на расположение RegisterAppForAppOnlyAuth.ps1.

Выполните следующую команду.

.\RegisterAppForAppOnlyAuth.ps1 -AppName "Go App-Only Graph Tutorial" -GraphScopes "User.Read.All"

Следуйте запросу, чтобы открыть https://microsoft.com/devicelogin в браузере, введите предоставленный код и завершите процесс проверки подлинности.
Скопируйте значения идентификатора клиента, идентификатора клиента и секрета клиента из выходных данных скрипта. Эти значения потребуются на следующем шаге.
```
SUCCESS
Client ID: ae2386e6-799e-4f75-b191-855d7e691c75
Tenant ID: 5927c10a-91bd-4408-9c70-c50bce922b71
Client secret: ...
Secret expires: 10/28/2024 5:01:45 PM
```

Примечание.

Обратите внимание, что в отличие от действий при регистрации для проверки подлинности пользователей в этом разделе вы настроили разрешения Microsoft Graph для регистрации приложения. Это связано с тем, что проверка подлинности только для приложений использует поток учетных данных клиента, который требует настройки разрешений на регистрацию приложения. Дополнительные сведения см. в область по умолчанию.

Создание консольного приложения Go

Осталось 15 мин

Начните с инициализации нового модуля Go с помощью Go CLI. Откройте интерфейс командной строки (CLI) в каталоге, в котором вы хотите создать проект. Выполните следующую команду.

go mod init graphapponlytutorial

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Установка зависимостей

Прежде чем переходить дальше, добавьте некоторые дополнительные зависимости, которые будут использоваться позже.

Клиентский модуль удостоверений Azure для Go для проверки подлинности пользователя и получения маркеров доступа.
Пакет SDK Microsoft Graph для Go для выполнения вызовов к Microsoft Graph.
GoDotEnv для чтения переменных среды из ENV-файлов.

Выполните следующие команды в интерфейсе командной строки, чтобы установить зависимости.

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

Загрузка параметров приложения

В этом разделе вы добавите в проект сведения о регистрации приложения.

Создайте файл в том же каталоге, что и go.mod с именем .env , и добавьте следующий код.
```
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.

Проектирование приложения

В этом разделе вы создадите простое меню на основе консоли.

Создайте новый каталог в том же каталоге, что и go.mod с именем graphhelper.

Добавьте новый файл в каталог graphhelper с именем graphhelper.go и добавьте следующий код.

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.

Создайте файл в том же каталоге, что и go.mod с именем graphtutorial.go. Добавьте в него указанный ниже код.

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
}

Это реализует базовое меню и считывает выбор пользователя из командной строки.

Добавление проверки подлинности только для приложений

Осталось 10 мин

В этом разделе вы добавите в приложение проверку подлинности только для приложений. он требуется для получения необходимого маркера доступа OAuth для вызова Microsoft Graph. На этом шаге вы интегрируете в приложение клиентский модуль удостоверений Azure для Go и настроите проверку подлинности для пакета SDK Microsoft Graph для Go.

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Библиотека удостоверений Azure предоставляет ряд классов, которые реализуют потоки маркеров TokenCredential OAuth2. Пакет SDK для Microsoft Graph использует эти классы для проверки подлинности вызовов 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 при сохранении. Возможно, потребуется повторно добавить модули для сборки.

Замените пустую initializeGraph функцию в graphapponlytutorial.go следующим кодом.

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. Каждый раз, когда вызов API выполняется в Microsoft Graph через userClient, он будет использовать предоставленные учетные данные для получения маркера доступа.

Тестирование 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
}

Замените пустую displayAccessToken функцию в graphapponlytutorial.go следующим кодом.

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...
```
Совет

Только для проверки и отладки можно декодировать маркеры доступа только для приложений с помощью средства синтаксического анализа токенов Майкрософт в сети по адресу https://jwt.ms. Это может быть полезно, если при вызове Microsoft Graph возникают ошибки маркера. Например, убедитесь, что role утверждение в маркере содержит ожидаемые области разрешений Microsoft Graph.

Перечисление пользователей

Осталось 7 мин

В этом разделе вы добавите возможность вывода списка всех пользователей в Azure Active Directory с помощью проверки подлинности только для приложений.

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Добавьте следующую функцию в ./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,
            })
}

Замените пустую listUsers функцию в graphapponlytutorial.go следующим кодом.

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 для сортировки ответа

Необязательно: добавление собственного кода

Осталось 5 мин

В этом разделе вы добавите в приложение собственные возможности Microsoft Graph. Это может быть фрагмент кода из документации Microsoft Graph, Обозреватель Graph или созданный вами код. Этот раздел является необязательным.

Важно!

Пакет SDK Microsoft Graph Go в настоящее время находится в предварительной версии сообщества и не должен использоваться в рабочей среде. В течение этого периода ожидаются критические изменения. Это руководство было написано в версии 0.47.0.

Обновите приложение

Добавьте следующую функцию в ./graphhelper/graphhelper.go.

func (g *GraphHelper) MakeGraphCall() error {
    // INSERT YOUR CODE HERE
    return nil
}

Замените пустую makeGraphCall функцию в graphapponlytutorial.go следующим кодом.

func makeGraphCall(graphHelper *graphhelper.GraphHelper) {
    err := graphHelper.MakeGraphCall()
    if err != nil {
        log.Panicf("Error making Graph call: %v", err)
    }
}

Выбор API

Найдите API в Microsoft Graph, который вы хотите попробовать. Например, API создания событий . Вы можете использовать один из примеров в документации по API или настроить запрос API в Graph Обозреватель и использовать созданный фрагмент.

Настройка разрешений

Ознакомьтесь с разделом Разрешения справочной документации по выбранному API, чтобы узнать, какие методы проверки подлинности поддерживаются. Некоторые API не поддерживают только приложения или личные учетные записи Майкрософт, например.

Чтобы вызвать API с проверкой подлинности пользователя (если API поддерживает проверку подлинности пользователя (делегированная) проверка подлинности, см. руководство по проверке подлинности пользователя (делегированная).
Чтобы вызвать API с проверкой подлинности только для приложений (если API поддерживает ее), добавьте необходимый область разрешений в Центре администрирования Azure AD.

Добавление кода

Скопируйте код в функцию MakeGraphCall в graphhelper.go. Если вы копируете фрагмент из документации или из Обозреватель Graph, обязательно переименуйте в GraphServiceClientappClient.

Поздравляем!

100% завершено

Вы завершили руководство по Microsoft Graph для Go. Теперь, когда у вас есть рабочее приложение, которое вызывает Microsoft Graph, вы можете экспериментировать и добавлять новые функции.

Узнайте, как использовать проверку подлинности пользователя (делегированная) с помощью пакета SDK Microsoft Graph Go.
Просмотрите обзор Microsoft Graph , чтобы просмотреть все данные, к которым можно получить доступ с помощью Microsoft Graph.