Azure AD B2C kullanarak kendi web API'nizde kimlik doğrulamasını etkinleştirme

Bir web API'sine erişimi yetkilendirmek için yalnızca Azure Active Directory B2C (Azure AD B2C) tarafından karşılaşılan geçerli bir erişim belirtecini içeren istekler sağlayabilirsiniz. Bu makalede web API'nizde Azure AD B2C yetkilendirmesini etkinleştirme adımları gösterilmektedir. Bu makaledeki adımları tamamladıktan sonra, yalnızca geçerli bir erişim belirteci alan kullanıcılara web API uç noktalarınızı çağırma yetkisi verilecektir.

Önkoşullar

Başlamadan önce, web API'lerini çağıran uygulamalar için kimlik doğrulamasını yapılandırmayı ele alan aşağıdaki makalelerden birini okuyun. Ardından, örnek web API'sini kendi web API'nizle değiştirmek için bu makaledeki adımları izleyin.

• Örnek ASP.NET Core uygulamasında kimlik doğrulamayı yapılandırma
• Örnek tek sayfalı uygulamada (SPA) kimlik doğrulamayı yapılandırma

Genel Bakış

Belirteç tabanlı kimlik doğrulaması, web API'sine yapılan isteklerin geçerli bir erişim belirteci içermesini sağlar.

Uygulama aşağıdaki adımları tamamlar:

1. Azure AD B2C ile kullanıcıların kimliğini doğrular.

2. Web API uç noktası için gerekli izinlere (kapsamlara) sahip bir erişim belirteci alır.

3. Bu biçimi kullanarak http isteğinin kimlik doğrulama üst bilgisinde erişim belirtecini taşıyıcı belirteç olarak geçirir:

   Authorization: Bearer <access token>
   

Web API'sinde aşağıdaki adımlar tamamlar:

1. HTTP isteğindeki yetkilendirme üst bilgisinden taşıyıcı belirtecini okur.

2. Belirteci doğrular.

3. Belirteçteki izinleri (kapsamları) doğrular.

4. Belirteçte kodlanmış talepleri okur (isteğe bağlı).

5. HTTP isteğine yanıt verir.

Uygulama kaydına genel bakış

Uygulamanızın Azure AD B2C ile oturum açmasını ve bir web API'sini çağırmasını sağlamak için Azure AD B2C dizinine iki uygulama kaydetmeniz gerekir.

• Web, mobil veya SPA uygulaması kaydı, uygulamanızın Azure AD B2C ile oturum açmasını sağlar. Uygulama kayıt işlemi, uygulamanızı benzersiz olarak tanımlayan istemci kimliği olarak da bilinen bir Uygulama Kimliği oluşturur (örneğin, Uygulama Kimliği: 1).

• Web API kaydı, uygulamanızın korumalı bir web API'sini çağırmasını sağlar. Kayıt, web API'sinin izinlerini (kapsamları) kullanıma sunar. Uygulama kayıt işlemi, web API'nizi benzersiz olarak tanımlayan bir Uygulama Kimliği oluşturur (örneğin, Uygulama Kimliği: 2). Uygulamanıza (Uygulama Kimliği: 1) web API'si kapsamları için izin verin (Uygulama Kimliği: 2).

Uygulama kayıtları ve uygulama mimarisi aşağıdaki diyagramda açıklanmıştır:

Geliştirme ortamınızı hazırlama

Sonraki bölümlerde yeni bir web API'si projesi oluşturacaksınız. Core veya Node.js ASP.NET programlama dilinizi seçin. Aşağıdaki yazılımlardan birini çalıştıran bir bilgisayarınız olduğundan emin olun:

ASP.NET Core

• Visual Studio Code
• Visual Studio Code için C# (en son sürüm)
• .NET 5.0 SDK

Node.js

• Visual Studio Code veya başka bir kod düzenleyicisi
• Node.js çalışma zamanı

1. Adım: Korumalı web API'si oluşturma

Yeni bir web API'si projesi oluşturun. İlk olarak, core veya node.js ASP.NET kullanmak istediğiniz programlama dilini seçin.

ASP.NET Core

dotnet new komutunu kullanın. komut, dotnet new web API'sinin proje varlıklarıyla TodoList adlı yeni bir klasör oluşturur. Dizini açın ve ardından Visual Studio Code'ı açın.

dotnet new webapi -o TodoList
cd TodoList
code . 

"Gerekli varlıkları projeye eklemeniz" istendiğinde Evet'i seçin.

Node.js

Web API'sini oluşturmak için Node.js için Express kullanın. Web API'sini oluşturmak için aşağıdakileri yapın:

1. TodoList adlı yeni bir klasör oluşturun.
2. TodoList klasörünün altında app.js adlı bir dosya oluşturun.
3. Komut kabuğunda komutunu çalıştırın npm init -y. Bu komut, Node.js projeniz için varsayılan package.json dosyasını oluşturur.
4. Komut kabuğunda npm install express komutunu çalıştırın. Bu komut, Express çerçevesini yükler.

2. Adım: Bağımlılıkları yükleme

Kimlik doğrulama kitaplığını web API'niz projesine ekleyin. Kimlik doğrulama kitaplığı HTTP kimlik doğrulama üst bilgisini ayrıştırıyor, belirteci doğrular ve talepleri ayıklar. Daha fazla bilgi için kitaplığın belgelerini gözden geçirin.

ASP.NET Core

Kimlik doğrulama kitaplığını eklemek için aşağıdaki komutu çalıştırarak paketi yükleyin:

dotnet add package Microsoft.Identity.Web

Node.js

Kimlik doğrulama kitaplığını eklemek için aşağıdaki komutu çalıştırarak paketleri yükleyin:

npm install passport
npm install passport-azure-ad
npm install morgan

Morgan paketi Node.js için bir HTTP istek günlükçü ara yazılımıdır.

3. Adım: Kimlik doğrulama kitaplığını başlatma

Kimlik doğrulama kitaplığını başlatmak için gerekli kodu ekleyin.

ASP.NET Core

Startup.cs dosyasını açın ve sınıfın başına aşağıdaki using bildirimleri ekleyin:

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

İşlevi ConfigureServices(IServiceCollection services) bulun. Ardından, kod satırından services.AddControllers(); önce aşağıdaki kod parçacığını ekleyin:

public void ConfigureServices(IServiceCollection services)
{
    // Adds Microsoft Identity platform (Azure AD B2C) support to protect this Api
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApi(options =>
    {
        Configuration.Bind("AzureAdB2C", options);

        options.TokenValidationParameters.NameClaimType = "name";
    },
    options => { Configuration.Bind("AzureAdB2C", options); });
    // End of the Microsoft Identity platform block    

    services.AddControllers();
}

İşlevi Configure bulun. Ardından, kod satırından app.UseRouting(); hemen sonra aşağıdaki kod parçacığını ekleyin:

app.UseAuthentication();

Değişiklik sonrasında kodunuz aşağıdaki kod parçacığı gibi görünmelidir:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();
    
    // Add the following line 
    app.UseAuthentication();
    // End of the block you add
    
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Node.js

App.js dosyanıza aşağıdaki JavaScript kodunu ekleyin.

// Import the required libraries
const express = require('express');
const morgan = require('morgan');
const passport = require('passport');
const config = require('./config.json');

// Import the passport Azure AD library
const BearerStrategy = require('passport-azure-ad').BearerStrategy;

// Set the Azure AD B2C options
const options = {
    identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    audience: config.credentials.clientID,
    issuer: config.credentials.issuer,
    policyName: config.policies.policyName,
    isB2C: config.settings.isB2C,
    scope: config.resource.scope,
    validateIssuer: config.settings.validateIssuer,
    loggingLevel: config.settings.loggingLevel,
    passReqToCallback: config.settings.passReqToCallback
}

// Instantiate the passport Azure AD library with the Azure AD B2C options
const bearerStrategy = new BearerStrategy(options, (token, done) => {
        // Send user info using the second argument
        done(null, { }, token);
    }
);

// Use the required libraries
const app = express();

app.use(morgan('dev'));

app.use(passport.initialize());

passport.use(bearerStrategy);

//enable CORS (for testing only -remove in production/deployment)
app.use((req, res, next) => {
    res.header('Access-Control-Allow-Origin', '*');
    res.header('Access-Control-Allow-Headers', 'Authorization, Origin, X-Requested-With, Content-Type, Accept');
    next();
});

4. Adım: Uç noktaları ekleme

Web API'nize iki uç nokta ekleyin:

• Anonim /public uç nokta. Bu uç nokta geçerli tarih ve saati döndürür. Anonim çağrılarla web API'nizde hata ayıklamak için bu api'yi kullanın.
• Korumalı /hello uç nokta. Bu uç nokta, erişim belirteci içindeki talebin değerini name döndürür.

Anonim uç noktayı eklemek için:

ASP.NET Core

/Controllers klasörünün altına bir PublicController.cs dosyası ekleyin ve ardından aşağıdaki kod parçacığına ekleyin:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace TodoList.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PublicController : ControllerBase
    {
        private readonly ILogger<PublicController> _logger;

        public PublicController(ILogger<PublicController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new {date = DateTime.UtcNow.ToString()});
        }
    }
}

Node.js

app.js dosyasına aşağıdaki JavaScript kodunu ekleyin:

// API anonymous endpoint
app.get('/public', (req, res) => res.send( {'date': new Date() } ));

Korumalı uç noktayı eklemek için:

ASP.NET Core

/Controllers klasörünün altına bir HelloController.cs dosyası ekleyin ve ardından aşağıdaki koda ekleyin:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.Resource;

namespace TodoList.Controllers
{
    [Authorize]
    [RequiredScope("tasks.read")]
    [ApiController]
    [Route("[controller]")]
    public class HelloController : ControllerBase
    {

        private readonly ILogger<HelloController> _logger;
        private readonly IHttpContextAccessor _contextAccessor;

        public HelloController(ILogger<HelloController> logger, IHttpContextAccessor contextAccessor)
        {
            _logger = logger;
            _contextAccessor = contextAccessor;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new { name = User.Identity.Name});
        }
    }
}

DenetleyiciHelloController, erişimi yalnızca kimliği doğrulanmış kullanıcılarla sınırlayan AuthorizeAttribute ile dekore edilmiştir.

Denetleyici ile de dekore edilmiştir [RequiredScope("tasks.read")]. RequiredScopeAttribute, web API'sinin doğru kapsamlarla çağrıldığını doğrulartasks.read.

Node.js

app.js dosyasına aşağıdaki JavaScript kodunu ekleyin:

// API protected endpoint
app.get('/hello',
    passport.authenticate('oauth-bearer', {session: false}),
    (req, res) => {
        console.log('Validated claims: ', req.authInfo);
        
        // Service relies on the name claim.  
        res.status(200).json({'name': req.authInfo['name']});
    }
);

Uç /hello nokta ilk olarak işlevini çağırır passport.authenticate() . Kimlik doğrulama işlevi erişimi yalnızca kimliği doğrulanmış kullanıcılarla sınırlar.

Kimlik doğrulama işlevi, web API'sinin doğru kapsamlarla çağrıldığını da doğrular. İzin verilen kapsamlar yapılandırma dosyasında bulunur.

5. Adım: Web sunucusunu yapılandırma

Geliştirme ortamında, web API'sini gelen HTTP veya HTTPS istekleri bağlantı noktası numarasını dinleyecek şekilde ayarlayın. Bu örnekte HTTP bağlantı noktası 6000 ve HTTPS bağlantı noktası 6001 kullanın. Web API'sinin temel URI'si HTTP ve https://localhost:6001 HTTPS için olacaktırhttp://localhost:6000.

ASP.NET Core

Appsettings.json dosyasına aşağıdaki JSON parçacığını ekleyin.

"Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:6000"
      },
      "Https": {
         "Url": "https://localhost:6001"   
        }
    }
  }

Node.js

App.js dosyasına aşağıdaki JavaScript kodunu ekleyin. Node uygulaması için HTTP ve HTTPS uç noktalarını ayarlamak mümkündür.

// Starts listening on port 6000
const port = process.env.PORT || 6000;

app.listen(port, () => {
    console.log('Listening on port ' + port);
});

6. Adım: Web API'sini yapılandırma

Yapılandırma dosyasına yapılandırmalar ekleyin. Dosya, Azure AD B2C kimlik sağlayıcınız hakkında bilgi içerir. Web API uygulaması, web uygulamasının taşıyıcı belirteç olarak geçirdiği erişim belirtecini doğrulamak için bu bilgileri kullanır.

ASP.NET Core

Proje kök klasörünün altında appsettings.json dosyasını açın ve aşağıdaki ayarları ekleyin:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

appsettings.json dosyasında aşağıdaki özellikleri güncelleştirin:

Bölüm	Anahtar	Değer
AzureAdB2C	Örnek	Azure AD B2C kiracı adınızın ilk bölümü (örneğin, https://contoso.b2clogin.com).
AzureAdB2C	Domain	Azure AD B2C kiracınızın tam kiracı adı (örneğin, contoso.onmicrosoft.com).
AzureAdB2C	ClientId	Web API'si uygulama kimliği. Yukarıdaki diyagramda Uygulama Kimliği: 2 olan uygulamadır. Web API'si uygulama kayıt kimliğinizi nasıl alacağınızı öğrenmek için bkz . Önkoşullar.
AzureAdB2C	SignUpSignInPolicyId	Kullanıcı akışları veya özel ilke. Kullanıcı akışınızı veya ilkenizi nasıl edineceğinizi öğrenmek için bkz . Önkoşullar.

Node.js

Proje kök klasörünün altında bir config.json dosyası oluşturun ve bunu aşağıdaki JSON kod parçacığına ekleyin:

{
    "credentials": {
        "tenantName": "<your-tenant-name>.onmicrosoft.com",
        "clientID": "<your-webapi-application-ID>",
        "issuer": "https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/"
    },
    "policies": {
        "policyName": "b2c_1_susi"
    },
    "resource": {
        "scope": ["tasks.read"]
    },
    "metadata": {
        "discovery": ".well-known/openid-configuration",
        "version": "v2.0"
    },
    "settings": {
        "isB2C": true,
        "validateIssuer": true,
        "passReqToCallback": false,
        "loggingLevel": "info"
    }
}

config.json dosyasında aşağıdaki özellikleri güncelleştirin:

Bölüm	Anahtar	Değer
kimlik bilgileri	tenantName	Azure AD B2C kiracı adınız/etki alanı adınız (örneğin, contoso.onmicrosoft.com).
kimlik bilgileri	Clientıd	Web API'si uygulama kimliği. Yukarıdaki diyagramda Uygulama Kimliği: 2 olan uygulamadır. Web API'si uygulama kayıt kimliğinizi nasıl alacağınızı öğrenmek için bkz . Önkoşullar.
kimlik bilgileri	yayınlayan	Belirteç veren iss talep değeri. Varsayılan olarak, Azure AD B2C belirteci şu biçimde döndürür: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. değerini Azure AD B2C kiracı adınızın ilk bölümüyle değiştirin<your-tenant-name>. değerini Azure AD B2C kiracı kimliğiniz ile değiştirin<your-tenant-ID>.
ilkeler	policyName	Kullanıcı akışları veya özel ilke. Kullanıcı akışınızı veya ilkenizi nasıl edineceğinizi öğrenmek için bkz . Önkoşullar.
kaynak	kapsam	Web API uygulama kaydınızın kapsamları. Web API'nizin kapsamını almayı öğrenmek için bkz . Önkoşullar.

7. Adım: Web API'sini çalıştırma ve test edin

Son olarak, Web API'sini Azure AD B2C ortam ayarlarınız ile çalıştırın.

ASP.NET Core

Komut kabuğunda aşağıdaki komutu çalıştırarak web uygulamasını başlatın:

 dotnet run

Aşağıdaki çıkışı görmeniz gerekir. Bu, uygulamanızın çalışır durumda olduğu ve istekleri almaya hazır olduğu anlamına gelir.

Now listening on: http://localhost:6000

Programı durdurmak için komut kabuğunda Ctrl+C tuşlarına basın. komutunu kullanarak node app.js uygulamayı yeniden çalıştırabilirsiniz.

Bahşiş

Alternatif olarak, komutunu çalıştırmak dotnet run için Visual Studio Code hata ayıklayıcısını kullanabilirsiniz. Visual Studio Code'un yerleşik hata ayıklayıcısı düzenleme, derleme ve hata ayıklama döngünüzü hızlandırmaya yardımcı olur.

Bir tarayıcıyı açın ve http://localhost:6000/public adresine gidin. Tarayıcı penceresinde, geçerli tarih ve saatle birlikte aşağıdaki metnin görüntülendiğini görmeniz gerekir.

Node.js

Komut kabuğunda aşağıdaki komutu çalıştırarak web uygulamasını başlatın:

node app.js

Aşağıdaki çıkışı görmeniz gerekir. Bu, uygulamanızın çalışır durumda olduğu ve istekleri almaya hazır olduğu anlamına gelir.

Example app listening on port 6000!

Programı durdurmak için komut kabuğunda Ctrl+C tuşlarına basın. komutunu kullanarak node app.js uygulamayı yeniden çalıştırabilirsiniz.

Bahşiş

Alternatif olarak, komutunu çalıştırmak node app.js için Visual Studio Code hata ayıklayıcısını kullanın. Visual Studio Code'un yerleşik hata ayıklayıcısı düzenleme, derleme ve hata ayıklama döngünüzü hızlandırmaya yardımcı olur.

Bir tarayıcıyı açın ve http://localhost:6000/public adresine gidin. Tarayıcı penceresinde, geçerli tarih ve saatle birlikte aşağıdaki metnin görüntülendiğini görmeniz gerekir.

8. Adım: Uygulamanızdan web API'sini çağırma

Erişim belirteci olmadan korumalı web API'sinin uç noktasını çağırmayı deneyin. Bir tarayıcıyı açın ve http://localhost:6000/hello adresine gidin. API, web API'sinin taşıyıcı belirteçle korunduğunu onaylayan yetkisiz bir HTTP hata iletisi döndürür.

Uygulamanızı web API'sini çağıracak şekilde yapılandırmaya devam edin. Yönergeler için Önkoşullar bölümüne bakın.

Azure AD B2C'yi bir API ile tümleştirirken en iyi yöntemler hakkında bilgi edinmek için bu videoyu izleyin.

Sonraki adımlar

GitHub'da tam örneği alın:

ASP.NET Core

• Microsoft kimlik kitaplığını kullanarak web API'sini alın.

Node.js

• Passport.js kitaplığını kullanarak web API'sini alın.