Włączanie uwierzytelniania we własnym internetowym interfejsie API przy użyciu usługi Azure AD B2C

Aby autoryzować dostęp do internetowego interfejsu API, możesz obsługiwać tylko żądania zawierające prawidłowy token dostępu, który ma problemy z usługą Azure Active Directory B2C (Azure AD B2C). W tym artykule pokazano, jak włączyć autoryzację usługi Azure AD B2C do internetowego interfejsu API. Po wykonaniu kroków opisanych w tym artykule tylko użytkownicy, którzy uzyskują prawidłowy token dostępu, będą autoryzowani do wywoływania punktów końcowych internetowego interfejsu API.

Wymagania wstępne

Przed rozpoczęciem przeczytaj jeden z następujących artykułów, w którym omówiono sposób konfigurowania uwierzytelniania dla aplikacji wywołujących internetowe interfejsy API. Następnie wykonaj kroki opisane w tym artykule, aby zastąpić przykładowy internetowy interfejs API własnym internetowym interfejsem API.

• Konfigurowanie uwierzytelniania w przykładowej aplikacji ASP.NET Core
• Konfigurowanie uwierzytelniania w przykładowej aplikacji jednostronicowej (SPA)

Omówienie

Uwierzytelnianie oparte na tokenach zapewnia, że żądania do internetowego interfejsu API zawierają prawidłowy token dostępu.

Aplikacja wykonuje następujące czynności:

1. Uwierzytelnia użytkowników za pomocą usługi Azure AD B2C.

2. Uzyskuje token dostępu z wymaganymi uprawnieniami (zakresami) dla internetowego punktu końcowego interfejsu API.

3. Przekazuje token dostępu jako token elementu nośnego w nagłówku uwierzytelniania żądania HTTP przy użyciu następującego formatu:

   Authorization: Bearer <access token>
   

Internetowy interfejs API wykonuje następujące kroki:

1. Odczytuje token elementu nośnego z nagłówka autoryzacji w żądaniu HTTP.

2. Weryfikuje token.

3. Weryfikuje uprawnienia (zakresy) w tokenie.

4. Odczytuje oświadczenia zakodowane w tokenie (opcjonalnie).

5. Odpowiada na żądanie HTTP.

Omówienie rejestracji aplikacji

Aby umożliwić aplikacji logowanie się za pomocą usługi Azure AD B2C i wywoływanie internetowego interfejsu API, musisz zarejestrować dwie aplikacje w katalogu usługi Azure AD B2C.

• Rejestracja aplikacji internetowej, mobilnej lub SPA umożliwia aplikacji logowanie się za pomocą usługi Azure AD B2C. Proces rejestracji aplikacji generuje identyfikator aplikacji, znany również jako identyfikator klienta, który jednoznacznie identyfikuje aplikację (na przykład identyfikator aplikacji: 1).

• Rejestracja internetowego interfejsu API umożliwia aplikacji wywoływanie chronionego internetowego interfejsu API. Rejestracja uwidacznia uprawnienia internetowego interfejsu API (zakresy). Proces rejestracji aplikacji generuje identyfikator aplikacji, który jednoznacznie identyfikuje internetowy interfejs API (na przykład identyfikator aplikacji: 2). Przyznaj aplikacji (identyfikator aplikacji: 1) uprawnienia do zakresów internetowego interfejsu API (identyfikator aplikacji: 2).

Rejestracje aplikacji i architektura aplikacji zostały opisane na poniższym diagramie:

przygotowywanie środowiska programistycznego

W następnych sekcjach utworzysz nowy projekt internetowego interfejsu API. Wybierz język programowania, ASP.NET Core lub Node.js. Upewnij się, że masz komputer z uruchomionym jednym z następujących programów:

ASP.NET Core

• Visual Studio Code
• Język C# dla programu Visual Studio Code (najnowsza wersja)
• Zestaw .NET SDK 5.0

Node.js

• Visual Studio Code lub inny edytor kodu
• Środowisko uruchomieniowe Node.js

Krok 1. Tworzenie chronionego internetowego interfejsu API

Utwórz nowy projekt internetowego interfejsu API. Najpierw wybierz język programowania, którego chcesz użyć, ASP.NET Core lub Node.js.

ASP.NET Core

Użyj polecenia dotnet new. Polecenie dotnet new tworzy nowy folder o nazwie TodoList z elementami zawartości projektu internetowego interfejsu API. Otwórz katalog, a następnie otwórz program Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Po wyświetleniu monitu o dodanie wymaganych zasobów do projektu wybierz pozycję Tak.

Node.js

Tworzenie internetowego interfejsu API za pomocą biblioteki Express for Node.js . Aby utworzyć internetowy interfejs API, wykonaj następujące czynności:

1. Utwórz nowy folder o nazwie TodoList.
2. W folderze TodoList utwórz plik o nazwie app.js.
3. W powłoce poleceń uruchom polecenie npm init -y. To polecenie tworzy domyślny plik package.json dla projektu platformy Node.js.
4. W powłoce poleceń uruchom polecenie npm install express. To polecenie powoduje zainstalowanie struktury Express.

Krok 2. Instalowanie zależności

Dodaj bibliotekę uwierzytelniania do projektu internetowego interfejsu API. Biblioteka uwierzytelniania analizuje nagłówek uwierzytelniania HTTP, weryfikuje token i wyodrębnia oświadczenia. Aby uzyskać więcej informacji, zapoznaj się z dokumentacją biblioteki.

ASP.NET Core

Aby dodać bibliotekę uwierzytelniania, zainstaluj pakiet, uruchamiając następujące polecenie:

dotnet add package Microsoft.Identity.Web

Node.js

Aby dodać bibliotekę uwierzytelniania, zainstaluj pakiety, uruchamiając następujące polecenie:

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

Pakiet morgan to oprogramowanie pośredniczące rejestratora żądań HTTP dla środowiska Node.js.

Krok 3. Inicjowanie biblioteki uwierzytelniania

Dodaj niezbędny kod, aby zainicjować bibliotekę uwierzytelniania.

ASP.NET Core

Otwórz plik Startup.cs , a następnie na początku klasy dodaj następujące using deklaracje:

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

ConfigureServices(IServiceCollection services) Znajdź funkcję. Następnie przed wierszem services.AddControllers(); kodu dodaj następujący fragment kodu:

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 Znajdź funkcję. Następnie bezpośrednio po app.UseRouting(); wierszu kodu dodaj następujący fragment kodu:

app.UseAuthentication();

Po zmianie kod powinien wyglądać podobnie do następującego fragmentu kodu:

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

Dodaj następujący kod JavaScript do pliku app.js .

// 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. Dodawanie punktów końcowych

Dodaj dwa punkty końcowe do internetowego interfejsu API:

• Anonimowy /public punkt końcowy. Ten punkt końcowy zwraca bieżącą datę i godzinę. Służy do debugowania internetowego interfejsu API za pomocą wywołań anonimowych.
• Chroniony /hello punkt końcowy. Ten punkt końcowy zwraca wartość name oświadczenia w tokenie dostępu.

Aby dodać anonimowy punkt końcowy:

ASP.NET Core

W folderze /Controllers dodaj plik PublicController.cs , a następnie dodaj go do następującego fragmentu kodu:

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

W pliku app.js dodaj następujący kod JavaScript:

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

Aby dodać chroniony punkt końcowy:

ASP.NET Core

W folderze /Controllers dodaj plik HelloController.cs , a następnie dodaj go do następującego kodu:

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 jest ozdobiony atrybutem AuthorizeAttribute, który ogranicza dostęp tylko do uwierzytelnionych użytkowników.

Kontroler jest również ozdobiony elementem [RequiredScope("tasks.read")]. Element RequiredScopeAttribute sprawdza, czy internetowy interfejs API jest wywoływany z odpowiednimi zakresami: tasks.read.

Node.js

W pliku app.js dodaj następujący kod JavaScript:

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

Punkt /hello końcowy najpierw wywołuje passport.authenticate() funkcję . Funkcja uwierzytelniania ogranicza dostęp tylko do uwierzytelnionych użytkowników.

Funkcja uwierzytelniania sprawdza również, czy internetowy interfejs API jest wywoływany z odpowiednimi zakresami. Dozwolone zakresy znajdują się w pliku konfiguracji.

Krok 5. Konfigurowanie serwera internetowego

W środowisku projektowym ustaw internetowy interfejs API do nasłuchiwania przychodzących żądań HTTP lub HTTPS numer portu. W tym przykładzie użyj portu HTTP 6000 i portu HTTPS 6001. Podstawowy identyfikator URI internetowego interfejsu API będzie przeznaczony http://localhost:6000 dla protokołu HTTP i https://localhost:6001 HTTPS.

ASP.NET Core

Dodaj następujący fragment kodu JSON do pliku appsettings.json .

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

Node.js

Dodaj następujący kod JavaScript do pliku app.js . Istnieje możliwość skonfigurowania punktów końcowych HTTP i HTTPS dla aplikacji Node.

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

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

Krok 6. Konfigurowanie internetowego interfejsu API

Dodaj konfiguracje do pliku konfiguracji. Plik zawiera informacje o dostawcy tożsamości usługi Azure AD B2C. Aplikacja internetowego interfejsu API używa tych informacji do sprawdzania poprawności tokenu dostępu, który aplikacja internetowa przekazuje jako token elementu nośnego.

ASP.NET Core

W folderze głównym projektu otwórz plik appsettings.json , a następnie dodaj następujące ustawienia:

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

W pliku appsettings.json zaktualizuj następujące właściwości:

Sekcja	Key	Wartość
AzureAdB2C	Wystąpienie	Pierwsza część nazwy dzierżawy usługi Azure AD B2C (na przykład https://contoso.b2clogin.com).
AzureAdB2C	Domain	Pełna nazwa dzierżawy usługi Azure AD B2C (na przykład contoso.onmicrosoft.com).
AzureAdB2C	ClientId	Identyfikator aplikacji internetowego interfejsu API. Na powyższym diagramie jest to aplikacja o identyfikatorze aplikacji: 2. Aby dowiedzieć się, jak uzyskać identyfikator rejestracji aplikacji internetowego interfejsu API, zobacz Wymagania wstępne.
AzureAdB2C	SignUpSignInPolicyId	Przepływy użytkownika lub zasady niestandardowe. Aby dowiedzieć się, jak uzyskać przepływ użytkownika lub zasady, zobacz Wymagania wstępne.

Node.js

W folderze głównym projektu utwórz plik config.json , a następnie dodaj go do następującego fragmentu kodu 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"
    }
}

W pliku config.json zaktualizuj następujące właściwości:

Sekcja	Key	Wartość
poświadczenia	tenantName	Nazwa dzierżawy/nazwa domeny usługi Azure AD B2C (na przykład contoso.onmicrosoft.com).
poświadczenia	Clientid	Identyfikator aplikacji internetowego interfejsu API. Na powyższym diagramie jest to aplikacja o identyfikatorze aplikacji: 2. Aby dowiedzieć się, jak uzyskać identyfikator rejestracji aplikacji internetowego interfejsu API, zobacz Wymagania wstępne.
poświadczenia	issuer	Wartość oświadczenia wystawcy iss tokenu. Domyślnie usługa Azure AD B2C zwraca token w następującym formacie: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Zastąp <your-tenant-name> element pierwszą częścią nazwy dzierżawy usługi Azure AD B2C. Zastąp <your-tenant-ID> element identyfikatorem dzierżawy usługi Azure AD B2C.
policies	policyName	Przepływy użytkownika lub zasady niestandardowe. Aby dowiedzieć się, jak uzyskać przepływ użytkownika lub zasady, zobacz Wymagania wstępne.
zasób	zakres	Zakresy rejestracji aplikacji internetowego interfejsu API. Aby dowiedzieć się, jak uzyskać zakres internetowego interfejsu API, zobacz Wymagania wstępne.

Krok 7. Uruchamianie i testowanie internetowego interfejsu API

Na koniec uruchom internetowy interfejs API przy użyciu ustawień środowiska usługi Azure AD B2C.

ASP.NET Core

W powłoce poleceń uruchom aplikację internetową, uruchamiając następujące polecenie:

 dotnet run

Powinny zostać wyświetlone następujące dane wyjściowe, co oznacza, że aplikacja jest uruchomiona i gotowa do odbierania żądań.

Now listening on: http://localhost:6000

Aby zatrzymać program, w powłoce poleceń wybierz klawisze Ctrl+C. Aplikację można ponownie uruchomić za pomocą node app.js polecenia .

Napiwek

Alternatywnie, aby uruchomić dotnet run polecenie, możesz użyć debugera programu Visual Studio Code. Wbudowany debuger programu Visual Studio Code pomaga przyspieszyć edytowanie, kompilowanie i pętlę debugowania.

Otwórz przeglądarkę i przejdź pod adres http://localhost:6000/public. W oknie przeglądarki powinien zostać wyświetlony następujący tekst wraz z bieżącą datą i godziną.

Node.js

W powłoce poleceń uruchom aplikację internetową, uruchamiając następujące polecenie:

node app.js

Powinny zostać wyświetlone następujące dane wyjściowe, co oznacza, że aplikacja jest uruchomiona i gotowa do odbierania żądań.

Example app listening on port 6000!

Aby zatrzymać program, w powłoce poleceń wybierz klawisze Ctrl+C. Aplikację można ponownie uruchomić za pomocą node app.js polecenia .

Napiwek

Alternatywnie, aby uruchomić node app.js polecenie, użyj debugera programu Visual Studio Code. Wbudowany debuger programu Visual Studio Code pomaga przyspieszyć edytowanie, kompilowanie i pętlę debugowania.

Otwórz przeglądarkę i przejdź pod adres http://localhost:6000/public. W oknie przeglądarki powinien zostać wyświetlony następujący tekst wraz z bieżącą datą i godziną.

Krok 8. Wywoływanie internetowego interfejsu API z aplikacji

Spróbuj wywołać chroniony internetowy punkt końcowy interfejsu API bez tokenu dostępu. Otwórz przeglądarkę i przejdź pod adres http://localhost:6000/hello. Interfejs API zwróci nieautoryzowany komunikat o błędzie HTTP, potwierdzając, że internetowy interfejs API jest chroniony za pomocą tokenu elementu nośnego.

Kontynuuj konfigurowanie aplikacji w celu wywołania internetowego interfejsu API. Aby uzyskać wskazówki, zobacz sekcję Wymagania wstępne .

Obejrzyj ten film wideo, aby dowiedzieć się więcej o najlepszych rozwiązaniach dotyczących integracji usługi Azure AD B2C z interfejsem API.

Następne kroki

Uzyskaj kompletny przykład w witrynie GitHub:

ASP.NET Core

• Pobierz internetowy interfejs API przy użyciu biblioteki tożsamości firmy Microsoft.

Node.js

• Pobierz internetowy interfejs API przy użyciu biblioteki Passport.js.