Поделиться через

Защита API

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

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

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

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

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

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

Вам нужен уникальный идентификатор для вашего API, известный как URI идентификатор приложения, который клиентские приложения, требующие доступа к вашему 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, вы можете предоставить рекомендации, по которым области могут безопасно требовать только согласие пользователя. Однако администраторы клиентов могут настроить клиент таким образом, чтобы все разрешения требовали согласия администратора. Если вы определяете область, требующую согласия администратора, разрешение всегда требует согласия администратора.

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

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

  • Охватывает ли разрешение широкий спектр операций? Например, широкая область применения разрешения — это когда приложение может изменять все в арендаторе или выполнять действия, которые могут быть необратимыми. Широкая область указывает, что требуется согласие администратора, а не согласие пользователя.

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

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

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

При создании приложений, отличных от использования, у вас нет пользователя, которого можно запрашивать для имени пользователя и пароля или многофакторной проверки подлинности (MFA). Если приложения без пользователей (например, рабочих нагрузок, служб и daemons) вызывают API, определите разрешения приложения для 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 ID, как и ID токены. Проверьте подпись после того, как ваше API получит токен из ненадежного источника в сети.

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

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

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

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

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

Обеспечение соблюдения областей и ролей

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

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

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

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

Дальнейшие действия

  • Last updated on