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

Artigo
01/11/2024

A política personalizada do Azure AD B2C (Azure Active Directory B2C) permite que você interaja com a lógica de aplicativo implementada fora do Azure AD B2C. Para isso, faça 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. Ao usar esse recurso, você poderá implementar recursos que não estão disponíveis na política personalizada do Azure AD B2C.

Neste artigo, você aprenderá como:

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 Node.js usando o perfil técnico RESTful.
Manipule ou relate um erro que um serviço RESTful retorna à sua política personalizada.

Visão geral do cenário

Em Criar ramificação no percurso do usuário usando as 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. Usamos um código de acesso estático, mas os aplicativos do mundo real não funcionam dessa maneira. 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 retornará uma resposta HTTP 409 Conflict e o usuário precisará inserir novamente um código de acesso.

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

Pré-requisitos

Se ainda não tiver um, você precisará criar um locatário do Azure AD B2C que esteja vinculado à sua assinatura do Azure.
Registre um aplicativo Web e habilite a concessão implícita de token de ID. Para o URI de Redirecionamento, use https://jwt.ms.
Você deve ter o Node.js instalado em seu computador.
Você deve ter o Visual Studio Code (VS Code) instalado em seu computador.
Conclua as etapas em Validar as entradas do usuário usando a política personalizada do Azure AD B2C. Este artigo faz parte da série de guias Criar e executar suas próprias políticas personalizadas.

Observação

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

Etapa 1 - Criar e implantar um aplicativo Node.js

Você precisa implantar um aplicativo, que servirá como aplicativo externo. Em seguida, sua política personalizada fará uma chamada HTTP para esse aplicativo.

Etapa 1.1 - Criar o aplicativo Node.js

Crie uma pasta para hospedar seu aplicativo do Node, como access-code-app.
No seu terminal, altere o diretório para a pasta do aplicativo do Node, como cd access-code-app, e execute npm init -y. Esse comando cria um arquivo package.json padrão para seu projeto Node.js.
Execute npm install express body-parser no seu terminal. Esse comando instala a estrutura Expresso e o pacote do analisador de corpo.
Em seu projeto, crie um arquivo index.js.

No VS Code, abra o arquivo index.js e, em seguida, adicione o 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);
    });

Observe 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 variável errorResponse. A origem do accessCode no aplicativo pode ser lida de um banco de dados. Saiba mais sobre Como retornar mensagem de erro de validação.

Para testar se o aplicativo está funcionando conforme o esperado, use as seguintes etapas:

No terminal, execute o comando node index.js para iniciar o servidor de aplicativos.
Para fazer uma solicitação POST semelhante à mostrada neste exemplo, use 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 uma entrada de código de acesso pelo usuário, como 54321. Se 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 snippet 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 momento, você estará 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 chegue ao seu aplicativo Node.js, ela precisa ser acessível, portanto, você precisará implantá-la. Neste artigo, você implantará o aplicativo usando o Serviço de Aplicativo do Azure, mas usará uma abordagem alternativa de hospedagem.

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

O URL do aplicativo será semelhante a https://custompolicyapi.azurewebsites.net.
O ponto de extremidade de serviço será semelhante a https://custompolicyapi.azurewebsites.net/validate-accesscode.

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

Etapa 2 - Chamar a API REST

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

Etapa 2.1 - Definir um perfil técnico RESTful

No arquivo ContosoCustomPolicy.XML, localize a seção ClaimsProviders 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>-->

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

O ServiceUrl representa o ponto de extremidade da API. Seu valor é https://custompolicyapi.azurewebsites.net/validate-accesscode. Se você implantou seu aplicativo Node.js usando um método alternativo, atualize 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), Form, Header, 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, pares de valor 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, portanto, definimos AuthenticationType como Nenhum. Se você definir o tipo de autenticação como Bearer, precisará adicionar um elemento CryptographicKeys, que especifica o armazenamento do token de acesso. Saiba mais sobre os tipos de autenticação compatíveis com o provedor de declarações RESTful.
O atributo PartnerClaimType no InputClaim especifica como você receberá os dados na API.

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

Em Criar ramificação no percurso 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 a política personalizada para refletir a nova abordagem.

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

A partir:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

para:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Deste ponto, o Perfil Técnico com IdCheckAccessCodeViaClaimsTransformationChecker não é necessário e pode ser removido.

Etapa 3 - Carregar arquivo da política personalizada

Verifique se o aplicativo Node.js está em execução e siga as etapas em Carregar arquivo da política personalizada para carregar o arquivo da política. Se você estiver carregando um arquivo com o mesmo nome que está no portal, selecione Substituir a política personalizada se ela já existir.

Etapa 4 - Testar a política personalizada

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

Em Tipo de Conta, selecione Conta Pessoal
Insira o restante dos detalhes conforme necessário e, em seguida, selecione Continuar Você verá uma nova tela.
Para Código de Acesso, insira 88888 e selecione Continuar. Depois que a política concluir a execução, você será redirecionado para https://jwt.ms e verá um token JWT decodificado. Se repetir o procedimento e inserir um Código de Acesso diferente de 88888, verá o erro: O código de acesso inserido está incorreto. Tente novamente.

Etapa 5 - Habilitar o modo de depuração

No desenvolvimento, talvez você queira ver erros detalhados enviados pela API, como developerMessage e moreInfo. Nesse caso, você precisará habilitar o modo de depuração no provedor técnico RESTful.

Localize seu provedor técnico ValidateAccessCodeViaHttp e adicione o seguinte item no metadata do provedor técnico:
```
    <Item Key="DebugMode">true</Item>
```
Salve as alterações e carregue o arquivo da política.
Teste sua política personalizada. Certifique-se de usar uma entrada errada para o Código de Acesso. Você verá um erro semelhante ao mostrado nesta captura de tela:

Manipular conteúdos JSON de solicitação complexos

Se a API REST chamada exigir o envio de um conteúdo JSON complexo, você poderá criar o conteúdo usando as transformações de declarações JSON GenerateJson. Depois de gerar o conteúdo, você poderá usar a opção de ClaimUsedForRequestPayloadmetadados para o nome da declaração que contém o conteúdo JSON.

Por exemplo, use a seguinte transformação de declarações para gerar um conteúdo 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>

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 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 na sua política, você poderá recebê-los especificando as declarações no elemento OutputClaims do perfil técnico RESTful. Se o nome da declaração definida na sua política for diferente do nome definido na API REST, você precisará mapear esses nomes usando o atributo PartnerClaimType.

Use as etapas em Recebendo dados para saber como formatar os dados que a política personalizada espera, como lidar com valores nulos e como analisar a REST no corpo JSON aninhado da API.

Próximas etapas

Em seguida, aprenda:

Sobre as transformações de declarações JSON.
Sobre o perfil técnico RESTful.
Como Criar e ler uma conta de usuário usando a política personalizada do Azure Active Directory B2C

Compartilhar via