Защита API

  • Статья

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

Регистрация защищенного API

Чтобы защитить API с помощью идентификатора Microsoft Entra (Идентификатор Microsoft Entra), сначала зарегистрируйте API, после чего вы можете управлять зарегистрированными API. В идентификаторе Microsoft Entra API — это приложение с определенными параметрами регистрации приложений, которые определяют его как ресурс или API, к которому может быть авторизовано другое приложение для доступа. В Центре администрирования Microsoft Entra разработчик удостоверений Майкрософт Регистрация приложений — это API, которые находятся в клиенте в качестве бизнес-API или служб от поставщиков SaaS, имеющих API, защищенные идентификатором Microsoft Entra.

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

Как правило, API не выполняет проверку подлинности или напрямую запрашивает авторизацию. API проверяет маркер, представленный вызывающим приложением. Интерфейсы API не будут иметь интерактивных входов, поэтому вам не нужно регистрировать такие параметры, как URI перенаправления или тип приложения. API получают свои маркеры из приложений, вызывающих эти API, а не путем взаимодействия с идентификатором Microsoft Entra. Для веб-API используйте маркеры доступа OAuth2 для авторизации. Веб-API проверяют маркеры носителя для авторизации вызывающих пользователей. Не принимаю маркеры идентификаторов в качестве подтверждения разрешения.

По умолчанию идентификатор Microsoft Entra добавляет User.Read разрешения API для регистрации любого нового приложения. Это разрешение будет удалено для большинства веб-API. Идентификатор Microsoft Entra id требует разрешений API, только если API вызывает другой API. Если API не вызывает другой API, удалите User.Read разрешение при регистрации API.

Вам потребуется уникальный идентификатор API, известный как URI идентификатора приложения, который клиентские приложения, которым требуется доступ к API, будут запрашивать разрешение на вызов API. URI идентификатора приложения должен быть уникальным для всех клиентов Microsoft Entra. Вы можете использовать api://<clientId> (предложение по умолчанию на портале), где <clientId> находится идентификатор приложения зарегистрированного API.

Чтобы предоставить разработчикам, которые обращаются к API с более понятным именем, вы можете использовать адрес API в качестве URI идентификатора приложения. Например, можно использовать https://API.yourdomain.com , где yourdomain.com должен быть настроенный домен издателя в клиенте Microsoft Entra. Корпорация Майкрософт проверяет, что у вас есть владение доменом, чтобы его можно было использовать в качестве уникального идентификатора api. У вас нет кода на этом адресе. API может быть где угодно, но рекомендуется использовать HTTPS-адрес API в качестве URI идентификатора приложения.

Определение делегированных разрешений с минимальными привилегиями

Если API будет вызываться приложениями, у которых есть пользователи, необходимо определить по крайней мере одно делегированное разрешение (см. раздел "Добавление область на регистрацию приложения" для предоставления API).

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

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

Объявите наименьшие привилегии область, чтобы ваши приложения не были уязвимы для компрометации или использования для выполнения задачи, которую вы никогда не намеревались. Определите несколько область в разрешениях API. Например, отдельные область от чтения и обновления данных и рассмотрите возможность предоставления разрешений только для чтения. "Доступ на запись" включает привилегии для операций создания, обновления и удаления. Клиент никогда не должен требовать доступ для записи, если он выполняет только чтение данных.

При работе API с конфиденциальными данными рассмотрите разрешения на доступ "стандартный" и "полный". Ограничьте конфиденциальные свойства, чтобы стандартное разрешение не разрешалось (например, Resource.Read). Затем реализуйте разрешение на полный доступ (например, Resource.ReadFull), которое возвращает свойства и конфиденциальную информацию.

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

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

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

При принятии решения о согласии пользователя или администратора у вас есть два основных вопроса:

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

  2. Имеет ли широкий область диапазон операций, стоящих за разрешением. Например, широкая область заключается в том, что разрешение позволяет приложению изменять все в клиенте или делать что-то, что может быть необратимым. Широкая область указывает, что требуется согласие администратора, а не согласие пользователя.

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

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

Определение разрешений приложения

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

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

Рабочие нагрузки проходят проверку подлинности с помощью учетных данных клиента и запрашивают маркер с помощью .default область, как показано в следующем примере кода.

// With client credentials flows the scopes is ALWAYS of the shape "resource/.default", as the 
// application permissions need to be set statically (in the portal or by PowerShell), 
// and then granted by a tenant administrator
string[] scopes = new string[] { "https://kkaad.onmicrosoft.com/webapi/.default" };
 
AuthenticationResult result = null;
try
{
  result = await app.AcquireTokenForClient(scopes)
    .ExecuteAsync();
  Console.WriteLine("Token acquired \n");
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
  // Invalid scope. The scope has to be of the form "https://resourceurl/.default"
  // Mitigation: change the scope to be as expected
  Console.WriteLine("Scope provided is not supported");
}

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

Принудительное применение доступа

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

Проверка маркеров

После получения маркера API он должен проверить маркер. Проверка гарантирует, что маркер поступает от правильного издателя как неуправляемый и неизмененные. Проверьте сигнатуру, так как вы не получаете маркер непосредственно из идентификатора Microsoft Entra, как и маркеры идентификаторов. Проверьте подпись после получения маркера из ненадежного источника в сети.

Так как существуют известные уязвимости при проверке подписи веб-токена JSON, используйте хорошо поддерживаемую и установленную стандартную библиотеку проверки маркеров. Библиотеки проверки подлинности (например , Microsoft.Identity.Web или Passport, если вы создаете узел) используют соответствующие шаги и устраняют известные уязвимости.

При необходимости расширьте проверку маркера. Используйте утверждение идентификатора клиента (tid) для ограничения клиентов, в которых API может получить маркер. azp Используйте утверждения appid для фильтрации приложений, которые могут вызывать API. Используйте утверждение идентификатора объекта (oid) для дальнейшего уменьшения доступа к отдельным пользователям.

Управление обновлением метаданных

Всегда убедитесь, что библиотека проверки маркеров эффективно управляет необходимыми метаданными. В этом случае метаданные — это открытые ключи, пара закрытых ключей, которую корпорация Майкрософт использует для подписи токенов Microsoft Entra. Когда библиотеки проверяют эти маркеры, они получат наш опубликованный список открытых ключей подписывания из известного интернет-адреса. Убедитесь, что среда размещения имеет подходящее время для получения этих ключей.

Например, старые библиотеки иногда жестко кодируются для обновления этих открытых ключей подписывания каждые 24 часа. Учитывайте, когда идентификатор Microsoft Entra должен быстро повернуть эти ключи, и ключи, скачанные вами, не включали новые поворачиваемые ключи. API может находиться в автономном режиме в течение дня, пока он ожидает цикла обновления метаданных. Ознакомьтесь с рекомендациями по обновлению определенных метаданных, чтобы убедиться, что вы правильно получаете метаданные. Если вы используете библиотеку, убедитесь, что она обрабатывает метаданные в разумные сроки.

Применение область и ролей

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

Для делегированных маркеров разрешений проверьте утверждение область (scp) API, чтобы узнать, что у приложения есть согласие. Проверьте идентификатор объекта () или ключ субъекта (oidsub) утверждения, чтобы увидеть пользователя, от имени которого работает приложение.

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

После проверки маркера и область API и обработки идентификатора объекта (), ключа субъекта (oidsub) и утверждений ролей API может вернуть результаты.

Следующие шаги