Проблемы утверждений, запросы утверждений и возможности клиента

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

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

Приложения, использующие расширенные функции безопасности, такие как Непрерывная оценка доступа (CAE) и контекст проверки подлинности условного доступа, должны быть готовы обрабатывать требования утверждений.

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

Формат заголовка требования утверждений

Требование утверждений — это директива в виде заголовка www-authenticate, возвращаемая API-интерфейсом, когда предоставленный ему маркер доступа не является авторизованным, а вместо него требуется новый маркер доступа с необходимыми возможностями. Требование утверждений состоит из нескольких элементов: код состояния HTTP ответа и заголовок www-authenticate, который сам состоит из нескольких элементов и должен содержать директиву утверждений.

Приведем пример:

HTTP 401; Unauthorized

www-authenticate =Bearer realm="", authorization_uri="https://login.microsoftonline.com/common/oauth2/authorize", error="insufficient_claims", claims="eyJhY2Nlc3NfdG9rZW4iOnsiYWNycyI6eyJlc3NlbnRpYWwiOnRydWUsInZhbHVlIjoiY3AxIn19fQ=="

Код состояния HTTP: должен быть 401 Unauthorized.

Заголовок ответа www-authenticate, содержащий указанные ниже элементы.

Ответ 401 может содержать более одного заголовка www-authenticate. Все поля в предыдущей таблице должны содержаться в одном заголовке www-authenticate. Заголовок www-authenticate, который содержит требование утверждений, может содержать другие поля. Поля в заголовке не упорядочены. Согласно стандарту RFC 7235, имя каждого параметра должно встречаться только один раз в каждом требовании схемы проверки подлинности.

Запрос утверждений

Если приложение получает требование утверждений, это означает, что прежний маркер доступа больше не считается допустимым. В этом сценарии приложение должно удалить маркер из локального кэша или сеанса пользователя. Затем он должен перенаправить вошедшего пользователя обратно в идентификатор Microsoft Entra, чтобы получить новый маркер с помощью потока кода авторизации OAuth 2.0 с параметром утверждений , который будет соответствовать другим требованиям, которые не были выполнены.

Приведем пример:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22acrs%22%3A%7B%22essential%22%3Atrue%2C%22value%22%3A%22c1%22%7D%7D%7D

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

Для заполнения параметра claims разработчик должен:

1. Декодировать полученную ранее строку Base64.
2. Закодировать строку в URL-адрес и снова добавить ее в параметр claims.

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

Возможности клиента

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

Некоторые популярные приложения, такие как Microsoft Graph, отправляют требования утверждений только в том случае, если вызывающее клиентское приложение объявляет с помощью возможностей клиента, что способно обрабатывать их.

Чтобы избежать дополнительного трафика или влияния на взаимодействие с пользователем, идентификатор Microsoft Entra не предполагает, что ваше приложение может обрабатывать утверждения, оспариваемые, если вы явно не согласитесь. Приложение не получит вызовы утверждений (и не сможет использовать связанные функции, такие как маркеры CAE), если только он не объявляет, что он готов обрабатывать их с помощью функции cp1.

Взаимодействие возможностей клиента с идентификатором Microsoft Entra

В следующем примере параметра утверждений показано, как клиентское приложение взаимодействует с его возможностями с идентификатором Microsoft Entra в потоке кода авторизации OAuth 2.0.

Claims: {"access_token":{"xms_cc":{"values":["cp1"]}}}

_clientApp = PublicClientApplicationBuilder.Create(App.ClientId)
 .WithDefaultRedirectUri()
 .WithAuthority(authority)
 .WithClientCapabilities(new [] {"cp1"})
 .Build();

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": 'Enter_the_Application_Id_Here' 
    "ClientCapabilities": [ "cp1" ],
    // remaining settings...
},

const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here', 
        clientCapabilities: ["CP1"]
        // remaining settings...
    }
}

const msalInstance = new msal.PublicClientApplication(msalConfig);

См. следующий фрагмент кода, чтобы просмотреть пример запроса к идентификатору Microsoft Entra:

GET https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/oauth2/v2.0/authorize
?client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&redirect_uri=https%3A%2F%contoso.com%3A44321%2Fsignin-oidc
&response_type=code
&scope=openid%20profile%20offline_access%20user.read%20Sites.Read.All
&response_mode=form_post
&login_hint=kalyan%ccontoso.onmicrosoft.com
&domain_hint=organizations
&claims=%7B%22access_token%22%3A%7B%22xms_cc%22%3A%7B%22values%22%3A%5B%22cp1%22%5D%7D%7D%7D

Если у вас уже есть полезные данные для параметра claims, вы можете добавить ее в существующий набор.

Например, если у вас уже есть следующий ответ из контекста проверки подлинности доступа к условию;

{"access_token":{"acrs":{"essential":true,"value":"c25"}}}

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

{"access_token":{"xms_cc":{"values":["cp1"]},"acrs":{"essential":true,"value":"c25"}}}

Получение утверждения xms_cc в маркере доступа

Чтобы понять, может ли клиентское приложение обрабатывать требования утверждений, реализация API должна запросить необязательное утверждение xms_cc в манифесте приложения.

Утверждение xms_cc со значением "cp1" в маркере доступа — полномочный способ понять, что клиентское приложение способно обрабатывать требования утверждений. xms_cc является необязательным утверждением, которое не всегда будет выдано в маркере доступа, даже если клиент отправляет запрос утверждений с "xms_cc". Чтобы в маркер доступа включалось утверждение xms_cc, приложение-ресурс (т. е. реализация API) должно запрашивать xms_cc как необязательное утверждение в манифесте приложения. При запросе в качестве необязательного утверждения xms_cc добавляется в маркер доступа, только если клиентское приложение отправляет xms_cc в запросе утверждений. Значение запроса xms_cc утверждения включается в качестве значения утверждения xms_cc в маркере доступа, если это известное значение. Единственным известным значением является cp1.

Значения не учитывает регистр и не упорядочены. Если в запросе утверждений xms_cc указано более одного значения, эти значения будут многозначными коллекциями в качестве значения утверждения xms_cc.

Выполните следующий запрос в качестве примера:

{ "access_token": { "xms_cc":{"values":["cp1","foo", "bar"] } }}

Это приводит к утверждению следующего фрагмента в маркере доступа, если cp1, foo и bar являются известными возможностями.

"xms_cc": ["cp1", "foo", "bar"]

После запроса xms_cc необязательного утверждения манифест приложения изменится следующим образом:

"optionalClaims":
{
    "accessToken": [
    {
        "additionalProperties": [],
        "essential": false,
        "name": "xms_cc",
        "source": null
    }],
    "idToken": [],
    "saml2Token": []
}

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

Claim ccClaim = context.User.FindAll(clientCapabilitiesClaim).FirstOrDefault(x => x.Type == "xms_cc");
if (ccClaim != null && ccClaim.Value == "cp1")
{
    // Return formatted claims challenge as this client understands this
}
else
{
    // Throw generic exception
    throw new UnauthorizedAccessException("The caller does not meet the authentication bar to carry our this operation. The service cannot allow this operation");
}

const checkIsClientCapableOfClaimsChallenge = (req, res, next) => {
    // req.authInfo contains the decoded access token payload
    if (req.authInfo['xms_cc'] && req.authInfo['xms_cc'].includes('CP1')) {
          // Return formatted claims challenge as this client understands this
    } else {
          return res.status(403).json({ error: 'Client is not capable' });
    }
}

Примеры кода

• Включение одностраничного приложения Angular для входа пользователей и вызова Microsoft Graph
• Включение одностраничного приложения React для входа пользователей и вызова Microsoft Graph
• Включение веб-приложения ASP.NET Core для входа пользователей и вызова Microsoft Graph

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

• Поток кода авторизации OAuth 2.0 и платформа удостоверений Майкрософт
• Как использовать API с поддержкой Непрерывной оценки доступа в приложениях
• Точный условный доступ для конфиденциальных данных и действий