Вызов REST API с помощью пользовательской политики Azure Active Directory B2C

Статья
01/11/2024

Настраиваемая политика Azure Active Directory B2C (Azure AD B2C) позволяет взаимодействовать с логикой приложения, реализуемой за пределами Azure AD B2C. Для этого необходимо выполнить HTTP-вызов к конечной точке. Пользовательские политики Azure AD B2C предоставляют технический профиль RESTful для этой цели. С помощью этой возможности можно реализовать функции, недоступные в пользовательской политике Azure AD B2C.

Вы узнаете, как выполнять следующие задачи:

Создайте и разверните пример приложения Node.js для использования в качестве службы RESTful.
Вызов HTTP к службе RESTful Node.js с помощью технического профиля RESTful.
Обработка или сообщение об ошибке, возвращаемой службой RESTful в настраиваемую политику.

Обзор сценария

При создании ветвления в пути пользователя с помощью пользовательских политик Azure AD B2C пользователи, которые выбирают личную учетную запись , должны предоставить действительный код доступа к приглашению для продолжения. Мы используем статический код доступа, но реальные приложения не работают таким образом. Если служба, которая выдает коды доступа, является внешней для пользовательской политики, необходимо вызвать эту службу и передать входные данные кода доступа пользователю для проверки. Если код доступа действителен, служба возвращает HTTP-ответ 200 OK , а Azure AD B2C выдает маркер JWT. В противном случае служба возвращает HTTP-ответ 409 Conflict , и пользователь должен повторно впустить код доступа.

A flowchart of calling a R E S T A P I.

Необходимые компоненты

Если у вас еще нет клиента Azure AD B2C, создайте его. Он должен быть связан с вашей подпиской Azure.
Зарегистрируйте веб-приложение и включите неявное предоставление разрешения для маркера идентификации. Для URI перенаправления используйте https://jwt.ms.
На компьютере должен быть установлен Node.js .
На компьютере должен быть установлен Visual Studio Code (VS Code ).
Выполните действия, описанные в разделе "Проверка входных данных пользователей" с помощью настраиваемой политики Azure AD B2C. Эта статья является частью руководства по созданию и запуску собственных пользовательских политик.

Примечание.

Эта статья является частью серии руководств по созданию и запуску собственных пользовательских политик в Azure Active Directory B2C. Мы рекомендуем начать эту серию из первой статьи.

Шаг 1. Создание и развертывание приложения Node.js

Необходимо развернуть приложение, которое служит внешним приложением. Затем настраиваемая политика выполняет вызов HTTP к этому приложению.

Шаг 1.1. Создание приложения Node.js

Создайте папку для размещения приложения Node, например access-code-app.
В окне терминала перейдите в папку приложения Node, например cd access-code-app, и выполните команду npm init -y. Эта команда создает файл по умолчанию package.json для проекта Node.js.
В окне терминале выполните команду npm install express body-parser. Эта команда устанавливает платформу Express и пакет синтаксического анализа текста.
Создайте index.js файл в проекте.

В VS Code откройте index.js файл и добавьте следующий код:

    const express = require('express');
    let bodyParser = require('body-parser')
    //Create an express instance
    const app = express();

    app.use( bodyParser.json() );       // to support JSON-encoded bodies
    app.use(bodyParser.urlencoded({     // to support URL-encoded bodies
      extended: true
    }));


    app.post('/validate-accesscode', (req, res) => {
        let accessCode = '88888';
        if(accessCode == req.body.accessCode){
            res.status(200).send();
        }else{
            let errorResponse = {
                "version" :"1.0",
                "status" : 409,
                "code" : "errorCode",
                "requestId": "requestId",
                "userMessage" : "The access code you entered is incorrect. Please try again.",
                "developerMessage" : `The provided code ${req.body.accessCode} does not match the expected code for user.`,
                "moreInfo" :"https://docs.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
            };
            res.status(409).send(errorResponse);                
        }
    });

    app.listen(80, () => {
        console.log(`Access code service listening on port !` + 80);
    });

Вы можете наблюдать, что при отправке неправильного кода доступа пользователь может вернуть ошибку непосредственно из REST API. Пользовательские политики позволяют возвращать сообщение об ошибке HTTP 4xx, например 400 (неправильный запрос) или код состояния ответа 409 (конфликт) с текстом JSON ответа в формате JSON, как показано в errorResponse переменной. Источник accessCode в приложении можно считывать из базы данных. Дополнительные сведения о возврате сообщения об ошибке проверки.

Чтобы проверить работу приложения должным образом, выполните следующие действия.
1. В терминале node index.js выполните команду, чтобы запустить сервер приложений.
2. Чтобы выполнить запрос POST, аналогичный приведенному в этом примере, можно использовать HTTP-клиент, например Microsoft PowerShell или Postman:
```
    POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code
```
Замените user-code-code ввод кода доступа пользователем, например 54321. Если вы используете PowerShell, выполните следующий сценарий.
```
    $accessCode="54321"
    $endpoint="http://localhost/validate-accesscode"
    $body=$accessCode
    $response=Invoke-RestMethod -Method Post -Uri $endpoint -Body $body
    echo $response
```
Если вы используете неправильный код доступа, ответ выглядит примерно так, как показано в следующем фрагменте КОДА JSON:
```
    {
        "version": "1.0",
        "status": 409,
        "code": "errorCode",
        "requestId": "requestId",
        "userMessage": "The access code you entered is incorrect. Please try again.",
        "developerMessage": "The provided code 54321 does not match the expected code for user.",
        "moreInfo": "https://docs.microsoft.com/en-us/azure/active-directory-b2c/string-transformations"
    }
```

На этом этапе вы готовы развернуть приложение Node.js.

Шаг 1.2. Развертывание приложения Node.js в службе приложение Azure

Для доступа к приложению Node.js настраиваемая политика должна быть доступной, поэтому ее необходимо развернуть. В этой статье вы развернете приложение с помощью службы приложение Azure, но используете альтернативный подход к размещению.

Выполните действия, описанные в статье "Развертывание приложения в Azure " для развертывания приложения Node.js в Azure. Для имени приложения используйте описательное имя, напримерcustompolicyapi. Следовательно:

URL-адрес приложения выглядит примерно так:https://custompolicyapi.azurewebsites.net
Конечная точка службы выглядит примерно так:https://custompolicyapi.azurewebsites.net/validate-accesscode

Вы можете протестировать приложение, которое вы развернули, с помощью HTTP-клиента, например Microsoft PowerShell или Postman. На этот раз используйте https://custompolicyapi.azurewebsites.net/validate-accesscode URL-адрес в качестве конечной точки.

Шаг 2. Вызов REST API

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

Шаг 2.1. Определение технического профиля RESTful

ContosoCustomPolicy.XML В файле найдите ClaimsProviders раздел и определите новый технический профиль RESTful с помощью следующего кода:

    <!--<ClaimsProviders>-->
        <ClaimsProvider>
            <DisplayName>HTTP Request Technical Profiles</DisplayName>
            <TechnicalProfiles>
                <TechnicalProfile Id="ValidateAccessCodeViaHttp">
                    <DisplayName>Check that the user has entered a valid access code by using Claims Transformations</DisplayName>
                    <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
                    <Metadata>
                        <Item Key="ServiceUrl">https://custompolicyapi.azurewebsites.net/validate-accesscode</Item>
                        <Item Key="SendClaimsIn">Body</Item>
                        <Item Key="AuthenticationType">None</Item>
                        <Item Key="AllowInsecureAuthInProduction">true</Item>
                    </Metadata>
                    <InputClaims>
                        <InputClaim ClaimTypeReferenceId="accessCode" PartnerClaimType="accessCode" />
                    </InputClaims>
                </TechnicalProfile>
            </TechnicalProfiles>
        </ClaimsProvider>
    <!--</ClaimsProviders>-->

В протоколе можно увидеть, что мы настроим технический профиль для использования RestfulProvider. Вы также можете просмотреть следующие сведения в разделе метаданных:

Представляет ServiceUrl конечную точку API. Его значение равно https://custompolicyapi.azurewebsites.net/validate-accesscode. Если вы развернули приложение Node.js с помощью альтернативного метода, обязательно обновите значение конечной точки.
SendClaimsIn указывает, как входные утверждения отправляются поставщику утверждений RESTful. Возможные значения: Body (default), , UrlFormHeaderили QueryString. При использовании Body, например в этой статье, вызывается команда POST HTTP, а данные, отправляемые в API, если они отформатированы как ключ, пары значений в тексте запроса. Узнайте , как вызвать команду GET HTTP и передать данные в виде строки запроса.
AuthenticationType указывает тип проверки подлинности, выполняемой поставщиком утверждений RESTful. Наш поставщик утверждений RESTful вызывает незащищенную конечную точку, поэтому мы задали значение AuthenticationTypeNone. При установке типа Bearerпроверки подлинности необходимо добавить элемент CryptographicKeys , который указывает хранилище для маркера доступа. Дополнительные сведения о типах проверки подлинности, поддерживаемых поставщиком утверждений RESTful.
Атрибут PartnerClaimType в описании InputClaim способа получения данных в API.

Шаг 2.2. Обновление технического профиля проверки

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

Найдите технический профиль AccessCodeInputCollector и обновите элемент ReferenceId элемента ValidationTechnicalProfile до ValidateAccessCodeViaHttp:

От:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

на:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

На этом этапе технический профиль с IdCheckAccessCodeViaClaimsTransformationChecker не нужен и может быть удален.

Шаг 3. Отправка пользовательского файла политики

Убедитесь, что приложение Node.js запущено, а затем выполните действия, описанные в разделе "Отправка пользовательского файла политики" для отправки файла политики. Если вы отправляете файл с тем же именем, что и на портале, убедитесь, что вы перезаписываете настраиваемую политику, если она уже существует.

Шаг 4. Проверка настраиваемой политики

Выполните действия, описанные в разделе "Тестирование настраиваемой политики", чтобы протестировать настраиваемую политику :

Для типа учетной записи выберите личную учетную запись
Введите остальные сведения по мере необходимости и нажмите кнопку "Продолжить". Появится новый экран.
Для кода доступа введите 88888, а затем нажмите кнопку "Продолжить". После завершения выполнения политики вы будете перенаправлены https://jwt.msв , и вы увидите декодированные токены JWT. Если повторить процедуру и ввести другой код доступа, отличный от 88888, появится ошибка, введенный вами код доступа является неверным. Повторите попытку.

Шаг 5. Включение режима отладки

В разработке может потребоваться просмотреть подробные ошибки, отправленные API, например developerMessage и moreInfo. В этом случае необходимо включить режим отладки в техническом поставщике RESTful.

Найдите технический поставщик ValidateAccessCodeViaHttp и добавьте следующий элемент в технические поставщикиmetadata:
```
    <Item Key="DebugMode">true</Item>
```
Сохраните изменения и отправьте файл политики.
Проверьте настраиваемую политику. Убедитесь, что вы используете неправильные входные данные для кода доступа. На снимке экрана отображается ошибка, аналогичная приведенной на следующем снимке экрана:

Обработка полезных данных JSON сложного запроса

Если вызову REST API требуется отправить сложную полезные данные JSON, можно создать полезные данные с помощью преобразований утверждений GenerateJson JSON. После создания полезных данных можно использовать ClaimUsedForRequestPayload параметр метаданных для имени утверждения, содержащего полезные данные JSON.

Например, используйте следующее преобразование утверждений для создания полезных данных JSON:

    <ClaimsTransformation Id="GenerateRequestBodyClaimsTransformation" TransformationMethod="GenerateJson">
        <InputClaims>
            <InputClaim ClaimTypeReferenceId="email" TransformationClaimType="customerEntity.email" />
            <InputClaim ClaimTypeReferenceId="objectId" TransformationClaimType="customerEntity.userObjectId" />
            <InputClaim ClaimTypeReferenceId="givenName" TransformationClaimType="customerEntity.firstName" />
            <InputClaim ClaimTypeReferenceId="surname" TransformationClaimType="customerEntity.lastName" />
            <InputClaim ClaimTypeReferenceId="accessCode" TransformationClaimType="customerEntity.accessCode" />
        </InputClaims>
        <InputParameters>
            <InputParameter Id="customerEntity.role.name" DataType="string" Value="Administrator" />
            <InputParameter Id="customerEntity.role.id" DataType="long" Value="1" />
        </InputParameters>
        <OutputClaims>
            <OutputClaim ClaimTypeReferenceId="requestBodyPayload" TransformationClaimType="outputClaim" />
        </OutputClaims>
    </ClaimsTransformation>

ClaimsTransformation создает следующий объект JSON:

{
   "customerEntity":{
      "email":"john.s@contoso.com",
      "userObjectId":"01234567-89ab-cdef-0123-456789abcdef",
      "firstName":"John",
      "lastName":"Smith",
      "accessCode":"88888",
      "role":{
         "name":"Administrator",
         "id": 1
      }
   }
}

Затем обновите метаданные, InputClaimsTransformations и InputClaims технического поставщика RESTful, как показано ниже:

    <Metadata>
        <Item Key="ClaimUsedForRequestPayload">requestBodyPayload</Item>
        <!--Other Metadata items -->
    </Metadata>
    
    <!--Execute your InputClaimsTransformations to generate your request Payload-->
    <InputClaimsTransformations>
        <InputClaimsTransformation ReferenceId="GenerateRequestBodyClaimsTransformation" />
    </InputClaimsTransformations>
    
    <InputClaims>
        <InputClaim ClaimTypeReferenceId="requestBodyPayload" />
    </InputClaims>

Получение данных из REST API

Если REST API возвращает данные, которые необходимо включить в политику в качестве утверждений, можно получить, указав утверждения в OutputClaims элементе технического профиля RESTful. Если имя утверждения, определенного в политике, отличается от имени, определенного в REST API, необходимо сопоставить эти имена с помощью атрибута PartnerClaimType .

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

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

Далее вы узнаете:

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