Azure Active Directory B2C özel ilkesini kullanarak REST API çağırma

  • Makale

Azure Active Directory B2C (Azure AD B2C) özel ilkesi, Azure AD B2C dışında uyguladığınız uygulama mantığıyla etkileşim kurmanızı sağlar. Bunu yapmak için bir uç noktaya HTTP çağrısı yaparsınız. Azure AD B2C özel ilkeleri bu amaçla RESTful teknik profili sağlar. Bu özelliği kullanarak, Azure AD B2C özel ilkesinde bulunmayan özellikleri uygulayabilirsiniz.

Bu makalede şunları öğreneceksiniz:

  • RESTful hizmeti olarak kullanmak üzere örnek bir Node.js uygulaması oluşturun ve dağıtın.

  • RESTful teknik profilini kullanarak Node.js RESTful hizmetine http çağrısı yapın.

  • RESTful hizmetinin özel ilkenize döndürdüğü bir hatayı işleyebilir veya raporla.

Senaryoya genel bakış

Azure AD B2C özel ilkelerini kullanarak kullanıcı yolculuğunda dallanma oluşturma bölümünde, Kişisel Hesap'ı seçen kullanıcıların devam etmek için geçerli bir davet erişim kodu sağlaması gerekir. Statik erişim kodu kullanıyoruz, ancak gerçek dünya uygulamaları bu şekilde çalışmıyor. Erişim kodlarını veren hizmet özel ilkenizin dışındaysa, bu hizmete bir çağrı yapmanız ve doğrulama için kullanıcı tarafından erişim kodu girişini geçirmeniz gerekir. Erişim kodu geçerliyse, hizmet bir HTTP 200 OK yanıtı döndürür ve Azure AD B2C JWT belirtecini verir. Aksi takdirde, hizmet bir HTTP 409 Conflict yanıtı döndürür ve kullanıcının bir erişim kodu yeniden alması gerekir.

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

Önkoşullar

Dekont

Bu makale, Azure Active Directory B2C'de kendi özel ilkelerinizi oluşturma ve çalıştırma nasıl yapılır kılavuzu serisinin bir parçasıdır. Bu seriyi ilk makaleden başlatmanızı öneririz.

1. Adım - Node.js uygulaması oluşturma ve dağıtma

Dış uygulamanız olarak hizmet veren bir uygulama dağıtmanız gerekir. Ardından özel ilkeniz bu uygulamaya bir HTTP çağrısı yapar.

1.1. Adım - Node.js uygulamasını oluşturma

  1. Düğüm uygulamanızı barındırmak için gibi access-code-appbir klasör oluşturun.

  2. Terminalinizde dizini Node uygulama klasörünüzle değiştirin ( gibi cd access-code-app) ve komutunu çalıştırın npm init -y. Bu komut Node.js projeniz için varsayılan package.json bir dosya oluşturur.

  3. Terminalinizde npm install express body-parser komutunu çalıştırın. Bu komut Express çerçevesini ve gövde ayrıştırıcı paketini yükler.

  4. Projenizde dosya oluşturun index.js .

  5. VS Code'da dosyayı açın index.js ve aşağıdaki kodu ekleyin:

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

    Bir kullanıcı yanlış erişim kodu gönderdiğinde doğrudan REST API'den hata döndürebileceğinizi görebilirsiniz. Özel ilkeler, değişkende errorResponse gösterildiği gibi biçimlendirilmiş bir yanıt JSON gövdesiyle 400 (hatalı istek) veya 409 (Çakışma) yanıt durum kodu gibi bir HTTP 4xx hata iletisi döndürmenizi sağlar. Uygulamadaki accessCode'un kaynağı veritabanından okunabilir. Doğrulama hata iletisini döndürme hakkında daha fazla bilgi edinin.

  6. Uygulamanın beklendiği gibi çalıştığını test etmek için aşağıdaki adımları kullanın:

    1. Terminalinizde komutunu çalıştırarak uygulama sunucunuzu node index.js başlatın.
    2. Bu örnekte gösterilene benzer bir POST isteğinde bulunmak için Microsoft PowerShell veya Postman gibi bir HTTP istemcisi kullanabilirsiniz:
        POST http://localhost/validate-accesscode HTTP/1.1
    Host: localhost
    Content-Type: application/x-www-form-urlencoded

    accessCode=user-code-code

    yerine kullanıcı tarafından bir erişim kodu girişi (gibi54321) yazınuser-code-code. PowerShell kullanıyorsanız aşağıdaki betiği çalıştırın.

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

    Yanlış bir erişim kodu kullanırsanız yanıt aşağıdaki JSON kod parçacığına benzer:

        {
        "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"
    }

Bu noktada Node.js uygulamanızı dağıtmaya hazırsınız.

1.2. Adım - Node.js uygulamasını Azure Uygulaması Hizmeti'nde dağıtma

Özel ilkenizin Node.js uygulamanıza ulaşması için erişilebilir olması gerekir, bu nedenle dağıtmanız gerekir. Bu makalede, uygulamayı Azure Uygulaması Hizmeti'ni kullanarak dağıtırsınız, ancak alternatif bir barındırma yaklaşımı kullanırsınız.

Node.js uygulamanızı Azure'a dağıtmak için Uygulamanızı Azure'a dağıtma bölümünde yer alan adımları izleyin. Uygulamanın Adı için gibi custompolicyapiaçıklayıcı bir ad kullanın. Dolayı -sıyla:

  • Uygulama URL'si şuna https://custompolicyapi.azurewebsites.netbenzer: .

  • Hizmet uç noktası şuna https://custompolicyapi.azurewebsites.net/validate-accesscodebenzer: .

Microsoft PowerShell veya Postman gibi bir HTTP istemcisi kullanarak dağıtmış olduğunuz uygulamayı test edebilirsiniz. Bu kez, uç nokta olarak URL'yi kullanın https://custompolicyapi.azurewebsites.net/validate-accesscode .

2. Adım - REST API'yi çağırma

Uygulamanız çalıştığına göre, özel ilkenizden bir HTTP çağrısı yapmanız gerekir. Azure AD B2C özel ilkesi, dış hizmeti çağırmak için kullandığınız bir RESTful teknik profili sağlar.

Adım 2.1 - RESTful teknik profili tanımlama

Dosyanızda ContosoCustomPolicy.XML bölümünü bulun ClaimsProviders ve aşağıdaki kodu kullanarak yeni bir RESTful teknik profili tanımlayın:

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

Protokolden, RestfulProvider'ı kullanmak için Teknik Profili yapılandırdığımıza dikkat edebilirsiniz. Aşağıdaki bilgileri meta veri bölümünde de gözlemleyebilirsiniz:

  • API ServiceUrl uç noktasını temsil eder. Değeri şeklindedir https://custompolicyapi.azurewebsites.net/validate-accesscode. Node.js uygulamanızı alternatif bir yöntem kullanarak dağıttıysanız uç nokta değerini güncelleştirdiğinizden emin olun.

  • SendClaimsIn giriş taleplerinin RESTful talep sağlayıcısına nasıl gönderileceğini belirtir. Olası değerler: Body (default), Form, Headerveya UrlQueryString. örneğin bu makalede kullandığınızda BodyPOST HTTP fiilini ve anahtar olarak biçimlendirildiyse API'ye gönderdiğiniz verileri, isteğin gövdesindeki değer çiftlerini çağırırsınız. GET HTTP fiilini çağırmayı ve verileri sorgu dizesi olarak geçirmeyi öğrenin.

  • AuthenticationType RESTful talep sağlayıcısının gerçekleştirdiği kimlik doğrulama türünü belirtir. RESTful talep sağlayıcımız korumasız bir uç nokta çağırır, bu nedenle bizim AuthenticationTypeiçin Yok olarak ayarlanır. Kimlik doğrulama türünü olarak Bearerayarlarsanız, erişim belirtecinizin depolama alanını belirten bir CryptographicKeys öğesi eklemeniz gerekir. RESTful talep sağlayıcısının desteklediği kimlik doğrulama türleri hakkında daha fazla bilgi edinin.

  • içindeki InputClaim PartnerClaimType özniteliği, VERILERINIZI API'de nasıl aldığınızı belirtir.

2.2. Adım - Doğrulama teknik profilini güncelleştirme

Azure AD B2C özel ilkesini kullanarak kullanıcı yolculuğunda dallanma oluşturma bölümünde, bir talep dönüştürmesi kullanarak accessCode'u doğrulamıştınız. Bu makalede, bir dış hizmete HTTP çağrısı yaparak accessCode'u doğrulaacaksınız. Bu nedenle, özel ilkenizi yeni yaklaşımı yansıtacak şekilde güncelleştirmeniz gerekir.

AccessCodeInputCollector teknik profilini bulun ve ValidationTechnicalProfile öğesinin ReferenceId değerini ValidateAccessCodeViahttp için güncelleştirin:

Kaynak:

    <ValidationTechnicalProfile ReferenceId="CheckAccessCodeViaClaimsTransformationChecker"/>

yerine şunu yazın:

    <ValidationTechnicalProfile ReferenceId="ValidateAccessCodeViaHttp"/>

Bu noktada CheckAccessCodeViaClaimsTransformationChecker ile IdTeknik Profil gerekli değildir ve kaldırılabilir.

3. Adım - Özel ilke dosyasını karşıya yükleme

Node.js uygulamanızın çalıştığından emin olun ve ardından İlke dosyanızı karşıya yüklemek için Özel ilke dosyasını karşıya yükleme bölümünde yer alan adımları izleyin. Portalda bulunan dosyayla aynı ada sahip bir dosyayı karşıya yüklüyorsanız, zaten varsa Özel ilkenin üzerine yaz'ı seçtiğinizden emin olun.

4. Adım - Özel ilkeyi test edin

Özel ilkenizi test etmek için Özel ilkeyi test etme altındaki adımları izleyin:

  1. Hesap Türü için Kişisel Hesap'ı seçin
  2. Diğer ayrıntıları gerektiği gibi girin ve Devam'ı seçin. Yeni bir ekran görürsünüz.
  3. Erişim Kodu için 88888 girin ve Devam'ı seçin. İlke yürütmeyi tamamladıktan sonra adresine yönlendirilirsiniz https://jwt.msve kodu çözülen bir JWT belirteci görürsünüz. Yordamı yineler ve 88888 dışında farklı bir Erişim Kodu girerseniz, girdiğiniz erişim kodu yanlış hatasını görürsünüz. Lütfen yeniden deneyin.

5. Adım - Hata ayıklama modunu etkinleştirme

Geliştirme aşamasında, api tarafından gönderilen developerMessage ve moreInfo gibi ayrıntılı hataları görmek isteyebilirsiniz. Bu durumda, RESTful teknik sağlayıcınızda hata ayıklama modunu etkinleştirmeniz gerekir.

  1. ValidateAccessCodeViaHttp teknik sağlayıcınızı bulun ve teknik sağlayıcının metadataöğesine aşağıdaki öğeyi ekleyin:

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

  2. Değişiklikleri kaydedin ve ilke dosyanızı karşıya yükleyin.

  3. Özel ilkenizi test edin. Erişim Kodunuz için yanlış giriş kullandığınızdan emin olun. Bu ekran görüntüsünde gösterilene benzer bir hata görürsünüz:

    A screenshot error when you enable debug mode.

Karmaşık istek JSON yüklerini işleme

Çağırdığınız REST API karmaşık bir JSON yükü göndermenizi gerektiriyorsa GenerateJson JSON talep dönüştürmelerini kullanarak yükü oluşturabilirsiniz. Yükü oluşturduktan sonra, JSON yükünü içeren talebin adına meta veri seçeneğini kullanabilirsinizClaimUsedForRequestPayload.

Örneğin, bir JSON yükü oluşturmak için aşağıdaki talep dönüştürmesini kullanın:

    <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 aşağıdaki JSON nesnesini oluşturur:

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

Ardından, RESTful teknik sağlayıcınızın Metadata, InputClaimsTransformations ve InputClaims değerlerini aşağıda gösterildiği gibi güncelleştirin:

    <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'den veri alma

REST API'niz ilkenize talep olarak eklemek istediğiniz verileri döndürürse, RESTful teknik profilinin OutputClaims öğesinde talepler belirterek bu verileri alabilirsiniz. İlkenizde tanımlanan talebin adı REST API'de tanımlanan addan farklıysa, özniteliğini PartnerClaimType kullanarak bu adları eşlemeniz gerekir.

Özel ilkenin beklediği verileri biçimlendirmeyi, null değerleri işlemeyi ve API'nin iç içe JSON gövdesini ayrıştırmayı öğrenmek için Verileri alma adımlarını kullanın.

Sonraki adımlar

Ardından şunları öğrenin: