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

Önemli

1 Mayıs 2025 tarihinden itibaren Azure AD B2C artık yeni müşteriler için satın alınamayacak. SSS bölümünden daha fazla bilgi edinebilirsiniz.

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'yi tamamlayan adımlar şunlardır:

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

2. Jetonu doğrular.

3. Tokendeki izinleri (kapsamları) kontrol eder.

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. Programlama dilinizi, ASP.NET Core veya Node.jsseç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'sı

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, kullanmak istediğiniz programlama dilini seçin ASP.NET Core veya Node.js.

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 oluşturmak için Node.js sürümüyle 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.jsadlı bir dosya oluşturun.
3. Komut kabuğunda npm init -y komutunu çalıştırın. Bu komut , Node.js projeniz için varsayılan birpackage.jsondosyası 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.jsiç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 açın ve sınıfın başına aşağıdaki using bildirimleri ekleyin:

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

ConfigureServices(IServiceCollection services) işlevini 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();
}

Configure işlevini 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

aşağıdaki JavaScript kodunu app.js dosyanıza 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.
• /hello uç noktası korumalı. 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});
        }
    }
}

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

Denetleyici ayrıca [RequiredScope("tasks.read")] ile süslenmiştir. 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']});
    }
);

İlk olarak /hello uç noktası, passport.authenticate() işlevini çağırır. 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 için http://localhost:6000 ve HTTPS için https://localhost:6001 olacaktır.

ASP.NET Core

aşağıdaki JSON parçacığını appsettings.json dosyasına 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	Alan adı	Azure AD B2C kiracınızın tam kiracı adı (örneğin, contoso.onmicrosoft.com).
AzureAdB2C	İstemci Kimliği	Web API'si uygulama kimliği. Önceki 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	KayıtOturumAçmaPolitikasıKimliği	Kullanıcı akışları ya da özel politika. 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 birconfig.json dosyası oluşturun ve sonra bu dosyayı 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	kiracıAdı	Azure AD B2C kiracı adınız/etki alanı adınız (örneğin, contoso.onmicrosoft.com).
kimlik bilgileri	müşteriKimliği	Web API'si uygulama kimliği. Önceki 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	Jeton veren iss talep edilen değer. 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/. Azure AD B2C <your-tenant-name> ilk bölümüyle değerini değiştirin. <your-tenant-ID> öğesini Azure AD B2C kiracı kimliğiniz ile değiştirin.
Politikalar	politikaAdı	Kullanıcı akışları ya da özel politika. 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.

Tavsiye

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.

Tavsiye

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.

İlgili içerik

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.