Partilhar via

Chamar uma API REST usando a política personalizada do Azure Ative Directory B2C

  • Artigo

A política personalizada do Azure Ative Directory B2C (Azure AD B2C) permite que você interaja com a lógica do aplicativo que você implementa fora do Azure AD B2C. Para fazer isso, você faz uma chamada HTTP para um ponto de extremidade. As políticas personalizadas do Azure AD B2C fornecem um perfil técnico RESTful para essa finalidade. Usando esse recurso, você pode implementar recursos que não estão disponíveis na política personalizada do Azure AD B2C.

Neste artigo, vai aprender a:

  • Crie e implante um aplicativo Node.js de exemplo para uso como um serviço RESTful.

  • Faça uma chamada HTTP para o serviço RESTful .js nó usando o perfil técnico RESTful.

  • Manipule ou relate um erro que um serviço RESTful retorna à sua política personalizada.

Descrição geral do cenário

Em Criar ramificação na jornada do usuário usando políticas personalizadas do Azure AD B2C, os usuários que selecionam Conta Pessoal precisam fornecer um código de acesso de convite válido para continuar. Utilizamos um código de acesso estático, mas as aplicações do mundo real não funcionam desta forma. Se o serviço que emite os códigos de acesso for externo à sua política personalizada, você deverá fazer uma chamada para esse serviço e passar o código de acesso inserido pelo usuário para validação. Se o código de acesso for válido, o serviço retornará uma resposta HTTP 200 OK e o Azure AD B2C emitirá o token JWT. Caso contrário, o serviço retorna uma resposta HTTP 409 Conflict e o usuário deve inserir novamente um código de acesso.

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

Pré-requisitos

Nota

Este artigo faz parte da série de guias de instruções Criar e executar suas próprias políticas personalizadas no Azure Ative Directory B2C. Recomendamos que comece esta série desde o primeiro artigo.

Etapa 1 - Criar e implantar um aplicativo .js nó

Você precisa implantar um aplicativo, que serve como seu aplicativo externo. Em seguida, sua política personalizada faz uma chamada HTTP para este aplicativo.

Etapa 1.1 - Criar o aplicativo Node.js

  1. Crie uma pasta para hospedar seu aplicativo de nó, como access-code-app.

  2. No terminal, altere o diretório para a pasta do aplicativo Node, como cd access-code-app, e execute npm init -y. Este comando cria um arquivo padrão package.json para seu projeto Node.js.

  3. No terminal, execute npm install express body-parser. Este comando instala a estrutura Express e o pacote body-parser .

  4. No seu projeto, crie index.js um arquivo.

  5. No VS Code, abra o ficheiro e, em seguida, adicione o index.js seguinte código:

        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);
    });

    Você pode observar que quando um usuário envia um código de acesso errado, você pode retornar um erro diretamente da API REST. As políticas personalizadas permitem que você retorne uma mensagem de erro HTTP 4xx, como o código de status de resposta 400 (solicitação incorreta) ou 409 (Conflito) com um corpo JSON de resposta formatado conforme mostrado na errorResponse variável. A fonte do accessCode no aplicativo pode ser lida a partir de um banco de dados. Saiba mais sobre como retornar mensagem de erro de validação.

  6. Para testar que o aplicativo funciona conforme o esperado, use as seguintes etapas:

    1. No terminal, execute o comando para iniciar o servidor de node index.js aplicativos.
    2. Para fazer uma solicitação POST semelhante à mostrada neste exemplo, você pode usar um cliente HTTP, como o Microsoft PowerShell ou o Postman:
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    Substitua user-code-code por um código de acesso inserido pelo usuário, como 54321. Se você estiver usando o PowerShell, execute o script a seguir.

        $accessCode="54321"
    $endpoint="http://localhost/validate-accesscode"
    $body=$accessCode
    $response=Invoke-RestMethod -Method Post -Uri $endpoint -Body $body
    echo $response

    Se você usar um código de acesso incorreto, a resposta será semelhante ao seguinte trecho 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"
    }

Neste ponto, você está pronto para implantar seu aplicativo Node.js.

Etapa 1.2 - Implantar o aplicativo Node.js no Serviço de Aplicativo do Azure

Para que sua política personalizada alcance seu aplicativo Node.js, ela precisa estar acessível, portanto, você precisa implantá-la. Neste artigo, você implanta o aplicativo usando o Serviço de Aplicativo do Azure, mas usa uma abordagem de hospedagem alternativa.

Siga as etapas em Implantar seu aplicativo no Azure para implantar seu aplicativo .js nó no Azure . Para o Nome do aplicativo, use um nome descritivo como custompolicyapi. Assim:

  • O URL do aplicativo é semelhante ao https://custompolicyapi.azurewebsites.net.

  • O ponto de extremidade de serviço é semelhante ao https://custompolicyapi.azurewebsites.net/validate-accesscode.

Você pode testar o aplicativo implantado usando um cliente HTTP, como o Microsoft PowerShell ou o Postman. Desta vez, use https://custompolicyapi.azurewebsites.net/validate-accesscode URL como o ponto de extremidade.

Etapa 2 - Chamar a API REST

Agora que seu aplicativo está em execução, você precisa fazer uma chamada HTTP a partir de sua política personalizada. A política personalizada do Azure AD B2C fornece um perfil técnico RESTful que você usa para chamar um serviço externo.

Etapa 2.1 - Definir um perfil técnico RESTful

No arquivo ContosoCustomPolicy.XML , localize a ClaimsProviders seção e defina um novo perfil técnico RESTful usando o seguinte código:

    <!--<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>-->

A partir do protocolo, você pode observar que configuramos o Perfil Técnico para usar o RestfulProvider. Você também pode observar as seguintes informações na seção de metadados:

  • O ServiceUrl representa o ponto de extremidade da API. O seu valor é https://custompolicyapi.azurewebsites.net/validate-accesscode. Se você implantou seu aplicativo Node.js usando um método alternativo, certifique-se de atualizar o valor do ponto de extremidade.

  • SendClaimsIn especifica como as declarações de entrada são enviadas para o provedor de declarações RESTful. Valores possíveis: Body (default), , FormHeader, Url ou QueryString. Ao usar Body, como neste artigo, você invoca o verbo HTTP POST e os dados enviados para a API, se formatados como chave, equivalem pares de valores no corpo da solicitação. Saiba como invocar o verbo HTTP GET e passar dados como cadeia de caracteres de consulta.

  • AuthenticationType especifica o tipo de autenticação que o provedor de declarações RESTful executa. Nosso provedor de declarações RESTful chama um ponto de extremidade desprotegido, por isso definimos nosso AuthenticationType como Nenhum. Se você definir o tipo de autenticação como Bearer, precisará adicionar um elemento CryptographicKeys , que especifica o armazenamento para seu token de acesso. Saiba mais sobre os tipos de autenticação suportados pelo provedor de declarações RESTful.

  • O atributo PartnerClaimType no InputClaim especifica como você recebe seus dados na API.

Etapa 2.2 - Atualizar perfil técnico de validação

Em Criar ramificação na jornada do usuário usando a política personalizada do Azure AD B2C, você validou o accessCode usando uma transformação de declarações. Neste artigo, você valida o accessCode fazendo uma chamada HTTP para um serviço externo. Portanto, você precisará atualizar sua política personalizada para refletir a nova abordagem.

Localize o perfil técnico AccessCodeInputCollector e atualize o ReferenceId do elemento ValidationTechnicalProfile para ValidateAccessCodeViaHttp:

De:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

para:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Neste ponto, o perfil técnico com IdCheckAccessCodeViaClaimsTransformationChecker não é necessário e pode ser removido.

Etapa 3 - Carregar arquivo de política personalizado

Verifique se o aplicativo Node.js está em execução e siga as etapas em Carregar arquivo de política personalizado para carregar seu arquivo de política. Se estiver a carregar um ficheiro com o mesmo nome que o que já se encontra no portal, certifique-se de que seleciona Substituir a política personalizada, caso já exista.

Etapa 4 - Testar a política personalizada

Siga as etapas em Testar a política personalizada para testar sua política personalizada:

  1. Em Tipo de Conta, selecione Conta Pessoal
  2. Introduza os restantes detalhes conforme necessário e, em seguida, selecione Continuar. Você verá uma nova tela.
  3. Para Código de Acesso, digite 88888 e selecione Continuar. Depois que a política terminar a execução, você será redirecionado para https://jwt.mso , e verá um token JWT decodificado. Se você repetir o procedimento e inserir um código de acesso diferente, diferente de 88888, verá um erro, O código de acesso inserido está incorreto. Por favor, tente novamente.

Etapa 5 - Ativar o modo de depuração

No desenvolvimento, você pode querer ver erros detalhados enviados pela API, como developerMessage e moreInfo. Nesse caso, você precisa habilitar o modo de depuração em seu provedor técnico RESTful.

  1. Localize seu provedor técnico ValidateAccessCodeViaHttp e adicione o seguinte item no provedor técnico:metadata

        <Item Key="DebugMode">true</Item>

  2. Salve as alterações e carregue seu arquivo de política.

  3. Teste sua política personalizada. Certifique-se de que utiliza uma introdução errada para o seu Código de Acesso. Você verá um erro semelhante ao mostrado nesta captura de tela:

    A screenshot error when you enable debug mode.

Lidar com cargas úteis JSON de solicitação complexas

Se a API REST chamada exigir que você envie uma carga JSON complexa, você poderá criar a carga usando transformações de declarações JSON GenerateJson. Depois de gerar a carga útil, você pode usar ClaimUsedForRequestPayload a opção de metadados para o nome da declaração que contém a carga JSON útil.

Por exemplo, use a seguinte transformação de declarações para gerar uma carga JSON útil:

    <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>

O ClaimsTransformation gera o seguinte objeto JSON:

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

Em seguida, atualize os Metadados, InputClaimsTransformations, e InputClaims do seu provedor técnico RESTful, conforme mostrado abaixo:

    <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>

Receber dados da API REST

Se sua API REST retornar dados, que você deseja incluir como declarações em sua política, poderá recebê-los especificando declarações no OutputClaims elemento do perfil técnico RESTful. Se o nome da declaração definida em sua política for diferente do nome definido na API REST, você precisará mapear esses nomes usando o PartnerClaimType atributo.

Use as etapas em Recebendo dados para saber como formatar os dados esperados pela política personalizada, como manipular valores nulos e como analisar REST o corpo JSON aninhado da API.

Próximos passos

A seguir, aprenda: