Hitelesítés engedélyezése a saját webes API-ban az Azure AD B2C használatával

A webes API-khoz való hozzáférés engedélyezéséhez csak olyan kéréseket tud kiszolgálni, amelyek az Azure Active Directory B2C (Azure AD B2C) által problémákat okozó érvényes hozzáférési jogkivonatot tartalmaznak. Ez a cikk bemutatja, hogyan engedélyezheti az Azure AD B2C-hitelesítést a webes API-ban. A cikkben ismertetett lépések elvégzése után csak azok a felhasználók jogosultak a webes API-végpontok meghívására, akik érvényes hozzáférési jogkivonatot szereznek be.

Előfeltételek

Mielőtt hozzákezdene, olvassa el az alábbi cikkek egyikét, amelyek a webes API-kat hívó alkalmazások hitelesítésének konfigurálását ismertetik. Ezután kövesse a cikkben leírt lépéseket a minta webes API saját webes API-ra való lecseréléséhez.

• Hitelesítés konfigurálása minta ASP.NET Core-alkalmazásban
• Hitelesítés konfigurálása egy egyoldalas mintaalkalmazásban (SPA)

Áttekintés

A jogkivonatalapú hitelesítés biztosítja, hogy a webes API-hoz érkező kérések érvényes hozzáférési jogkivonatot tartalmazzanak.

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

1. Az Azure AD B2C-vel hitelesíti a felhasználókat.

2. A webes API-végponthoz szükséges engedélyekkel (hatókörökkel) rendelkező hozzáférési jogkivonatot szerez be.

3. A http-kérés hitelesítési fejlécében a hozzáférési jogkivonatot az alábbi formátumban adja át tulajdonosi jogkivonatként:

   Authorization: Bearer <access token>
   

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

1. Beolvassa a tulajdonosi jogkivonatot a HTTP-kérelem engedélyezési fejlécéből.

2. Ellenőrzi a jogkivonatot.

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

4. Beolvassa a jogkivonatban kódolt jogcímeket (nem kötelező).

5. Válaszol a HTTP-kérésre.

Alkalmazásregisztráció áttekintése

Ahhoz, hogy az alkalmazás bejelentkezhessen az Azure AD B2C-vel, és meghívjon egy webes API-t, két alkalmazást kell regisztrálnia az Azure AD B2C címtárban.

• A webes, mobil- vagy SPA-alkalmazásregisztrációval az alkalmazás bejelentkezhet az Azure AD B2C-vel. Az alkalmazásregisztrációs folyamat létrehoz egy alkalmazásazonosítót, más néven ügyfélazonosítót, amely egyedileg azonosítja az alkalmazást (például: 1. alkalmazásazonosító).

• 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ásregisztrációs folyamat létrehoz egy alkalmazásazonosítót, amely egyedileg azonosítja a webes API-t (például alkalmazásazonosító: 2). Adjon engedélyt az alkalmazásnak (alkalmazásazonosító: 1) a webes API-hatókörökhöz (alkalmazásazonosító: 2).

Az alkalmazásregisztrációkat és az alkalmazásarchitektúrát az alábbi diagram ismerteti:

A fejlesztő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 nyelvet, ASP.NET Core-t vagy Node.js-t. Győződjön meg arról, hogy rendelkezik olyan számítógéppel, amely 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 más kódszerkesztő
• Node.js futtatókörnyezet

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 az dotnet new parancsot. A dotnet new parancs létrehoz egy TodoList nevű új mappát a webes API-projektegységekkel. Nyissa meg a könyvtárat, majd nyissa meg a Visual Studio Code-ot.

dotnet new webapi -o TodoList
cd TodoList
code . 

Amikor a rendszer kéri, hogy "adja hozzá a szükséges eszközöket a projekthez", válassza az Igen lehetőséget.

Node.js

Az Express for Node.js használatával webes API-t hozhat létre. Webes API létrehozásához tegye a következőket:

1. Hozzon létre egy TodoList nevű új mappát.
2. A TodoList mappában hozzon létre egy app.js nevű fájlt.
3. Futtassa npm init -ya parancshéjban. Ez a parancs egy alapértelmezett package.json fájlt hoz létre a Node.js-projekthez.
4. A parancshéjban futtassa a npm install express parancsot. Ez a parancs az Express keretrendszert telepíti.

2. lépés: A függőségek telepítése

Adja hozzá a hitelesítési kódtárat a webes API-projekthez. A hitelesítési kódtár elemzi a HTTP-hitelesítési fejlécet, ellenőrzi a jogkivonatot, és kinyeri a jogcímeket. További információkért tekintse át a könyvtár dokumentációját.

ASP.NET Core

A hitelesítési kódtár hozzáadásához telepítse a csomagot az alábbi parancs futtatásával:

dotnet add package Microsoft.Identity.Web

Node.js

A hitelesítési kódtá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ésnaplózó köztes szoftver a Node.js-hez.

3. lépés: A hitelesítési kódtár kezdeményezése

Adja hozzá a hitelesítési kódtár elindításához szükséges kódot.

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 függvényt ConfigureServices(IServiceCollection services) . 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 függvényt Configure . Ezután közvetlenül a app.UseRouting(); kódsor után adja hozzá a következő kódrészletet:

app.UseAuthentication();

A módosítás után a kódnak a következő kódrészlethez hasonlóan 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 az 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: A végpontok hozzáadása

Adjon hozzá két végpontot a webes API-hoz:

• Névtelen /public végpont. Ez a végpont az aktuális dátumot és időt adja vissza. Segítségével névtelen hívásokkal hibakeresést végezhet a webes API-val.
• Védett /hello végpont. Ez a végpont a jogcím értékét adja vissza a name hozzáférési jogkivonaton belül.

A névtelen végpont hozzáadása:

ASP.NET Core

A /Controllers mappában vegyen fel egy PublicController.cs fájlt, majd adja hozzá a következő 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

Az 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ása:

ASP.NET Core

A /Controllers mappában adjon hozzá egy HelloController.cs fájlt, majd adja 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őt az AuthorizeAttribute díszíti, amely csak a hitelesített felhasználók hozzáférését korlátozza.

A vezérlőt [RequiredScope("tasks.read")]a . A RequiredScopeAttribute ellenőrzi, hogy a webes API a megfelelő hatókörökkel van-e meghívva. tasks.read

Node.js

Az 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 meghívja a függvényt passport.authenticate() . A hitelesítési függvény csak a hitelesített felhasználók hozzáférését korlátozza.

A hitelesítési függvény azt is ellenőrzi, hogy a webes API a megfelelő hatókö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 webkiszolgáló konfigurálása

Fejlesztői környezetben állítsa be a webes API-t a bejövő HTTP- vagy HTTPS-kérelmek portszámának figyelésére. Ebben a példában a HTTP-port 6000-et és a HTTPS-portot 6001-et használjuk. A webes API alap URI-ja HTTP-hez és https://localhost:6001 HTTPS-hez leszhttp://localhost:6000.

ASP.NET Core

Adja hozzá a következő JSON-kódré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 az app.js fájlhoz . A csomópontalkalmazásHOZ HTTP- és HTTPS-végpontok is beállíthatók.

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

Konfigurációk hozzáadása konfigurációs fájlhoz. A fájl információkat tartalmaz az Azure AD B2C-identitásszolgáltatóról. A web API-alkalmazás ezen információk alapján ellenőrzi a webalkalmazás által tulajdonosi jogkivonatként áthaladó hozzáférési jogkivonatot.

ASP.NET Core

A projekt gyökérmappájában nyissa meg az appsettings.json fájlt, majd 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
}

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

Szakasz	Key	Érték
AzureAdB2C	Példány	Az Azure AD B2C-bérlő nevének első része (például https://contoso.b2clogin.com).
AzureAdB2C	Tartomány	Az Azure AD B2C-bérlő teljes bérlőneve (például contoso.onmicrosoft.com).
AzureAdB2C	ClientID	A webes API-alkalmazás azonosítója. Az előző ábrán ez az alkalmazás a következő alkalmazásazonosítóval: 2. A webes API-alkalmazásregisztrációs azonosító lekéréséről az előfeltételek című témakörben olvashat.
AzureAdB2C	SignUpSignInPolicyId	A felhasználói folyamatok vagy egyéni szabályzatok. A felhasználói folyamat vagy szabályzat beszerzésének módjáról az előfeltételek című témakörben olvashat.

Node.js

A projekt gyökérmappájában hozzon létre egy config.json fájlt, majd adja hozzá a következő JSON-kódré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	Key	Érték
hitelesítő adatok	tenantName	Az Azure AD B2C-bérlő neve/tartományneve (például contoso.onmicrosoft.com).
hitelesítő adatok	clientID	A webes API-alkalmazás azonosítója. Az előző ábrán ez az alkalmazás a következő alkalmazásazonosítóval: 2. A webes API-alkalmazásregisztrációs azonosító lekéréséről az előfeltételek című témakörben olvashat.
hitelesítő adatok	Kibocsátó	A jogkivonat-kiállító iss jogcímértéke. Az Azure AD B2C alapértelmezés szerint a következő formátumban adja vissza a jogkivonatot: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Cserélje le <your-tenant-name> az Azure AD B2C-bérlő nevének első részére. Cserélje le <your-tenant-ID> az Azure AD B2C-bérlőazonosítóját.
policies	policyName	A felhasználói folyamatok vagy egyéni szabályzatok. A felhasználói folyamat vagy szabályzat beszerzésének módjáról az előfeltételek című témakörben olvashat.
erőforrás	scope	A webes API-alkalmazásregisztráció hatókörei. A webes API-hatókör beszerzéséről az előfeltételek című témakörben olvashat.

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

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

ASP.NET Core

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

 dotnet run

A következő kimenetnek kell megjelennie, ami azt jelenti, hogy az alkalmazás 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 billentyűkombinációt. A parancs használatával újrafuttathatja az node app.js alkalmazást.

Tipp.

A parancs futtatásához használhatja a dotnet runVisual Studio Code hibakeresőt is. A Visual Studio Code beépített hibakeresője segít felgyorsítani a szerkesztési, fordítási és hibakeresési ciklust.

Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/public címre. A böngészőablakban az alábbi szövegnek kell megjelennie az aktuális dátummal és időponttal együtt.

Node.js

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

node app.js

A következő kimenetnek kell megjelennie, ami azt jelenti, hogy az alkalmazás 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 billentyűkombinációt. A parancs használatával újrafuttathatja az node app.js alkalmazást.

Tipp.

A parancs futtatásához használja a node app.jsVisual 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 ciklust.

Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/public címre. A böngészőablakban az alábbi szövegnek kell megjelennie az aktuális dátummal és időponttal együtt.

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

Próbálja meg hozzáférési jogkivonat nélkül meghívni a védett webes API-végpontot. Nyisson meg egy böngészőt, és ugorjon a http://localhost:6000/hello címre. Az API egy jogosulatlan HTTP-hibaüzenetet ad vissza, amely megerősíti, hogy a webes API védett egy tulajdonosi jogkivonattal.

Folytassa az alkalmazás konfigurálását a webes API meghívásához. Útmutatásért tekintse meg az Előfeltételek szakaszt .

Ebből a videóból megismerhet néhány ajánlott eljárást az Azure AD B2C API-val való integrálása során.

További lépések

Szerezze be a teljes példát a GitHubon:

ASP.NET Core

• A webes API lekérése a Microsoft identitástárával.

Node.js

• Szerezze be a webes API-t a Passport.js kódtár használatával.