Экспорт (0) Печать
Развернуть все

Использование API Graph для запроса в Azure AD

Обновлено: Май 2014 г.

noteПримечание
Примечание. Этот образец устарел. Его технологии, методы и (или) инструкции пользовательского интерфейса были заменены более новыми функциями. Чтобы увидеть обновленный образец, создающий похожее приложение, см. раздел WebApp-GraphAPI-DotNet.

Данное демонстрационное приложение предназначено для разработчиков .NET, желающих дополнить существующие приложения и строить новые приложения для Windows Azure Active Directory (Windows Azure AD). Это пошаговое руководство построено на руководстве Добавление единого входа в веб-приложение с помощью Azure AD, в котором создается демонстрационное приложение, показывающее, как предоставить интерфейс единого входа через Интернет клиентам Windows Azure AD. В настоящем пошаговом руководстве показывается, как использовать API Graph Windows Azure AD для чтения данных каталога. API Graph — это API RESTful, позволяющий приложениям получать доступ к данным каталога клиента Windows Azure.

Приложениям необходим доступ к данным каталога во многих сценариях, включая следующие.

  • Извлечение списков пользователей, групп, контактов для выбора людей или групп.

  • Чтение подробных сведений о клиенте, пользователе или группе.

  • Проверка членства в группе.

  • Изменение пользователей, групп и членства в группах.

  • Обновление паролей пользователей.

  • Отключение учетных записей пользователей.

noteПримечание
Если мультитенантное приложение пытается получить токен для доступа к API Graph для клиента Azure AD, который недавно отправил согласие для приложения, запрос токена может завершиться с ошибкой ACS50012. Чтобы устранить эту проблему, подождите несколько минут и повторите попытку. Или попросите администратора клиента, предоставившего согласие, войти в приложение после согласия. Дополнительные сведения см. в статье Коды ошибок ACS.

Документ состоит из следующих разделов.

Для прохождения настоящего руководства должны быть выполнены следующие предварительные требования.

В конце этого пошагового руководства вы получите приложение, настроенное для чтения данных из вашего клиента Azure AD. Это приложение сможет читать следующие сущности каталога: пользователи, группы, контакты, сведения о компании, лицензии и роли. Если этому приложению предоставить разрешения на запись, то оно также сможет обновлять эти сущности.

На примере этого приложения мы изучим, как можно читать данные каталога из Azure AD организации. Дополнительные разделы:

  • Получение полных сведений о пользователе

  • Создание и обновление пользователей

  • Получение списка групп

  • Обновление членства в группе

После обновления приложения, чтобы оно могло получать доступ к API Graph, взаимодействие единого входа останется прежним. После успешной проверки подлинности пользователя приложение запрашивает токен в конечной точке проверки подлинности Azure AD и после успешного получения использует этот токен в вызовах API Graph для получения всех пользователей из клиента. Приложение отображает список пользователей, показывающий их Display Names и User Principal Names.

Архитектура решения

В данном пошаговом руководстве для проверки подлинности и авторизации будет использоваться поток учетных данных клиента OAuth 2.0. Перед доступом к конечной точке API Graph приложение должно сначала получить допустимый токен от конечной точки проверки подлинности Azure AD — это делается путем представления правильных учетных данных приложения (идентификатора клиента и секрета). После успешной проверки учетных данных приложению возвращается подписанный токен. После этого приложение включает токен в заголовок Authorization своего вызова API Graph. Служба API Graph проверяет токен на соответствие входящему запросу, и если токен проходит эту проверку, авторизация продолжается дальше.

Авторизация приложения проверяется API Graph и его базовой службой управления доступом на основе ролей (RBAC). Вызовы API Graph ограничиваются разрешениями приложения. Данные возвращаются в приложение после успешного прохождения проверки подлинности и авторизации.

Конфигурация проверки подлинности и авторизации приложения сохраняется в Azure AD с помощью объекта Service Principal, хранящегося в каталоге клиента. Приложения представляются в Azure AD объектом Service Principal с уникальным удостоверением, учетными данными и разрешениями. Этот объект аналогичен объектам User Principal в Active Directory, которые представляют пользователей, и все они имеют уникальные идентификаторы, учетные данные и разрешения.

Объект приложения Service Principal имеет уникальный идентификатор и секрет, используемый для проверки подлинности. Авторизация управляется путем добавления субъекта-службы приложения в роль, имеющую необходимые разрешения. Администраторы клиента могут создавать субъекты-службы приложений и добавлять их в роли на портале управления Azure AD. Кроме того, администраторы клиента также могут управлять субъектами-службами с помощью Windows PowerShell. Дополнительные сведения см. в статье Управление Windows Azure Active Directory с помощью Windows PowerShell.

В пошаговом руководстве Добавление единого входа в веб-приложение с помощью Azure AD авторизация приложения выполнялась для разрешения единого входа с помощью учетных данных пользователя Azure AD путем настройки разрешений приложения на портале управления Azure AD. Теперь мы будем обновлять конфигурацию приложения, чтобы включить проверку подлинности и авторизацию приложения Expense Reporting для вызова API Graph. Мы будем выполнять следующие действия.

  • Авторизация. Настройка разрешений приложения для разрешения доступа на чтение и запись в каталоге.

  • Проверка подлинности. Получение ключа приложения, являющегося паролем приложения. Он используется для проверки подлинности приложения в API Graph.

  1. Перейдите на портал управления Microsoft Azure (https://manage.WindowsAzure.com), выполните вход и щелкните Active Directory. (Совет по устранению неполадок. "Active Directory" item is missing or not available (Элемент "Active Directory" отсутствует или недоступен))

  2. Щелкните ваш каталог, чтобы выбрать его, нажмите Приложения, а затем щелкните демонстрационное приложение Expense Reporting, созданное в пошаговом руководстве по единому входу.



    Внешний доступ

  3. Нажмите кнопку Управление доступом в нижней части страницы.

  4. Выберите пункт Изменить доступ к каталогу для этого приложения.



    Что необходимо сделать?
  5. Выберите вариант Единый вход, чтение данных каталога. Нажмите флажок, чтобы сохранить изменения.



    Доступ к каталогу

  1. На странице приложения Expense Reporting разверните узел Разрешить приложению чтение или запись данных каталога. В разделе Создать ключ выберите Настроить ключ.



    Настроить ключ

  2. Чтобы добавить ключ, на странице конфигурации в разделе Ключи выберите время существования ключа (по умолчанию 1 год) и нажмите кнопку Сохранить внизу экрана. В результате будет создан ключ, являющийся паролем приложения.

    WarningПредупреждение
    Значение ключа отображается при его создании, но позднее его cannot нельзя будет извлечь. Таким образом, значение ключа следует немедленно скопировать и сохранить в безопасном месте для будущего использования. Кроме того, приложение может иметь несколько ключей — например, могут быть разные ключи для тестовой и для рабочей среды.



    Ключ Graph

На этот момент у вас есть идентификатор клиента (идентификатор приложения) ключ приложения (значение ключа) и настроенные разрешения на чтение для этого приложения.

noteПримечание
В данном пошаговом руководстве мы используем значение ключа в качестве пароля для проверки подлинности приложения. В терминах OAuth 2.0 мы используем поток предоставления учетных данных клиента, где grant_type=client_credentials.

Откройте Visual Studio, а затем откройте учебный проект единого входа Expense Reporting, построенный ранее. Мы будем изменять учебное приложение с единым входом, выполняя следующие действия.

  1. Добавление проекта класса поддержки Graph.

  2. Обновление до версии не ниже WCF Datservices 5.3.

  3. Обновление файла Web.config.

  4. Изменение контроллера HomeController.

  5. Добавление нового представления для пользователей.

  6. Обновление общего представления _Layout.

Загрузите вспомогательную библиотеку API Graph Azure AD: Проект класса поддержки Graph Helper включает библиотеку и классы, облегчающие проверку подлинности и вызов API Graph. Он содержит исходный код и должен быть включен и построен в рамках этого пошагового руководства.

  1. Чтобы добавить класс Graph Helper в проект Expense Reporting, щелкните правой кнопкой мыши решение ExpenseReport, выберите в меню команду Добавить, а затем выберите пункт Существующий проект.

  2. В диалоговом окне Добавление существующего проекта перейдите в путь Graph Helper и откройте файл проекта Microsoft.WindowsAzure.ActiveDirectory.GraphHelper.csproj.

Теперь проект Graph Helper добавлен в решение ExpenseReport.

В разделе appSettings файла Web.config содержатся конфигурационные сведения, относящиеся к приложению. Добавьте пары "ключ-значение" ClientId и Password в файл Web.config приложения.

  • ClientId: соответствует значению идентификатора клиента на странице управления приложением портала управления Azure AD.

  • Password: соответствует значению ключа приложения на странице управления приложением портала управления Azure AD. Это значение должно было быть записано в предыдущем этапе создания ключа — помните, что извлечь его нельзя. если вы забыли или потеряли ключ, создайте другой ключ в этом же приложении.

<appSettings>
    <add key="ClientId" value="<insert your ClientId here>"/>
    <add key="Password" value="<insert your Application Key here>"/>
    ...

После внесения изменений сохраните файл Web.config.

  1. В Visual Studio щелкните правой кнопкой мыши папку Ссылки проекта Expense Reporting и выберите в меню команду Добавить ссылку…

  2. В диалоговом окне Диспетчер ссылок выберите раздел Расширения, а затем выберите сборку Microsoft.Data.OData версии 5.3.0.0 и сборку Microsoft.Data.Services.Client версии5.3.0.0.



    Справочник по OData
  3. В этом же диалоговом окне Диспетчер ссылок разверните меню Решение слева и установите флажок для Microsoft.WindowsAzure.ActiveDirectory.GraphHelper. Нажмите кнопку ОК, после чего ссылки будут добавлены в проект.



    Добавить ссылку на модуль поддержки Graph

Откройте файл HomeController.cs, который находится в папке Контроллеры. Добавьте в этот файл следующие сборки, а затем сохраните его.

using System.Configuration;
using System.Security.Claims;
using System.Data.Services.Client;
using Microsoft.WindowsAzure.ActiveDirectory;
using Microsoft.WindowsAzure.ActiveDirectory.GraphHelper;

Найдите класс HomeController в файле HomeController.cs, где размещаются существующиеActionResult (Index, About, Contact). Добавьте новый ActionResult с именем Users, как показано ниже:

       public ActionResult Users()
       {
            //get the tenantName
            string tenantName = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/tenantid").Value;



            // retrieve the clientId and password values from the Web.config file
            string clientId = ConfigurationManager.AppSettings["ClientId"];
            string password = ConfigurationManager.AppSettings["Password"];



            // get a token using the helper
            AADJWTToken token = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);

            // initialize a graphService instance using the token acquired from previous step
            DirectoryDataService graphService = new DirectoryDataService(tenantName, token);

            //  get Users
            //
            var users = graphService.users;
            QueryOperationResponse<User> response;
            response = users.Execute() as QueryOperationResponse<User>;
            List<User> userList = response.ToList();
            ViewBag.userList = userList;


            //  For subsequent Graph Calls, the existing token should be used.
            //  The following checks to see if the existing token is expired or about to expire in 2 mins
            //  if true, then get a new token and refresh the graphService
            //
            int tokenMins = 2;
            if (token.IsExpired || token.WillExpireIn(tokenMins))
            {
                AADJWTToken newToken = DirectoryDataServiceAuthorizationHelper.GetAuthorizationToken(tenantName, clientId, password);
                token = newToken;
                graphService = new DirectoryDataService(tenantName, token);
            }

            //  get tenant information
            //
            var tenant = graphService.tenantDetails;
            QueryOperationResponse<TenantDetail> responseTenantQuery;
            responseTenantQuery = tenant.Execute() as QueryOperationResponse<TenantDetail>;
            List<TenantDetail> tenantInfo = responseTenantQuery.ToList();
            ViewBag.OtherMessage = "User List from tenant: " + tenantInfo[0].displayName;


            return View(userList);
       }

В папке Представления/Домашние создайте новое представление с именем Users.cshtml и добавьте следующий код:

@model IEnumerable<Microsoft.WindowsAzure.ActiveDirectory.User> 
@{
    ViewBag.Title = "Users";
}

<h1>@ViewBag.Message</h1>
<h2>@ViewBag.OtherMessage</h2>
<table>
    <tr>
        <th>
            DisplayName
        </th>
        <th>
            UPN
        </th>
        <th></th>
    </tr>

@if (User.Identity.IsAuthenticated)
{

  foreach (var user in Model) {
    <tr>
        <td>
         @Html.DisplayFor(modelItem => user.displayName)    
        </td>
        <td>
         @Html.DisplayFor(modelItem => user.userPrincipalName)
        </td>
   </tr>
  }
}
</table>

В папке Представления/Общие откройте файл _Layout.cshtml. В разделе <header> этого файла добавьте в элемент <nav> новый элемент списка: "<li>@Html.ActionLink("Users", "Users", "Home")</li>". Сохраните этот файл.

               <nav>
                        <ul id="menu">
                            <li>@Html.ActionLink("Home", "Index", "Home")</li>
                            <li>@Html.ActionLink("About", "About", "Home")</li>
                            <li>@Html.ActionLink("Contact", "Contact", "Home")</li>
                            <li>@Html.ActionLink("Users", "Users", "Home")</li>
                        </ul>
                    </nav>

Чтобы запустить приложение, нажмите клавишу F5. Войдите с учетными данными пользователя вашего каталога Azure AD, т. е. пользователя с учетной записью организации в домене вашего каталога.

Как можно видеть, интерфейс единого входа остался таким же, как в предыдущем пошаговом руководстве, и требует проверку подлинности с использованием ваших учетных данных Azure AD. Если приложение было опубликовано на веб-сайте, необходимо обновить его с использованием обновлений из этого пошагового руководства. После успешной проверки подлинности пользователя выберите вкладку Пользователи в верхнем меню справа.

Отобразить пользователей

Приложение запустит процесс вызова API Graph, сначала запросив токен из конечной точки проверки подлинности Azure AD. После успешного получения токена приложение будет его использовать в последующем вызове Graph для получения всех пользователей в клиенте. Затем приложение отобразит список пользователей, показывающий их Display Names и User Principal Names.

На этом заканчивается кодирование для учебного приложения, использующего API Graph. В следующем разделе содержатся более подробные сведения и ссылки на расширенные демонстрационные приложения API Graph, демонстрирующие дополнительные операции чтения и записи.

После успешного выполнения единого входа приложение будет запрашивать токен в конечной точке авторизации Azure AD, используя имя клиента (полученное из утверждения идентификатора клиента вошедшего пользователя), идентификатор клиента и пароль для проверки подлинности. Подробное описание метода, поддерживающего получение токена, см. в описании класса DirectoryDataServiceAuthorizationHelper, которое можно найти в файле с тем же именем. Метод GetAuthorization управляет получением токена JSON Web Token (JWT) от конечной точки проверки подлинности Azure AD путем предоставления правильного имени клиента (любого проверенного домена, принадлежащего клиенту), идентификатора клиента и пароля.

Успешный запрос возвращает токен JWT для использования при вызовах API Graph, который вставляется в заголовок Authorization последующих запросов. Вызов API Graph для получения всех пользователей — это HTTP-запрос GET, содержащий следующие заголовки:

Content-Type: application/json; odata=minimalmetadata
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1T….

Рекомендуется, чтобы токен JWT кэшировался приложением для последующих вызовов — в демонстрационном приложении срок действия токена JWT проверяется до выполнения второго вызова API Graph. Если срок действия токена истек, то потребуется получить новый токен. Если вызов API Graph выполняется с токеном, срок действия которого истек, то будет возвращено следующее сообщение об ошибке, а клиенту придется запросить новый токен.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="contoso.com", error="invalid_token", error_description="Your access token has expired. Please renew it before submitting the request.", 

noteПримечание
В настоящее время существует предварительная версия библиотеки проверки подлинности Azure (AAL), управляющей получением токенов проверки подлинности Azure AD. Когда библиотека AAL будет выпущена, мы обновим наши демонстрационные приложения и документацию с учетом использования AAL. Документация по предварительной версии AAL находится здесь.

Дополнительные вызовы REST, включая методы чтения и записи, можно найти в другом демонстрационном приложении MVC4, которое можно загрузить здесь.

Это приложение демонстрирует дополнительную функциональность REST, включая приведенные далее действия.

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

  • Создание и обновление групп.

  • Обновление членства в группе.

  • Разбиение на страницы для обработки большого количества возвращенных объектов.

Добавления сообщества

Показ:
© 2014 Microsoft