Povolení ověřování ve vlastním webovém rozhraní API pomocí Azure AD B2C

Pokud chcete autorizovat přístup k webovému rozhraní API, můžete obsluhovat pouze požadavky, které obsahují platný přístupový token, který azure Active Directory B2C (Azure AD B2C) řeší. V tomto článku se dozvíte, jak povolit autorizaci Azure AD B2C pro webové rozhraní API. Po dokončení kroků v tomto článku budou mít oprávnění k volání koncových bodů webového rozhraní API pouze uživatelé, kteří získají platný přístupový token.

Požadavky

Než začnete, přečtěte si jeden z následujících článků, který popisuje, jak nakonfigurovat ověřování pro aplikace, které volají webová rozhraní API. Potom podle kroků v tomto článku nahraďte ukázkové webové rozhraní API vlastním webovým rozhraním API.

• Konfigurace ověřování v ukázkové aplikaci ASP.NET Core
• Konfigurace ověřování v ukázkové jednostránkové aplikaci (SPA)

Přehled

Ověřování na základě tokenů zajišťuje, že požadavky na webové rozhraní API obsahují platný přístupový token.

Aplikace provede následující kroky:

1. Ověřuje uživatele pomocí Azure AD B2C.

2. Získá přístupový token s požadovanými oprávněními (obory) pro koncový bod webového rozhraní API.

3. Předává přístupový token jako nosný token v hlavičce ověřování požadavku HTTP pomocí tohoto formátu:

   Authorization: Bearer <access token>
   

Webové rozhraní API provede následující kroky:

1. Načte nosný token z autorizační hlavičky v požadavku HTTP.

2. Ověří token.

3. Ověří oprávnění (obory) v tokenu.

4. Načte deklarace identity kódované v tokenu (volitelné).

5. Reaguje na požadavek HTTP.

Přehled registrace aplikací

Pokud chcete aplikaci povolit přihlášení pomocí Azure AD B2C a volání webového rozhraní API, musíte zaregistrovat dvě aplikace v adresáři Azure AD B2C.

• Registrace webové, mobilní aplikace nebo aplikace SPA umožňuje aplikaci přihlásit se pomocí Azure AD B2C. Proces registrace aplikace vygeneruje ID aplikace, označované také jako ID klienta, které jednoznačně identifikuje vaši aplikaci (například ID aplikace: 1).

• Registrace webového rozhraní API umožňuje vaší aplikaci volat chráněné webové rozhraní API. Registrace zveřejňuje oprávnění webového rozhraní API (obory). Proces registrace aplikace vygeneruje ID aplikace, které jednoznačně identifikuje vaše webové rozhraní API (například ID aplikace: 2). Udělte aplikaci (ID aplikace: 1) oprávnění k oborům webového rozhraní API (ID aplikace: 2).

Registrace aplikací a architektura aplikací jsou popsány v následujícím diagramu:

Příprava vývojového prostředí

V dalších částech vytvoříte nový projekt webového rozhraní API. Vyberte programovací jazyk ASP.NET Core nebo Node.js. Ujistěte se, že máte počítač, na kterém běží některý z následujících softwaru:

ASP.NET Core

• Visual Studio Code
• Jazyk C# pro Visual Studio Code (nejnovější verze)
• Sada .NET 5.0 SDK

Node.js

• Visual Studio Code nebo jiný editor kódu
• Modul runtime Node.js

Krok 1: Vytvoření chráněného webového rozhraní API

Vytvořte nový projekt webového rozhraní API. Nejprve vyberte programovací jazyk, který chcete použít, ASP.NET Core nebo Node.js.

ASP.NET Core

Použijte příkaz dotnet new. Příkaz dotnet new vytvoří novou složku s názvem TodoList s prostředky projektu webového rozhraní API. Otevřete adresář a otevřete Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Po zobrazení výzvy k přidání požadovaných prostředků do projektu vyberte Ano.

Node.js

K vytvoření webového rozhraní API použijte Express for Node.js . Pokud chcete vytvořit webové rozhraní API, postupujte takto:

1. Vytvořte novou složku s názvem TodoList.
2. Ve složce TodoList vytvořte soubor s názvem app.js.
3. V příkazovém prostředí spusťte npm init -ypříkaz . Tímto příkazem vytvoříte pro svůj projekt Node.js výchozí soubor package.json.
4. V příkazovém prostředí spusťte npm install express. Uvedený příkaz nainstaluje architekturu Expressu.

Krok 2: Instalace závislostí

Přidejte knihovnu ověřování do projektu webového rozhraní API. Knihovna ověřování analyzuje hlavičku ověřování HTTP, ověří token a extrahuje deklarace identity. Další informace najdete v dokumentaci ke knihovně.

ASP.NET Core

Pokud chcete přidat knihovnu ověřování, nainstalujte balíček spuštěním následujícího příkazu:

dotnet add package Microsoft.Identity.Web

Node.js

Pokud chcete přidat knihovnu ověřování, nainstalujte balíčky spuštěním následujícího příkazu:

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

Balíček Morgan je middleware protokolovacího nástroje protokolu HTTP pro Node.js.

Krok 3: Zahájení knihovny ověřování

Přidejte potřebný kód pro zahájení knihovny ověřování.

ASP.NET Core

Otevřete Startup.cs a pak na začátek třídy přidejte následující using deklarace:

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

ConfigureServices(IServiceCollection services) Najděte funkci. Potom před services.AddControllers(); řádek kódu přidejte následující fragment kódu:

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 Najděte funkci. Pak bezprostředně za app.UseRouting(); řádek kódu přidejte následující fragment kódu:

app.UseAuthentication();

Po změně by měl váš kód vypadat jako následující fragment kódu:

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

Do souboru app.js přidejte následující kód JavaScriptu.

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

Krok 4: Přidání koncových bodů

Přidejte do webového rozhraní API dva koncové body:

• Anonymní /public koncový bod. Tento koncový bod vrátí aktuální datum a čas. Slouží k ladění webového rozhraní API pomocí anonymních volání.
• Chráněný /hello koncový bod. Tento koncový bod vrátí hodnotu name deklarace identity v rámci přístupového tokenu.

Přidání anonymního koncového bodu:

ASP.NET Core

Do složky /Controllers přidejte soubor PublicController.cs a pak ho přidejte do následujícího fragmentu kódu:

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

Do souboru app.js přidejte následující kód JavaScriptu:

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

Přidání chráněného koncového bodu:

ASP.NET Core

Do složky /Controllers přidejte soubor HelloController.cs a pak ho přidejte do následujícího kódu:

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

Kontroler HelloController je zdoben autorizovaným atributem AuthorizeAttribute, který omezuje přístup pouze na ověřené uživatele.

Kontroler je také zdobený [RequiredScope("tasks.read")]. RequiredScopeAttribute ověřuje, že webové rozhraní API je volána se správnými obory, tasks.read.

Node.js

Do souboru app.js přidejte následující kód JavaScriptu:

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

Koncový /hello bod nejprve zavolá passport.authenticate() funkci. Ověřovací funkce omezuje přístup jenom na ověřené uživatele.

Ověřovací funkce také ověřuje, že webové rozhraní API se volá se správnými obory. Povolené obory se nacházejí v konfiguračním souboru.

Krok 5: Konfigurace webového serveru

Ve vývojovém prostředí nastavte webové rozhraní API tak, aby naslouchala na příchozím čísle portu požadavků HTTP nebo HTTPS. V tomto příkladu použijte port HTTP 6000 a https port 6001. Základní identifikátor URI webového rozhraní API bude http://localhost:6000 pro HTTP a https://localhost:6001 HTTPS.

ASP.NET Core

Do souboru appsettings.json přidejte následující fragment kódu JSON.

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

Node.js

Do souboru app.js přidejte následující kód JavaScriptu. Pro aplikaci Node je možné nastavit koncové body HTTP a HTTPS.

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

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

Krok 6: Konfigurace webového rozhraní API

Přidejte konfigurace do konfiguračního souboru. Soubor obsahuje informace o vašem zprostředkovateli identity Azure AD B2C. Aplikace webového rozhraní API tyto informace používá k ověření přístupového tokenu, který webová aplikace předává jako nosný token.

ASP.NET Core

V kořenové složce projektu otevřete soubor appsettings.json a přidejte následující nastavení:

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

V souboru appsettings.json aktualizujte následující vlastnosti:

Oddíl	Key	Hodnota
AzureAdB2C	Instance	První část názvu tenanta Azure AD B2C (napříkladhttps://contoso.b2clogin.com).
AzureAdB2C	Doména	Úplný název tenanta Azure AD B2C (například contoso.onmicrosoft.com).
AzureAdB2C	ClientId	ID aplikace webového rozhraní API. V předchozím diagramu se jedná o aplikaci s ID aplikace: 2. Informace o tom, jak získat ID registrace aplikace webového rozhraní API, najdete v tématu Požadavky.
AzureAdB2C	SignUpSignInPolicyId	Toky uživatelů nebo vlastní zásady. Informace o tom, jak získat tok nebo zásady uživatele, najdete v tématu Požadavky.

Node.js

V kořenové složce projektu vytvořte soubor config.json a přidejte ho do následujícího fragmentu kódu JSON:

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

V souboru config.json aktualizujte následující vlastnosti:

Oddíl	Key	Hodnota
přihlašovací údaje	tenantName	Název nebo název domény vašeho tenanta Azure AD B2C (napříkladcontoso.onmicrosoft.com).
přihlašovací údaje	Clientid	ID aplikace webového rozhraní API. V předchozím diagramu se jedná o aplikaci s ID aplikace: 2. Informace o tom, jak získat ID registrace aplikace webového rozhraní API, najdete v tématu Požadavky.
přihlašovací údaje	issuer	Hodnota deklarace identity vystavitele iss tokenu. Azure AD B2C ve výchozím nastavení vrátí token v následujícím formátu: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Nahraďte <your-tenant-name> první částí názvu tenanta Azure AD B2C. Nahraďte <your-tenant-ID> ID tenanta Azure AD B2C.
Zásady	policyName	Toky uživatelů nebo vlastní zásady. Informace o tom, jak získat tok nebo zásady uživatele, najdete v tématu Požadavky.
resource	rozsah	Rozsahy registrace vaší aplikace webového rozhraní API Informace o tom, jak získat obor webového rozhraní API, najdete v tématu Požadavky.

Krok 7: Spuštění a otestování webového rozhraní API

Nakonec spusťte webové rozhraní API s nastavením prostředí Azure AD B2C.

ASP.NET Core

V příkazovém prostředí spusťte webovou aplikaci spuštěním následujícího příkazu:

 dotnet run

Měl by se zobrazit následující výstup, což znamená, že vaše aplikace je spuštěná a připravená přijímat požadavky.

Now listening on: http://localhost:6000

Pokud chcete program zastavit, v příkazovém prostředí vyberte Ctrl+C. Aplikaci můžete znovu spustit pomocí node app.js příkazu.

Tip

Případně můžete ke spuštění dotnet run příkazu použít ladicí program editoru Visual Studio Code. Integrovaný ladicí program editoru Visual Studio Code pomáhá urychlit úpravy, kompilaci a ladění smyčky.

Otevřete prohlížeč a přejděte na adresu http://localhost:6000/public. V okně prohlížeče by se měl zobrazit následující text spolu s aktuálním datem a časem.

Node.js

V příkazovém prostředí spusťte webovou aplikaci spuštěním následujícího příkazu:

node app.js

Měl by se zobrazit následující výstup, což znamená, že vaše aplikace je spuštěná a připravená přijímat požadavky.

Example app listening on port 6000!

Pokud chcete program zastavit, v příkazovém prostředí vyberte Ctrl+C. Aplikaci můžete znovu spustit pomocí node app.js příkazu.

Tip

Případně ke spuštění node app.js příkazu použijte ladicí program editoru Visual Studio Code. Integrovaný ladicí program editoru Visual Studio Code pomáhá urychlit úpravy, kompilaci a ladění smyčky.

Otevřete prohlížeč a přejděte na adresu http://localhost:6000/public. V okně prohlížeče by se měl zobrazit následující text spolu s aktuálním datem a časem.

Krok 8: Volání webového rozhraní API z vaší aplikace

Zkuste volat koncový bod chráněného webového rozhraní API bez přístupového tokenu. Otevřete prohlížeč a přejděte na adresu http://localhost:6000/hello. Rozhraní API vrátí neautorizovanou chybovou zprávu HTTP, která potvrzuje, že webové rozhraní API je chráněné nosným tokenem.

Pokračujte v konfiguraci aplikace tak, aby volala webové rozhraní API. Pokyny najdete v části Požadavky .

V tomto videu se dozvíte o některých osvědčených postupech při integraci Azure AD B2C s rozhraním API.

Další kroky

Získejte úplný příklad na GitHubu:

ASP.NET Core

• Získejte webové rozhraní API pomocí knihovny identit Microsoftu.

Node.js

• Získejte webové rozhraní API pomocí knihovny Passport.js.