Защита ASP.NET Web API с помощью Windows Azure AD и компонентов Microsoft OWIN

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

Индустрия явно склоняется к решению по защите REST API, опирающемуся на стандарт OAuth 2.0. Однако на практике подробного руководства, что следует делать на уровне проектов, не предлагается. Более того, существующие классы и средства в Microsoft .NET Framework для защиты коммуникаций были рассчитаны на работу с определенными типами приложений (веб-приложениями с обратной передачей страниц на сервер). Они не слишком хорошо подходят для Web API и сценариев с множеством клиентов. В итоге защита Web API оказалась довольно кустарной. Она не обязательно плоха, но сильно варьируется от решения к решению и требует слишком много собственного кода.

С выпуском Visual Studio 2013 все это можно считать оставшимся позади. В этом выпуске введены инновационные средства ASP.NET и промежуточное ПО на основе компонентов Microsoft Open Web Interface for .NET (OWIN), которые упрощают защиту вашего Web API. Новые средства и шаблоны ASP.NET позволяют конфигурировать проект Web API на прямое управление аутентификацией через Windows Azure Active Directory (AD), генерируя необходимый код в локальном проекте и в соответствующих записях Windows Azure AD.

В этой статье я покажу, как использовать преимущества этих новых средств Visual Studio 2013 для создания простого Web API, защищаемого Windows Azure AD. Я также продемонстрирую, как создать тестовый клиент, чтобы увидеть этот API в действии. Мы вкратце рассмотрим, что происходит «за кулисами», — это может пригодиться вам в качестве отправной точки, если вы захотите копнуть поглубже и исследовать более сложные аспекты этого сценария.

Удостоверения, пожалуйста

Аутентификация сводится к предложению вызвавшему (при передаче сообщения на сервер) сообщить некий вид удостоверений, которые могут подтвердить его идентификацию или получить его атрибуты. Затем сервер использует эту информацию для авторизации, определяя, следует ли разрешить доступ и на каких условиях.

С ресурсов зачастую снимают большую часть функций аутентификации и передают их провайдеру внешних сервисов, обычно называемому центром или провайдером идентификации. Эти провайдеры берут на себя такие тяжелые задачи, как введение новых пользователей, выдача удостоверений, обработка процедур жизненного цикла (например, восстановление паролей), предоставление UI для аутентификации пользователей, проверка удостоверений по различным протоколам, управление многоступенчатой аутентификацией, обнаружение попыток мошенничества и др.

Без этих функций остается лишь одна задача аутентификации — проверять успешность аутентификации в выбранном вами центре. Обычно это включает проверку маркера защиты — фрагмента данных, выдаваемого центром в случае успешной аутентификации.

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

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

Ресурс В этом качестве будет выступать проект ASP.NET Web API 2, который мне нужно защищать. Вы можете применить требования аутентификации с более высокой детализацией. Например, можно определить подмножество защищенных операций, а другие оставить доступными анонимным вызывающим.

Центр Я сконфигурирую Web API на делегирование задач аутентификации в Windows Azure AD — PaaS-сервис (Platform as a Service), доступный каждому подписчику Windows Azure. Windows Azure AD специально рассчитан на поддержку рабочих нагрузок облачных приложений. Этот сервис хранит информацию о пользователях (атрибуты и удостоверения) и организационной структуре. Вы можете при желании синхронизировать свои данные с вашим Windows Server Active Directory или «обитать» исключительно в облаке без инфраструктуры на предприятии.

Почти все онлайновые сервисы Microsoft (Office 365, Intune и Windows Azure) используют преимущества Windows Azure AD для аутентификации и потребностей в каталоге. Благодаря открытым стандартам и поддержке распространенных протоколов вы можете подключаться к Windows Azure AD практически из любого приложения (Web UX, Web API, «родного» клиента и т. д.) и с любой платформы. Я продемонстрирую, как зарегистрировать свои приложения в Windows Azure AD и задействовать преимущества его конечных точек OAuth 2.0.

Формат маркеров и проверка Спецификация OAuth 2.0 не обязывает использовать какой-либо определенный формат маркеров, но формат JSON Web Token (JWT) (bit.ly/14EhlE8) для REST-сценариев стал стандартом de facto. И Windows Azure AD и компоненты Microsoft OWIN поддерживают формат JWT в OAuth 2.0. Я упоминаю об этом в основном для того, чтобы вы получили некоторое представление о контексте. Механика получения и проверки JWT выполняется промежуточным ПО, а формат маркеров прозрачен для кода приложений.

Клиент Когда ресурс полагается в аутентификации на некий центр, он в конечном счете отделяется от клиента. Как пользователь (и клиентское приложение) получает маркер, становится делом пользователя и этого центра. Это просто превосходно для улучшения возможностей в сопровождении кода, но, если вы захотите увидеть свой API в действии, вам все равно придется настраивать клиент. Вы узнаете, как зарегистрировать «родной» клиент для Web API в Windows Azure AD и как с помощью Windows Azure AD Authentication Library (ADAL) разрешить полнофункциональному клиентскому .NET-приложению аутентифицировать пользователей в Windows Azure AD и получать маркеры для защиты вызовов, адресованных Web API.

На рис. 1 приведены различные элементы решения, которое я собираюсь создать. Не волнуйтесь, если вы пока не понимаете некоторые надписи: я расскажу обо всем в процессе разработки решения.

Рис. 1. Архитектура всего решения

Создание проекта Web API

Чтобы создать проект Web API, используйте новые средства и шаблоны ASP.NET в Visual Studio 2013. Откройте Visual Studio и создайте новый проект ASP.NET Web Application. В диалоге создания проекта выберите шаблон Web API. Щелкните кнопку Change Authentication.

Вам будут предложены стили аутентификации, которые можно выбирать из готового набора для Web API, как показано на рис. 2. Выберите Organizational Accounts — это позволит использовать Windows Azure AD в качестве центра аутентификации. (Подробнее обо всех вариантах см. по ссылке bit.ly/1bhWngl.) Здесь цель — собрать информацию о характеристиках вашего Web API, важных с точки зрения управления идентификациями, и определить, какой экземпляр Windows Azure AD (обычно называемый тенантом) следует сконфигурировать для обработки аутентификации.

Рис. 2. Диалог аутентификации Organizational Accounts

Первый раскрывающийся список определяет, будет ли использовать приложение только один тенант Windows Azure AD (типичный вариант для специализированных бизнес-приложений) или несколько (обычно ожидается от SaaS-приложения). Вы должны выбрать Single Organization, если приложение будет использоваться только сотрудниками вашей компании, или Multiple Organizations, если к приложению должны обращаться сотрудники из множества компаний. Другие варианты в настоящее время доступны только для приложений ASP.NET Web Forms и ASP.NET MVC. На данный момент шаблон проекта Web API поддерживает лишь вариант Single Organization.

Поле Domain идентифицирует, какой тенант Windows Azure AD должен регистрировать ваше приложение. Это обычно каталог предприятия, сопоставленный с вашей подпиской Windows Azure, но подойдет любой каталог, к которому у вас есть доступ с правами администратора (подробности позже). В момент создания у каждого тенанта Windows Azure AD есть один сопоставленный домен третьего уровня в форме ваша_организация.onmicrosoft.com. В принципе, вы будете сопоставлять тенант с одним или более доменами, которыми уже владеете. В примере на рис. 2 я использую собственный домен cloudidentity.net.

Раскрывающийся список Access Level указывает права доступа приложения к каталогу. Значение по умолчанию, Single Sign On, позволяет каталогу выдавать маркеры вашему приложению. Это простое подтверждение того, что приложение зарегистрировано. Центр не выдает маркеры незарегистрированным приложениям даже после успешной аутентификации.

Другие уровни доступа включают Read directory data и Read and write directory data, которые соответственно разрешают приложению запрашивать каталог и модифицировать его содержимое. Это делается через Graph API — программный интерфейс на основе REST, спроектированный так, чтобы приложения с любой платформы со стеком HTTP могли получать делегированный доступ к каталогу. Я оставлю уровень доступа по умолчанию (Single Sign On) и не стану демонстрировать Graph в проекте Web API. Однако это чрезвычайно мощное средство в Windows Azure AD. Подробнее о Graph API см. по ссылке bit.ly/1aByRLS.

Указав домен, сопоставленный с вашим тенантом Windows Azure AD, щелкните OK для генерации проекта. Инструментарий выполнит две задачи.

1. Свяжется с выбранным тенантом Windows Azure AD и добавит запись, описывающую создаваемое приложение.
2. Сгенерирует код для проекта Web API, добавит необходимое защитное промежуточное ПО из компонентов Microsoft OWIN для обработки аутентификации в Windows Azure AD и создаст инициализирующий код для проверки входящих маркеров в соответствии с выбранным тенантом Windows Azure AD.

Первая задача выполняется через Graph API (Visual Studio сама является клиентом Graph API). Чтобы добавить в каталог запись, описывающую создаваемое приложение, нужно получить маркер от каталога, доказывающий, что у вас есть необходимые привилегии для записи в каталог. Вот почему Visual Studio после щелчка OK выводит запрос на аутентификацию (рис. 3).

Рис. 3. Вход по учетной записи

От вас требуется лишь ввести удостоверения администратора каталога. Visual Studio проверит, есть ли у вас необходимые привилегии для выполнения требуемых операций. Visual Studio связывается с Windows Azure AD и создает файлы проекта.

Теперь у вас полностью сконфигурированный Web API, готовый принимать вызовы только от тех, кто указан в тенанте Windows Azure AD. Давайте рассмотрим подробнее.

Перейдите в секцию Solution Explorer, где вы увидите в корне файл Startup.cs. Если вы читали в прошлом номере статью Говарда Диркинга (Howard Dierking) «Getting Started with the Katana Project» (msdn.microsoft.com/magazine/dn451439), то уже знаете, что при запуске приложения из этого файла вызывается определенный класс. В данном случае реализация очень проста:

public partial class Startup
{
  public void Configuration(IAppBuilder app)
  {
    ConfigureAuth(app);
  }
}

Согласно стандарту, вы должны искать метод ConfigureAuth в каком-то другом классе внутри папки App_Start решения. Это файл Startup.Auth.cs. Вот как он выглядит:

public partial class Startup
{
  public void ConfigureAuth(IAppBuilder app)
  {
    app.UseWindowsAzureActiveDirectoryBearerAuthentication(
      new WindowsAzureActiveDirectoryBearerAuthenticationOptions
      {
        Audience = ConfigurationManager.AppSettings["ida:Audience"],
        Tenant = ConfigurationManager.AppSettings["ida:Tenant"]
      });
  }
}

Соглашение по именованию app.Use* предполагает, что метод добавляет реализацию промежуточного ПО в конвейер OWIN. В данном случае добавленное промежуточное ПО анализирует входящий запрос, чтобы узнать, содержит ли HTTP-заголовок Authorization маркер защиты. Именно так вы защищаете запрос согласно спецификации OAuth 2.0 (bit.ly/W4OqA3). Если маркер обнаруживается, он подвергается ряду стандартных проверок: выдан ли маркер уполномоченным центром? Не было ли попытки его модификации в процессе передачи? Не истек ли срок его действия?

Если с маркером все в порядке, промежуточное ПО передает его содержимое участнику системы безопасности (principal), назначает этого участника текущему пользователю и уступает управление следующему элементу в конвейере. Если маркер не проходит проверки, промежуточное ПО возвращает соответствующий код ошибки.

Если маркера нет, промежуточное ПО просто пропускает вызов без создания участника системы безопасности. Логика авторизации, обычно в виде фильтров авторизации, на основе наличия или отсутствия участника (и его содержимого) решает, что делать с запросом — обслужить или отклонить.

Единственный параметр, передаваемый промежуточному ПО, WindowsAzureActiveDirectoryBearerAuthenticationOptions, предоставляет значения для определения правильности маркера. Исходные значения захватываются при создании проекта и хранятся в файле web.config. Значение Audience — это идентификатор, под которым Web API известен Windows Azure AD. Любые маркеры с другим Audience предназначены для другого ресурса и должны быть отклонены.

Свойство Tenant указывает тенант Windows Azure AD, используемый для аутсорсинговой аутентификации. На основе этой информации промежуточное ПО обращается к тенанту и считывает все остальные свойства, определяющие правильность маркера (например, ключ, который следует применять для проверки подписей маркера).

Эти несколько автоматически генерируемых строк кода достаточны для аутентификации вызывающих в Windows Azure AD. Последнее, что нужно сделать в проекте Web API, — дополнить методы, которые вы хотите защищать, атрибутом [Authorize]. Добавьте его ко всем методам в ValuesController. (Для простоты я работаю с контроллерами по умолчанию, предоставляемыми шаблоном.)

Как проверить, что Web API ведет себя ожидаемым образом? Проще всего создать тестовый клиент.

Регистрация «родного» клиента

Точно так же, как Windows Azure AD не будет выдавать маркеры незарегистрированным Web API, так и Windows Azure требует регистрации всех клиентов, запрашивающих маркеры. Чтобы получить маркер для конкретного Web API, зарегистрированному клиенту также необходимо явно предоставить права доступа к этому Web API в Windows Azure AD. Вы должны придерживаться этой схемы на этапе разработки — еще до того, как некий пользователь попытается пройти аутентификацию. Теперь я покажу, как использовать портал Windows Azure для регистрации клиентского приложения и задать разрешения, сопоставленные с доступом к созданному вами Web API.

Начните с перехода на портал Windows Azure. Я аутентифицируюсь под той же учетной записью, что и ранее. Для экономии времени я перейду на портале Windows Azure непосредственно к своему тенанту Windows Azure AD. Вы получаете необходимый URL, добавление домена тенанта к обычному адресу портала, в данном случае это http://manage.windowsazure.com/cloudidentity.net.

Перейти по URL, специфичному для тенанта, быстрее, чем докапываться до поля Sign in with your organizational account со страницы входа. Заметьте: если Windows Azure AD, с которой вы работаете, не включена в администраторы вашей подписки Windows Azure, вам следует входить на портал, используя обычные удостоверения (Microsoft Account или другую организационную сущность).

После загрузки портала выберите из списка доступных сервисов значок Active Directory, щелкните свой каталог, а затем откройте вкладку Applications. Вы увидите список всех созданных вами приложений, в том числе запись для нового проекта Web API. Чтобы создать новую запись, щелкните кнопку Add на панели команд внизу страницы. Появится диалог, как на рис. 4. Технически вы могли бы определить почти любой вид приложения, и это был бы допустимый клиент для вашего Web API. Выберите «родное» клиентское приложение и перейдите на следующий экран.

Рис. 4. Первый этап в мастере Add Application на портале Windows Azure Active Directory

На следующем (и последнем) экране предлагается ввести URI перенаправления для приложения. Этот URI — просто идентификатор, используемый в процессе получения маркера OAuth 2.0, чтобы уведомить вызвавшего о том, что интерактивная часть процесса аутентификации завершена. Остальная часть процесса получения маркера протекает без участия пользователя. В зависимости от платформы, на которой вы разрабатываете «родной» клиент, вы можете столкнуться с различными ограничениями. Например, приложение Windows Store потребовало бы использования схемы протокола ms-app://, если бы пожелали задействовать определенные функции (детали см. по ссылке bit.ly/13KrM6i).

В данном случае я пишу традиционное настольное .NET-приложение, в каковом случае ограничений практически нет. Подойдет любой допустимый URI. Я взял https://cloud­identity.net/myWebAPItestclient, чтобы гарантированно запомнить, для чего предназначен этот клиент.

Как только я заканчиваю ввод записи для приложения, появляется страница, показанная на рис. 5.

Рис. 5. Страница Quick Start

В разделе Update Your Code предоставляется информация, которая понадобится вам, когда вы будете писать клиентское приложение. Она включает параметры для URI перенаправления и клиентский идентификатор, необходимый при формировании запроса на маркер, адресуемого центру аутентификации.

В разделе Configure Access to Web APIs содержится ссылка на область портала, где можно указать API, к которому клиент должен получать доступ. Если вы проследуете по этой ссылке, то окажетесь на странице свойств приложения (рис. 6). Внизу вы увидите раскрывающийся список, позволяющий указать Web API, к которому должен быть доступ у вашего клиента. Обратите внимание на то, что в раскрывающемся списке перечисляются как определенные вами приложения, так и встроенные API, в частности Windows Azure AD Graph API.

Рис. 6. Страница свойств «родного» клиентского приложения на портале Windows Azure Active Directory

Выберите запись для проекта Web API и щелкните Save. Теперь все готово, чтобы клиент получал маркеры для вашего сервиса. Оставьте в браузере эту страницу открытой, так как вам понадобятся некоторые данные, отображаемые на ней.

Создание простого клиентского проекта и тестирование Web API

Теперь вы готовы создать тестовый клиент и проверить в действии аутентифицированный Web API. Вы можете создать клиент почти любого типа на любой платформе, где есть стек HTTP. Чтобы упростить задачу получения и поддержки маркеров, Microsoft предоставляет ADAL, которая облегчает аутентификацию в Active Directory (как в Windows Azure, так и в Windows Server) и не требует быть экспертом в протоколах аутентификации.

Для Microsoft .NET Framework была выпущена библиотека, которая сейчас находится в состоянии предварительной версии для разработчиков приложений Windows Store. (Учебное пособие по реализации этого сценария с приложением Windows Store см. по ссылке bit.ly/17YtYVg.) В конечном счете появятся версии для всех основных клиентских платформ.

Поскольку .NET-версия, в принципе, уже имеется, я использую ее здесь. Помимо синтаксических различий между разными стеками, остальное, о чем я буду рассказывать, применимо к другим платформам и приложениям других типов. Если вам не терпится, помните, что все коммуникации, описываемые в моем сценарии, следуют открытым стандартам и детально документированы. Кодировать логику запроса маркеров довольно легко. Пример с использованием Windows Phone 8 см. по ссылке bit.ly/YatATk.

Проект предназначен для нового WPF-приложения (Windows Presentation Foundation) в рамках того же решения, но вы можете выбрать любой тип проекта, способный интерактивно взаимодействовать с пользователем. После создания проекта добавьте кнопку и обработчик события щелчка, запускающий логику вызова Web API.

ADAL распространяется как NuGet-пакет. Чтобы включить ее в клиентский проект, откройте Package Manager Console из меню Tools в Visual Studio и введите Install-Package Microsoft.IdentityModel.Clients.ActiveDirectory –Version 1.0.0. Теперь добавьте в обработчик события щелчка код с рис. 7.

Рис. 7. Код, добавляемый в обработчик события щелчка

private async void btnCall_Click(object sender, RoutedEventArgs e)
{
  // Получаем маркер
  AuthenticationContext ac = new AuthenticationContext(
    "https://login.windows.net/cloudidentity.net");
  AuthenticationResult ar =
    ac.AcquireToken("https://cloudidentity.net/WindowsAzureADWebAPITest",
    "a4836f83-0f69-48ed-aa2b-88d0aed69652",
    new Uri("https://cloudidentity.net/myWebAPItestclient"));
  // Вызываем Web API
  string authHeader = ar.CreateAuthorizationHeader();
  HttpClient client = new HttpClient();
  HttpRequestMessage request = new HttpRequestMessage(
    HttpMethod.Get, "https://localhost:44353/api/Values");
  request.Headers.TryAddWithoutValidation("Authorization", authHeader);
  HttpResponseMessage response = await client.SendAsync(request);
  string responseString = await response.Content.ReadAsStringAsync();
  MessageBox.Show(responseString);
}

Не волнуйтесь, если код показался вам запутанным. Через минуту все станет ясно.

Первая строка инициализирует новый AuthenticationContext. В коде приложения экземпляр AuthenticationContext представляет центр, с которым вы будете работать. В данном случае центром является мой тенант Windows Azure AD, представленный URI в виде https://login.windows.net/[мой_домен]. Вы должны использовать ту же логику для подключения к каталогу на предприятии, передавая адрес его сервера Active Directory Federation Services (AD FS) (детали см. по ссылке bit.ly/1d553F0).

Во второй строке запрашивает маркер от AuthenticationContext. Создать запрос маркера можно самыми разнообразными способами — в каждом сценарии и типе приложений требуются разные параметры. В данном случае я хочу указать, что ресурс, для которого мне нужен маркер, — мой Web API. Поэтому я передаю идентификатор его записи в Windows Azure AD. Это то самое значение, которое использовалось как параметр audience в проекте Web API. Затем, поскольку маркер запрашивается «родным» клиентом, я должен передать идентификатор клиента и URI перенаправления моего клиента; эти значения берутся со страницы конфигурирования приложения, оставленной мной открытой в браузере.

Вот и все, что нужно для получения маркера. Остальной код помещает маркер в нужный HTTP-заголовок согласно спецификации OAuth 2.0 и выполняет сам вызов.

Теперь опробуйте разок это решение. После модификации решения на запуск сразу всех проектов нажмите F5. Как только поток выполнения дойдет до вызова AcquireToken, на экране появится диалог аутентификации (рис. 8). ADAL берет на себя установление связи с правильной конечной точкой и создает всплывающее диалоговое окно аутентификации на основе данных, предоставляемых сервером; при этом от вас не требуется писать никакого UI-кода.

Рис. 8. Диалог аутентификации, создаваемый Active Directory Authentication Library

Когда я ввожу удостоверения любого допустимого пользователя из тенанта каталога, я получаю маркер. Последующий код представляет маркер для Web API в заголовках запроса. Его проверяет защитное промежуточное ПО. Поскольку все параметры успешно проходят проверку, оно возвращает HTTP-код состояния 200 с результатами.

Просто смеха ради нажмите кнопку еще раз. Вы увидите, что на этот раз вы тут же получаете маркер безо всяких запросов удостоверений. Это связано с тем, что в ADAL имеется встроенный кеш, который отслеживает маркеры. Этот кеш по возможности даже заботится об автоматическом обновлении маркеров с истекшим сроком действия.

Заключение

Я очень поверхностно рассказал о том, чего можно добиться с помощью Web API, компонентов Microsoft OWIN, Windows Azure AD и ADAL. Маркеры, выдаваемые Windows Azure AD, — это не просто доказательства аутентификации. Они несут в себе довольно много информации о пользователе, к которой вы можете легко обращаться из участника системы безопасности для этого пользователя и применять весьма сложную логику авторизации. Процесс аутентификации может простираться далеко за рамки имени и пароля пользователя.

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

Эти средства позволяют расширять функционал облачных Web API. До сих пор вам приходилось выполнять их на предприятии за корпоративным брандмауэром. Теперь вы можете использовать аналогичный код с Windows Server Active Directory.

Конечно, вы также можете публиковать Web API в Windows Azure, не меняя ни одной строки кода, — средства аутентификации по-прежнему будут работать. Единственное, что вам, вероятно, потребуется модифицировать — клиентский проект. Дело в том, что URL сервиса изменится согласно новому размещению приложения. Однако логика получения маркера останется точно такой же, поскольку идентификатор ресурса не обязательно должен быть увязан с физическим адресом этого ресурса.