Engedélyezze a hitelesítést saját webes API-jában az Azure AD B2C használatával.

Fontos

2025. május 1-jére az Azure AD B2C már nem lesz elérhető az új ügyfelek számára. További információ a GYIK-ben.

A web API elérésének engedélyezéséhez csak azokat a kérelmeket szolgálhatja ki, amelyek tartalmaznak egy érvényes hozzáférési tokent, amelyet az Azure Active Directory B2C (Azure AD B2C) bocsát ki. Az alábbi cikk bemutatja, hogyan engedélyezheti Azure AD B2C jogosultságot a webes API-hoz. Miután elvégezte ennek a cikknek a lépéseit, csak azok a felhasználók lesznek jogosultak hívni az Ön webes API végpontjait, akik érvényes hozzáférési tokent szereznek.

Előfeltételek

Mielőtt elkezdi, olvassa el az alábbi cikkek egyikét, amelyek arról szólnak, hogyan lehet beállítani a hitelesítést olyan alkalmazásokhoz, amelyek webes API-kat hívnak meg. Ezután kövesse a cikk lépéseit, hogy a mintául szolgáló webes API-t lecserélje saját webes API-jára.

• Hitelesítés konfigurálása egy mintaként szolgáló ASP.NET Core alkalmazásban
• Hitelesítés konfigurálása egy minta egyoldalas alkalmazásban (SPA)

Áttekintés

A token alapú hitelesítés biztosítja, hogy a webes API-kérelmek tartalmaznak érvényes hozzáférési tokent.

Az alkalmazás a következő lépéseket hajtja végre:

1. Felhasználók hitelesítése az Azure AD B2C használatával történik.

2. Megszerzi a web API végpontjához szükséges jogosultságokkal (hatáskörökkel) rendelkező hozzáférési tokent.

3. Átadja a hozzáférési tokent hordozó tokentként az HTTP kérés hitelesítési fejléce formátumának megfelelően.

   Authorization: Bearer <access token>
   

A web API a következő lépéseket hajtja végre:

1. Az HTTP-kérésben lévő engedélyezési fejlécelemben található legitimációs token olvasása történik.

2. Érvényesíti a tokent.

3. Ellenőrzi az engedélyeket (hatóköröket) a tokenben.

4. Leolvassa a tokenbe kódolt állításokat (opcionális).

5. Válaszol az HTTP kérésre.

Az alkalmazás regisztrációjának áttekintése

Az alkalmazás számára az Azure AD B2C használatával történő bejelentkezés és egy webes API hívásának lehetővé tétele érdekében két alkalmazást kell regisztrálnia az Azure AD B2C könyvtárban.

• A webes, mobil vagy egyoldalas alkalmazás regisztráció lehetővé teszi az alkalmazás számára, hogy bejelentkezzen az Azure AD B2C-be. Az alkalmazás regisztrációs folyamata létrehoz egy alkalmazásazonosítót, más néven ügyfélazonosítót, amely egyedileg azonosítja az alkalmazását (például, alkalmazásazonosító: 1).

• A webes API-regisztrációval az alkalmazás meghívhat egy védett webes API-t. A regisztráció elérhetővé teszi a webes API-engedélyeket (hatóköröket). Az alkalmazás regisztrációs folyamata létrehoz egy alkalmazásazonosítót, amely egyedülálló módon azonosítja a webes API-ját (például: App ID: 2). Engedélyezze az alkalmazásának (App ID: 1) jogosultságait a webes API-hatókörök számára (App ID: 2).

A következő diagram bemutatja az alkalmazásregisztrációkat és az alkalmazás architektúráját.

A fejlesztési környezet előkészítése

A következő szakaszokban egy új webes API projektet hoz létre. Válassza ki a programozási nyelvét: ASP.NET Core vagy Node.js. Győződjön meg arról, hogy számítógépe az alábbi szoftverek valamelyikét futtatja:

ASP.NET Core

• Visual Studio Code
• C# for Visual Studio Code (legújabb verzió)
• .NET 5.0 SDK

Node.js

• Visual Studio Code, vagy egy másik kódszerkesztő
• Node.js futási idő

1. lépés: Védett webes API létrehozása

Hozzon létre egy új webes API projektet. Először válassza ki a használni kívánt programozási nyelvet, ASP.NET Core vagy Node.js.

ASP.NET Core

Használja a dotnet new parancsot. A dotnet new parancs létrehoz egy új mappát TodoList névvel, amely a web API projekt eszközeit tartalmazza. Nyissa meg a könyvtárat, majd nyissa meg a Visual Studio Code-ot.

dotnet new webapi -o TodoList
cd TodoList
code . 

Amikor felszólítják, hogy "adja hozzá a szükséges eszközöket a projekthez," válassza az Igen opciót.

Node.js

Használja az Express-t a Node.js-hez webes API készítéséhez. Ahhoz, hogy webes API-t hozzon létre, tegye a következőket:

1. Hozzon létre egy új mappát, amelynek neve TodoList.
2. A TodoList mappa alatt hozz létre egy fájlt, melynek neve app.js.
3. Egy parancssori felületben futtassa a(z) npm init -y. Ez a parancs létrehoz egy alapértelmezett package.json fájlt a Node.js projektedhez.
4. A parancssorban futtassa a npm install express parancsot. Ez a parancs telepíti az Express keretrendszert.

2. lépés: Telepítse a függőségeket

Adja hozzá az azonosítási könyvtárat a webes API projektjéhez. Az autentikációs könyvtár elemzi az HTTP autentikációs fejléceket, ellenőrzi a tokent és kibontja az állításokat. További információkért tekintse át a könyvtár dokumentációját.

ASP.NET Core

Az autentikációs könyvtár hozzáadásához telepítse a csomagot a következő parancs futtatásával:

dotnet add package Microsoft.Identity.Web

Node.js

Az autentikációs könyvtár hozzáadásához telepítse a csomagokat az alábbi parancs futtatásával:

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

A Morgan csomag egy HTTP kéréseket naplózó köztes szoftver a Node.js számára.

3. lépés: Indítsa el a hitelesítési könyvtárat

Adja hozzá a szükséges kódot az azonosítási könyvtár inicializálásához.

ASP.NET Core

Nyissa meg a Startup.cs fájlt, majd az osztály elején adja hozzá a következő using deklarációkat:

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

Keresse meg a ConfigureServices(IServiceCollection services) függvényt. Ezután a services.AddControllers(); kódsor előtt adja hozzá a következő kódrészletet:

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

Keresse meg a Configure függvényt. Ezután, közvetlenül a app.UseRouting(); kódsor után, adja hozzá a következő kódrészletet:

app.UseAuthentication();

A változtatás után a kódodnak így kell kinéznie:

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

Adja hozzá a következő JavaScript kódot a app.js fájlhoz.

// 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. lépés: Adja hozzá a végpontokat

Adj hozzá két végpontot a webes API-dhoz.

• Névtelen /public végpont. Ez a végpont visszaadja a jelenlegi dátumot és időt. Használd ezt a web API-d hibakeresésére anonim hívásokkal.
• Védett /hello végpont. Ez az végpont visszaadja a hozzáférési jogkivonaton belüli name igény értékét.

Az anonim végpont hozzáadásához:

ASP.NET Core

A /Controllers mappa alatt hozzon létre egy PublicController.cs fájlt, majd adja hozzá az alábbi kódrészlethez:

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

A app.js fájlban adja hozzá a következő JavaScript kódot:

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

A védett végpont hozzáadásához:

ASP.NET Core

A /Controllers mappa alatt, adj hozzá egy HelloController.cs fájlt, majd add hozzá a következő kódhoz:

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

A HelloController vezérlőre az AuthorizeAttribute került alkalmazásra, amely csak hitelesített felhasználók számára korlátozza a hozzáférést.

A vezérlő is fel van díszítve a [RequiredScope("tasks.read")]-vel. A RequiredScopeAttribute ellenőrzi, hogy a webes API-t a megfelelő tartományokkal hívják meg, tasks.read.

Node.js

A app.js fájlban adja hozzá a következő JavaScript kódot:

// 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']});
    }
);

A /hello végpont először a passport.authenticate() függvényt hívja meg. Az azonosítási funkció kizárólag a hitelesített felhasználók számára korlátozza a hozzáférést.

Az autentikáció funkciója azt is ellenőrzi, hogy a webes API a megfelelő hatáskörökkel van-e meghívva. Az engedélyezett hatókörök a konfigurációs fájlban találhatók.

5. lépés: A webszerver konfigurálása

Fejlesztői környezetben állítsa be a webes API-t, hogy figyelje a bejövő HTTP vagy HTTPS kérések portszámát. Ebben a példában használja a 6000-es HTTP portot és a 6001-es HTTPS portot. A webes API alap URI-je http://localhost:6000 lesz HTTP-hez és https://localhost:6001 HTTPS-hez.

ASP.NET Core

Adja hozzá a következő JSON-részletet az appsettings.json fájlhoz.

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

Node.js

Adja hozzá a következő JavaScript kódot a app.js fájlhoz. Lehetőség van HTTP és HTTPS végpontok beállítására a Node alkalmazás számára.

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

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

6. lépés: A webes API konfigurálása

Adjon hozzá konfigurációkat egy konfigurációs fájlhoz. A fájl tartalmazza az Azure AD B2C identitásszolgáltatóval kapcsolatos információkat. A web API alkalmazás ezt az információt használja a webalkalmazás által átadott hozzáférési jogkivonat érvényességének ellenőrzésére, amelyet bearer tokenként továbbítanak.

ASP.NET Core

hu-HU: A projekt gyökérmappájában nyissa meg a appsettings.json fájlt, és adja hozzá a következő beállításokat:

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

A appsettings.json fájlban frissítse a következő tulajdonságokat:

Szakasz	Kulcs	Érték
AzureAdB2C	Példa	Azure AD B2C bérlőnevének első része (például, ).
AzureAdB2C	Szakterület	Az ön Azure AD B2C bérlő teljes bérlőnév (például, contoso.onmicrosoft.com).
AzureAdB2C	Ügyfélazonosító	A webes API alkalmazásazonosító. A megelőző diagramon ez az az alkalmazás, amelynek Alkalmazásazonosítója: 2. A webes API-alkalmazás regisztrációs azonosítójának megszerzéséről a Előfeltételek című részben olvashat.
AzureAdB2C	RegisztrációBejelentkezésIrányelvAzonosító	A felhasználói folyamatok vagy az egyéni irányelv. Ha szeretné megtudni, hogyan szerezheti be a felhasználói folyamatát vagy szabályzatát, tekintse meg a Előfeltételek című részt.

Node.js

A projekt gyökérmappájában hozzon létre egy config.json fájlt, majd adja hozzá a következő JSON részlethez:

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

A config.json fájlban frissítse a következő tulajdonságokat:

Szakasz	Kulcs	Érték
hitelesítő adatok	bérlőNeve	Az Azure AD B2C bérlő neve/tartománynév (például, contoso.onmicrosoft.com).
hitelesítő adatok	ügyfélazonosító	A webes API alkalmazásazonosító. A megelőző diagramon ez az az alkalmazás, amelynek Alkalmazásazonosítója: 2. A webes API-alkalmazás regisztrációs azonosítójának megszerzéséről a Előfeltételek című részben olvashat.
hitelesítő adatok	kibocsátó	A token kibocsátójának iss igényértéke. Alapértelmezés szerint az Azure AD B2C a tokent a következő formátumban adja vissza: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Cserélje le a <your-tenant-name> az Azure AD B2C bérlői nevének első részére. Helyettesítse a <your-tenant-ID> az Azure AD B2C bérlőazonosítójával.
irányelvek	szabályzat neve	A felhasználói folyamatok vagy az egyéni irányelv. Ha szeretné megtudni, hogyan szerezheti be a felhasználói folyamatát vagy szabályzatát, tekintse meg a Előfeltételek című részt.
erőforrás	kiterjedés	Az Ön webes API alkalmazásának regisztrációjának hatókörei. A web API hatókörének megismeréséhez tekintse meg az Előfeltételek részt.

7. lépés: A web API futtatása és tesztelése

Végül futtassa a webes API-t az Azure AD B2C környezet beállításaival.

ASP.NET Core

A parancssorban indítsa el a webalkalmazást a következő parancs futtatásával:

 dotnet run

A következő kimenetet kell látnia, ami azt jelenti, hogy az alkalmazása működik és készen áll a kérések fogadására.

Now listening on: http://localhost:6000

A program leállításához a parancshéjban válassza a Ctrl+C-t. Újra futtathatja az alkalmazást a node app.js parancs használatával.

Jótanács

Alternatívaként, a dotnet run parancs futtatásához használhatja a Visual Studio Code hibakeresőt. A Visual Studio Code beépített hibakeresője segít felgyorsítani a szerkesztési, fordítási és hibakeresési ciklusát.

Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/public címre. A böngészőablakban meg kell jelennie a következő szövegnek, a jelenlegi dátummal és idővel együtt.

Node.js

A parancssorban indítsa el a webalkalmazást a következő parancs futtatásával:

node app.js

A következő kimenetet kell látnia, ami azt jelenti, hogy az alkalmazása működik és készen áll a kérések fogadására.

Example app listening on port 6000!

A program leállításához a parancshéjban válassza a Ctrl+C-t. Újra futtathatja az alkalmazást a node app.js parancs használatával.

Jótanács

Alternatívaként, a node app.js parancs futtatásához használja a Visual Studio Code hibakeresőt. A Visual Studio Code beépített hibakeresője segít felgyorsítani a szerkesztési, fordítási és hibakeresési ciklusát.

Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/public címre. A böngészőablakban meg kell jelennie a következő szövegnek, a jelenlegi dátummal és idővel együtt.

8. lépés: A webes API meghívása az alkalmazásból

Próbálja meg elérni a védett webes API végpontot hozzáférési token nélkül. Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/hello címre. ** Az API egy jogosulatlan HTTP hibajelzést ad vissza, megerősítve, hogy a webes API védett egy hordozó tokennel.

Folytassa az alkalmazás beállítását, hogy felhívja a web API-t. Útmutatásért lásd a Előfeltételek részt.

Nézze meg ezt a videót, hogy megismerje a legjobb gyakorlatokat az Azure AD B2C és egy API integrálása során.

Kapcsolódó tartalom

Szerezze be a teljes példát a GitHub-on.

ASP.NET Core

• Szerezze meg a webes API-t a Microsoft identitás könyvtár használatával.

Node.js

• Szerezd be a webes API-t a Passport.js könyvtár használatával.