Megosztás a következőn keresztül:


A Identity használata az SLA-khoz készült webes API-háttérrendszer védelméhez

Jegyzet

Ez nem a cikk legújabb verziója. Az aktuális kiadásról a cikk .NET 10-es verziójában olvashat.

Figyelmeztetés

A ASP.NET Core ezen verziója már nem támogatott. További információ: .NET és .NET Core támogatási szabályzat. Az aktuális kiadáshoz lásd ennek a cikknek a .NET 9-es verzióját.

ASP.NET Core Identity hitelesítést, engedélyezést és identitáskezelést kezelő API-kat biztosít. Az API-k lehetővé teszik egy webes API-háttérrendszer végpontjainak védelmét cookie-alapú hitelesítéssel. A jogkivonat-alapú beállítás olyan ügyfelek számára érhető el, akik nem tudnak cookie-kat használni, de ennek használatakor Ön felelős a jogkivonatok biztonságának biztosításáért. Azt javasoljuk, hogy böngészőalapú alkalmazásokhoz használjon cookie-kat, mert alapértelmezés szerint a böngésző automatikusan kezeli őket anélkül, hogy a JavaScriptbe irányítja őket.

Ez a cikk bemutatja, hogyan használható a Identity egy webes API-háttérrendszer védelmére olyan SLA-khoz, mint az Angular, a React és a Vue alkalmazások. Ugyanezekkel a háttérbeli API-kkal védhetők Blazor WebAssembly alkalmazások.

Előfeltételek

Az ebben a cikkben ismertetett lépések hitelesítést és engedélyezést adnak hozzá egy ASP.NET Core Web API-alkalmazáshoz, amely:

  • Még nincs konfigurálva hitelesítésre.
  • Cél net8.0 vagy újabb.
  • Lehet minimális API vagy vezérlőalapú API.

A cikkben szereplő tesztelési utasítások némelyike a projektsablonban található Swagger felhasználói felületet használja. A Swagger felhasználói felülete nem szükséges a Identity webes API-háttérrendszerrel való használatához.

NuGet-csomagok telepítése

Telepítse a következő NuGet-csomagokat:

Az első lépések leggyorsabb módja a memórián belüli adatbázis használata.

Később módosítsa az adatbázist SQLite-ra vagy SQL Serverre a felhasználói adatok munkamenetek közötti mentéséhez tesztelés vagy éles használat esetén. Ez némi összetettséget okoz a memória alapú megoldáshoz képest, mivel az adatbázist a migrációkáltal kell létrehozni, ahogyan az a EF Core bevezető oktatóanyagbanlátható.

Telepítse ezeket a csomagokat a NuGet csomagkezelővel a Visual Studio-ban, vagy a dotnet add package CLI paranccsal.

IdentityDbContext létrehozása

Adjon hozzá egy ApplicationDbContext nevű osztályt, amely örököl a IdentityDbContext<TUser>-ből.

using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.AspNetCore.Identity;
using Microsoft.EntityFrameworkCore;

public class ApplicationDbContext : IdentityDbContext<IdentityUser>
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options) :
        base(options)
    { }
}

A megjelenő kód egy speciális konstruktort biztosít, amely lehetővé teszi az adatbázis konfigurálását különböző környezetekhez.

Az alábbi using irányelvek közül szükség szerint vegyen fel egy vagy több utasítást az ezekben a lépésekben látható kód hozzáadásakor.

using Microsoft.AspNetCore.Identity;
using Microsoft.AspNetCore.Identity.EntityFrameworkCore;
using Microsoft.EntityFrameworkCore;

A EF Core környezet konfigurálása

Ahogy korábban már említettük, az első lépések legegyszerűbb módja a memórián belüli adatbázis használata. A memórián belül minden futtatás egy friss adatbázissal kezdődik, és nincs szükség migrálásra. A WebApplication.CreateBuilder(args)hívása után adja hozzá a következő kódot, amely konfigurálja a Identity memórián belüli adatbázis használatára:

builder.Services.AddDbContext<ApplicationDbContext>(
    options => options.UseInMemoryDatabase("AppDb"));

Ha felhasználói adatokat szeretne menteni a munkamenetek között tesztelés vagy éles használat esetén, módosítsa az adatbázist később SQLite vagy SQL Serverre.

Szolgáltatások hozzáadása a Identity tárolóhoz

A WebApplication.CreateBuilder(args)hívás után hívja meg a AddAuthorization-et a szolgáltatások hozzáadásához a függőséginjektáló (DI) tárolóhoz.

builder.Services.AddAuthorization();

Identity API-k aktiválása

A WebApplication.CreateBuilder(args)hívása után hívja meg AddIdentityApiEndpoints<TUser>(IServiceCollection) és AddEntityFrameworkStores<TContext>(IdentityBuilder).

builder.Services.AddIdentityApiEndpoints<IdentityUser>()
    .AddEntityFrameworkStores<ApplicationDbContext>();

Alapértelmezés szerint a cookie-k és a saját fejlesztésű tokenek is aktiválódnak. A cookie-k és jogkivonatok akkor kerülnek kiadásra bejelentkezéskor, ha a bejelentkezési végpont useCookies lekérdezési sztring paramétere true.

A(z) Identity útvonalak megjelenítése

A builder.Build()hívása után hívja meg a MapIdentityApi<TUser>(IEndpointRouteBuilder) a Identity végpontok leképezéséhez:

app.MapIdentityApi<IdentityUser>();

Kijelölt végpontok biztonságossá tétele

Egy végpont védelméhez használja az útvonalat meghatározó RequireAuthorization hívás Map{Method} bővítménymetódusát. Például:

app.MapGet("/weatherforecast", (HttpContext httpContext) =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        {
            Date = DateOnly.FromDateTime(DateTime.Now.AddDays(index)),
            TemperatureC = Random.Shared.Next(-20, 55),
            Summary = summaries[Random.Shared.Next(summaries.Length)]
        })
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast")
.WithOpenApi()
.RequireAuthorization();

A RequireAuthorization metódus a következőket is lehetővé teszi:

  • Biztonságos Swagger felhasználói felületi végpontok, az alábbi példában látható módon:

    app.MapSwagger().RequireAuthorization();
    
  • Az alábbi példa bemutatja, hogyan lehet egy bizonyos igény vagy engedély révén biztosítani valamit.

    .RequireAuthorization("Admin");
    

Egy vezérlőalapú webes API-projektben a végpontok biztonságossá tételéhez alkalmazza a [Authorize] attribútumot egy vezérlőre vagy műveletre.

Az API tesztelése

A hitelesítés tesztelésének gyors módja a memóriabeli adatbázis és a projektsablonban található Swagger felhasználói felület használata. Az alábbi lépések bemutatják, hogyan tesztelheti az API-t a Swagger felhasználói felületén. Győződjön meg arról, hogy a Swagger felhasználói felületi végpontjai nincsenek biztonságban.

Biztonságos végpont elérésének kísérlete

  • Futtassa az alkalmazást, és lépjen a Swagger felhasználói felületére.
  • Bontsa ki a biztonságos végpontot, például /weatherforecast a webes API-sablon által létrehozott projektben.
  • Válassza Próbálja kilehetőséget.
  • Válassza ki a elemet, hajtsa végre aműveletet. A válasz 401 - not authorized.

Tesztregisztráció

  • Bontsa ki /register, és válassza a Próbálja kilehetőséget.

  • A felhasználói felület Paraméterek szakaszában megjelenik egy mintakérés törzse:

    {
      "email": "string",
      "password": "string"
    }
    
  • Cserélje le a "karakterláncot" érvényes e-mail-címre és jelszóra, majd válassza a Végrehajtáslehetőséget.

    Az alapértelmezett jelszóérvényesítési szabályok betartásához a jelszónak legalább hat karakter hosszúságúnak kell lennie, és tartalmaznia kell a következő karakterek legalább egyikét:

    • Nagybetű
    • Kisbetű
    • Numerikus számjegy
    • Nem alfanumerikus karakter

    Ha érvénytelen e-mail-címet vagy rossz jelszót ad meg, az eredmény tartalmazza az érvényesítési hibákat. Íme egy példa egy ellenőrzési hibákkal rendelkező választörzsre:

    {
      "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
      "title": "One or more validation errors occurred.",
      "status": 400,
      "errors": {
        "PasswordTooShort": [
          "Passwords must be at least 6 characters."
        ],
        "PasswordRequiresNonAlphanumeric": [
          "Passwords must have at least one non alphanumeric character."
        ],
        "PasswordRequiresDigit": [
          "Passwords must have at least one digit ('0'-'9')."
        ],
        "PasswordRequiresLower": [
          "Passwords must have at least one lowercase ('a'-'z')."
        ]
      }
    }
    

    A hibák ProblemDetails formátumban jelennek meg, hogy az ügyfél elemezhesse őket, és szükség szerint megjeleníthesse az érvényesítési hibákat.

    A sikeres regisztráció 200 - OK választ eredményez.

Bejelentkezés tesztelése

  • Bontsa ki /login, és válassza a Próbálja kilehetőséget. A példakérés törzse két további paramétert jelenít meg:

    {
      "email": "string",
      "password": "string",
      "twoFactorCode": "string",
      "twoFactorRecoveryCode": "string"
    }
    

    Ehhez a példához nincs szükség további JSON-tulajdonságokra, ezért törölhetők. Állítsa useCookiestrueértékre.

  • Cserélje le a "karakterláncot" a regisztrációhoz használt e-mail címre és jelszóra, majd válassza a Végrehajtásgombot.

    A sikeres bejelentkezés 200 - OK választ eredményez, a válasz fejlécében pedig egy cookie.

A biztonságos végpont újratesztelése

A sikeres bejelentkezés után futtassa újra a biztonságos végpontot. A cookie hitelesítési információt a rendszer automatikusan elküldi a kéréssel együtt, és a végpont engedélyezve van. Cookie-alapú hitelesítés biztonságosan be van építve a böngészőbe, és "csak működik".

Tesztelés nem böngésző ügyfelekkel

Egyes webes ügyfelek alapértelmezés szerint nem tartalmaznak cookie-kat a fejlécben:

  • Ha api-k teszteléséhez használ eszközt, előfordulhat, hogy engedélyeznie kell a cookie-kat a beállítások között.

  • A JavaScript fetch API alapértelmezés szerint nem tartalmaz cookie-kat. Engedélyezze őket úgy, hogy a beállításokban credentials értéket include-re állítja.

  • Egy HttpClient, amely egy Blazor WebAssembly alkalmazásban fut, a HttpRequestMessage-nek hitelesítő adatokat kell tartalmaznia, például:

    request.SetBrowserRequestCredential(BrowserRequestCredentials.Include);
    

Token-alapú hitelesítés használata

Azt javasoljuk, hogy böngészőalapú alkalmazásokban használjon cookie-kat, mert alapértelmezés szerint a böngésző automatikusan kezeli őket anélkül, hogy a JavaScriptbe helyeznénk őket.

A rendszer kibocsát egy egyéni tokent (amely az ASP.NET Core identitásplatform sajátja), amely a későbbi kérések hitelesítésére szolgál. A token a Authorization fejlécben "bearer token"-ként kerül átadásra. Egy frissítési token is biztosítva van. Ez a jogkivonat lehetővé teszi, hogy az alkalmazás új jogkivonatot kérjen, amikor a régi lejár anélkül, hogy a felhasználót újra be kell jelentkeznie.

A tokenek nem szabványos JSON webes tokenek (JWT-k). Az egyéni tokenek használata szándékos, mivel a beépített Identity API elsősorban egyszerű helyzetekhez készült. A jogkivonat lehetőség nem egy teljes funkcionalitású identitáskezelő vagy jogkivonat-kiszolgáló, hanem alternatíva a cookie lehetőség helyett azon ügyfelek számára, akik nem tudják használni a cookie-kat.

A token alapú hitelesítés használatához állítsa be a useCookies lekérdezési lánc paramétert false értékre a /login végpont meghívásakor. A jogkivonatok a hordozó hitelesítési sémát használják. A /loginhívásából visszaadott jogkivonat használatával a védett végpontokra irányuló későbbi hívásoknak hozzá kell adniuk a fejlécet Authorization: Bearer <token>, ahol <token> a hozzáférési jogkivonat. További információ: A POST /login végpont használata a cikk későbbi részében.

Kijelentkezés

Ha módot szeretne adni a felhasználónak a kijelentkezéshez, definiáljon egy /logout végpontot az alábbi példához hasonlóan:

app.MapPost("/logout", async (SignInManager<IdentityUser> signInManager,
    [FromBody] object empty) =>
{
    if (empty != null)
    {
        await signInManager.SignOutAsync();
        return Results.Ok();
    }
    return Results.Unauthorized();
})
.WithOpenApi()
.RequireAuthorization();

Adjon meg egy üres JSON-objektumot ({}) a kérelem törzsében a végpont meghívásakor. Az alábbi kód egy példa a kijelentkezés végpontjára irányuló hívásra:

public signOut() {
  return this.http.post('/logout', {}, {
    withCredentials: true,
    observe: 'response',
    responseType: 'text'

A MapIdentityApi<TUser> végpontok

A MapIdentityApi<TUser> hívása a következő végpontokat adja hozzá az alkalmazáshoz:

A POST /register végpont használata

A kérelemtörzsnek Email és Password tulajdonságokkal kell rendelkeznie:

{
  "email": "string",
  "password": "string",
}

További információ:

A POST /login végpont használata

A kérelem törzsében Email és Password szükséges. Ha engedélyezve van a kéttényezős hitelesítés (2FA), TwoFactorCode vagy TwoFactorRecoveryCode van szükség. Ha a 2FA nincs engedélyezve, hagyja ki twoFactorCode és twoFactorRecoveryCode. További információ: A POST /manage/2fa végpont használata a cikk későbbi részében.

Íme egy példa a kérelem törzsére, amelynél a 2FA nincs engedélyezve:

{
  "email": "string",
  "password": "string"
}

Íme néhány példa a kérelem törzsére a 2FA engedélyezésével:

  • {
      "email": "string",
      "password": "string",
      "twoFactorCode": "string",
    }
    
  • {
      "email": "string",
      "password": "string",
      "twoFactorRecoveryCode": "string"
    }
    

A végpont egy lekérdezési sztringparamétert vár:

  • Állítsa useCookies-t true-re cookie-alapú hitelesítéshez. Állítsa be false-ra, vagy hagyja ki token-alapú hitelesítéshez.

A cookie-alapú hitelesítésről további információt a cikk korábbi részében, a Bejelentkezési tesztelése című szakaszban talál.

Tokenalapú hitelesítés

Ha useCookiesfalse vagy nincs megadva, a jogkivonatalapú hitelesítés engedélyezve van. A válasz törzse a következő tulajdonságokat tartalmazza:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

További információ ezekről a tulajdonságokról: AccessTokenResponse.

A hozzáférési jogkivonatot egy fejlécbe helyezve hitelesíthet kérelmeket, ahogyan az alábbi példában is látható

Authorization: Bearer {access token}

Amikor a hozzáférési jogkivonat hamarosan lejár, hívja meg a /frissítés végpontot.

A POST /refresh végpont használata

Csak tokenalapú hitelesítéssel használható. Új hozzáférési jogkivonatot kér le anélkül, hogy a felhasználót újra be kell jelentkeznie. Hívja meg ezt a végpontot, amikor a hozzáférési jogkivonat hamarosan lejár.

A kérelem törzse csak a RefreshToken-t tartalmazza. Íme egy példa a kérelem törzsére:

{
  "refreshToken": "string"
}

Ha a hívás sikeres, a válasz törzse egy új AccessTokenResponse, ahogyan az a következő példában látható:

{
  "tokenType": "string",
  "accessToken": "string",
  "expiresIn": 0,
  "refreshToken": "string"
}

A GET /confirmEmail végpont használata

Ha Identity be van állítva az e-mail-megerősítéshez, a /register végpontra irányuló sikeres hívás egy e-mailt küld, amely a /confirmEmail végpontra mutató hivatkozást tartalmaz. A hivatkozás a következő lekérdezési sztringparamétereket tartalmazza:

  • userId
  • code
  • changedEmail – Csak akkor tartalmazza, ha a felhasználó módosította az e-mail-címet a regisztráció során.

Identity a megerősítő e-mail alapértelmezett szövegét adja meg. Alapértelmezés szerint az e-mail tárgya "Az e-mail megerősítése", és az e-mail törzse a következő példához hasonlóan néz ki:

 Please confirm your account by <a href='https://contoso.com/confirmEmail?userId={user ID}&code={generated code}&changedEmail={new email address}'>clicking here</a>.

Ha a RequireConfirmedEmail tulajdonság értéke true, a felhasználó csak akkor tud bejelentkezni, ha az e-mail-cím megerősítéséhez kattintson az e-mailben található hivatkozásra. A /confirmEmail végpont:

  • Megerősíti az e-mail-címet, és engedélyezi a felhasználónak a bejelentkezést.
  • A válasz törzsében a "Köszönjük, hogy megerősítette az e-mail-címét" szöveget adja vissza.

Ha az e-mail-megerősítéshez szeretné beállítani a(z) Identity-t, adjon hozzá kódot a(z) Program.cs-hez, hogy beállítsa a(z) RequireConfirmedEmail értékét true-ra, és adjon hozzá egy osztályt, amely megvalósítja a IEmailSender-et a DI konténerbe. Például:

builder.Services.Configure<IdentityOptions>(options =>
{
    options.SignIn.RequireConfirmedEmail = true;
});

builder.Services.AddTransient<IEmailSender, EmailSender>();

További információ: Fiók megerősítése és jelszó helyreállítása az ASP.NET Core-ban.

Identity a többi elküldendő e-mailhez is alapértelmezett szöveget biztosít, például a 2FA-t és a jelszó-visszaállítást. Az e-mailek testreszabásához adja meg a IEmailSender felület egyéni implementációját. Az előző példában EmailSender egy olyan osztály, amely IEmailSenderimplementál. További információkért, beleértve egy IEmailSendermegvalósító osztály példáját, tekintse meg a ASP.NET Corefiók megerősítéséről és jelszó-helyreállításról szóló dokumentációt.

A POST /resendConfirmationEmail végpont használata

Csak akkor küld e-mailt, ha a cím érvényes egy regisztrált felhasználóra.

A kérelem törzse csak a Email-t tartalmazza. Íme egy példa a kérelem törzsére:

{
  "email": "string"
}

További információért lásd a GET /confirmEmail végpont használatát a cikk korábbi részében.

A POST /forgotPassword végpont használata

Létrehoz egy új jelszó-visszaállítási kódot tartalmazó e-mailt. Küldje el a kódot egy új jelszóval /resetPassword.

A kérelem törzse csak a Email-t tartalmazza. Íme egy példa:

{
  "email": "string"
}

A Identity e-mailek küldésének engedélyezéséről további információt A GET /confirmEmail végpont használatacímű témakörben talál.

A POST /resetPassword végpont használata

Hívja meg ezt a végpontot az alaphelyzetbe állítási kód lekérése után a /forgotPassword végpont meghívásával.

A kérelem törzséhez Email, ResetCodeés NewPasswordszükséges. Íme egy példa:

{
  "email": "string",
  "resetCode": "string",
  "newPassword": "string"
}

A POST /manage/2fa végpont használata

Kéttényezős hitelesítést (2FA) konfigurál a felhasználó számára. Ha a 2FA engedélyezve van, a sikeres bejelentkezéshez az e-mail-cím és a jelszó mellett egy hitelesítő alkalmazás által létrehozott kódra van szükség.

2FA engedélyezése

A 2FA engedélyezése az aktuálisan hitelesített felhasználó számára:

  • Hívja meg a /manage/2fa végpontot, és küldjön egy üres JSON-objektumot ({}) a kérelem törzsében.

  • A válasz törzse biztosítja a SharedKey, valamint néhány olyan tulajdonságot, amelyre jelenleg nincs szükség. A megosztott kulccsal állíthatja be a hitelesítő alkalmazást. Példa a válasz törzsére:

    {
      "sharedKey": "string",
      "recoveryCodesLeft": 0,
      "recoveryCodes": null,
      "isTwoFactorEnabled": false,
      "isMachineRemembered": false
    }
    
  • A megosztott kulccsal időalapú egyszeri jelszót (TOTP) kaphat. További információ: QR-kódlétrehozás engedélyezése TOTP-hitelesítő alkalmazásokhoz ASP.NET Core.

  • Hívja meg a /manage/2fa végpontot, és küldje el a TOTP-t és a "enable": true-et a kérés törzsében. Például:

    {
      "enable": true,
      "twoFactorCode": "string"
    }
    
  • A válasz törzse megerősíti, hogy IsTwoFactorEnabled igaz, és megadja a RecoveryCodes. A helyreállítási kódokat a bejelentkezéshez használják, amikor a hitelesítő alkalmazás nem érhető el. Példa a válasz törzsére a 2FA sikeres engedélyezése után.

    {
      "sharedKey": "string",
      "recoveryCodesLeft": 10,
      "recoveryCodes": [
        "string",
        "string",
        "string",
        "string",
        "string",
        "string",
        "string",
        "string",
        "string",
        "string"
      ],
      "isTwoFactorEnabled": true,
      "isMachineRemembered": false
    }
    

Bejelentkezés 2FA-val

Hívja meg a /login végpontot, és küldje el az e-mail-címet, a jelszót és a TOTP-t a kérelem törzsében. Például:

{
  "email": "string",
  "password": "string",
  "twoFactorCode": "string"
}

Ha a felhasználó nem fér hozzá a hitelesítő alkalmazáshoz, jelentkezzen be úgy, hogy meghívja a /login végpontot a 2FA engedélyezésekor megadott helyreállítási kódok egyikével. A kérelem törzse a következő példához hasonlóan néz ki:

{
  "email": "string",
  "password": "string",
  "twoFactorRecoveryCode": "string"
}

A helyreállítási kódok alaphelyzetbe állítása

A helyreállítási kódok új gyűjteményének lekéréséhez hívja meg ezt a végpontot úgy, hogy ResetRecoveryCodestrueértékre van állítva. Íme egy példa a kérelem törzsére:

{
  "resetRecoveryCodes": true
}

A megosztott kulcs alaphelyzetbe állítása

Új véletlenszerű megosztott kulcs lekéréséhez hívja meg ezt a végpontot úgy, hogy ResetSharedKeytrueértékre van állítva. Íme egy példa a kérelem törzsére:

{
  "resetSharedKey": true
}

A kulcs alaphelyzetbe állítása automatikusan letiltja a hitelesített felhasználó kétfaktoros bejelentkezési követelményét, amíg egy későbbi kérés nem engedélyezi újra.

Felejtsd el a gépet

Ha a cookie "emlékezzen rám" jelző jelen van, törölje úgy, hogy ezt a végpontot hívja meg, és állítsa be a ForgetMachine értékét igazra. Íme egy példa a kérelem törzsére:

{
  "forgetMachine": true
}

Ez a végpont nincs hatással a jogkivonat-alapú hitelesítésre.

A GET /manage/info végpont használata

Lekéri a bejelentkezett felhasználó e-mail-címét és e-mail-visszaigazolási állapotát. Az igények biztonsági okokból lettek kihagyva ebből a végpontból. Ha jogcímekre van szükség, a kiszolgálóoldali API-k használatával állítson be végpontot a jogcímekhez. Vagy ahelyett, hogy megosztaná az összes felhasználói jogcímet, adjon meg egy érvényesítési végpontot, amely elfogadja a jogcímet, és válaszol arra, hogy a felhasználó rendelkezik-e vele.

A kéréshez nincs szükség paraméterekre. A válasz törzse tartalmazza a Email és IsEmailConfirmed tulajdonságokat, ahogyan az alábbi példában is látható:

{
  "email": "string",
  "isEmailConfirmed": true
}

A POST /manage/info végpont használata

Frissíti a bejelentkezett felhasználó e-mail-címét és jelszavát. Küldje a NewEmail, NewPasswordés OldPassword elemeket a kérelem törzsében, az alábbi példának megfelelően:

{
  "newEmail": "string",
  "newPassword": "string",
  "oldPassword": "string"
}

Íme egy példa a válasz tartalmára:

{
  "email": "string",
  "isEmailConfirmed": false
}

Lásd még:

További információ:

A ASP.NET Core-sablonok egyoldalas alkalmazásokban (SPA-kban) nyújtanak hitelesítést az API-engedélyezés támogatásával. ASP.NET Core Identity a felhasználók hitelesítésére és tárolására, kombinálva a Duende Identity Server-mal az OpenID Connect implementálásához.

Fontos

A Duende Software előírhatja, hogy licencdíjat kell fizetnie a Duende Identity Server éles használatáért. További információ: Migrálás ASP.NET Core-ból .NET 5-ről .NET 6-ra.

A Angular és React projektsablonokhoz egy hitelesítési paraméter lett hozzáadva, amely hasonló a webalkalmazás (Model-View-Controller) (MVC) és webalkalmazás- (Razor Pages) projektsablonok hitelesítési paraméteréhez. Az engedélyezett paraméterértékek Nincs és Egyéni. A React.js és a Redux projektsablon jelenleg nem támogatja a hitelesítési paramétert.

Alkalmazás létrehozása API-engedélyezési támogatással

A felhasználói hitelesítés és engedélyezés az Angular és a React SLA-k használatával is használható. Nyisson meg egy parancshéjat, és futtassa a következő parancsot:

Szögletes:

dotnet new angular -au Individual

Reagálás:

dotnet new react -au Individual

Az előző parancs létrehoz egy ASP.NET Core-alkalmazást az SPA-t tartalmazó ClientApp könyvtárral.

Az alkalmazás ASP.NET Core összetevőinek általános leírása

A következő szakaszok a projekt kiegészítéseit ismertetik, ha a hitelesítési támogatás szerepel a csomagban:

Program.cs

Az alábbi példakódok a Microsoft.AspNetCore.ApiAuthorization.IdentityServer NuGet-csomag alapulnak. A példák az API-hitelesítést és -engedélyezést a AddApiAuthorization és AddIdentityServerJwt bővítménymetelyekkel konfigurálják. A React- vagy Angular SPA-projektsablonokat hitelesítéssel használó projektek hivatkoznak erre a csomagra.

dotnet new angular -au Individual a következő Program.cs fájlt hozza létre:

using Microsoft.AspNetCore.Authentication;
using Microsoft.EntityFrameworkCore;
using output_directory_name.Data;
using output_directory_name.Models;

var builder = WebApplication.CreateBuilder(args);

var connectionString = builder.Configuration.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlite(connectionString));
builder.Services.AddDatabaseDeveloperPageExceptionFilter();

builder.Services.AddDefaultIdentity<ApplicationUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddEntityFrameworkStores<ApplicationDbContext>();

builder.Services.AddIdentityServer()
    .AddApiAuthorization<ApplicationUser, ApplicationDbContext>();

builder.Services.AddAuthentication()
    .AddIdentityServerJwt();

builder.Services.AddControllersWithViews();
builder.Services.AddRazorPages();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseMigrationsEndPoint();
}
else
{
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

app.UseAuthentication();
app.UseIdentityServer();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller}/{action=Index}/{id?}");
app.MapRazorPages();

app.MapFallbackToFile("index.html");

app.Run();

Az előző kód a következőt konfigurálja:

  • Identity az alapértelmezett felhasználói felülettel:

    builder.Services.AddDbContext<ApplicationDbContext>(options =>
        options.UseSqlite(connectionString));
    builder.Services.AddDatabaseDeveloperPageExceptionFilter();
    
    builder.Services.AddDefaultIdentity<ApplicationUser>(options => options.SignIn.RequireConfirmedAccount = true)
        .AddEntityFrameworkStores<ApplicationDbContext>();
    
  • IdentityServer egy további AddApiAuthorization segédmetódussal, amely beállít néhány alapértelmezett ASP.NET Core-konvenciót az IdentityServeren felül:

    builder.Services.AddIdentityServer()
        .AddApiAuthorization<ApplicationUser, ApplicationDbContext>();
    
  • Hitelesítés egy további AddIdentityServerJwt segédmetódussal, amely konfigurálja az alkalmazást az IdentityServer által létrehozott JWT-tokenek ellenőrzésére:

    builder.Services.AddAuthentication()
    .AddIdentityServerJwt();
    
  • A hitelesítési köztes szoftver, amely a kérés hitelesítő adatainak érvényesítéséért és a felhasználó kérési környezethez való beállításáért felelős:

    app.UseAuthentication();
    
  • Az OpenID Connect-végpontokat elérhetővé tevő IdentityServer köztes szoftver:

    app.UseIdentityServer();
    

Figyelmeztetés

Ez a cikk a kapcsolati sztringek használatát mutatja be. Helyi adatbázis esetén a felhasználót nem kell hitelesíteni, de éles környezetben a kapcsolati sztringek néha tartalmaznak jelszót a hitelesítéshez. Az erőforrás-tulajdonosi jelszó hitelesítő adatai (ROPC) olyan biztonsági kockázatot jelentenek, amelyet el kell kerülni az éles adatbázisokban. A termelésben használt alkalmazásoknak az elérhető legbiztonságosabb hitelesítési folyamatot kell használniuk. A tesztelési vagy éles környezetekben üzembe helyezett alkalmazások hitelesítéséről további információt a Biztonságos hitelesítési folyamatokcímű témakörben talál.

Azure App Service on Linux

A Linuxon futó Azure App Service-környezetek esetében explicit módon adja meg a kiállítót:

builder.Services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme, 
    options =>
    {
        options.Authority = "{AUTHORITY}";
    });

Az előző kódban a {AUTHORITY} helyőrző az OpenID Connect-hívásokhoz használandó Authority-ként van megadva.

Példa:

options.Authority = "https://contoso-service.azurewebsites.net";

AddApiAuthorization

Ez a segédmetódus konfigurálja az IdentityServert a támogatott konfiguráció használatára. Az IdentityServer egy hatékony és bővíthető keretrendszer az alkalmazásbiztonsági problémák kezeléséhez. Ezzel egyidejűleg a leggyakoribb forgatókönyvek szükségtelen összetettségét teszi elérhetővé. Következésképpen olyan konvenciók és konfigurációs lehetőségek állnak rendelkezésre, amelyek jó kiindulási pontnak minősülnek. Miután a hitelesítést módosítani kell, az IdentityServer teljes ereje továbbra is elérhető az igényeinek megfelelő hitelesítés testreszabásához.

AddIdentityServerJwt

Ez a segédmetódus alapértelmezett hitelesítési kezelőként konfigurál egy szabályzatsémát az alkalmazáshoz. A szabályzat úgy van konfigurálva, hogy Identity kezelje a Identity URL-címtartomány "/Identity" bármely alútjára irányított kéréseket. A JwtBearerHandler kezeli az összes többi kérést. Emellett ez a módszer regisztrál egy <<ApplicationName>>API API-erőforrást az IdentityServerben az alapértelmezett <<ApplicationName>>API hatókörrel, és konfigurálja a JWT Bearer-jogkivonat köztes szoftverét az IdentityServer által az alkalmazáshoz kiadott jogkivonatok érvényesítéséhez.

WeatherForecastController

A fájlban figyelje meg az osztályra alkalmazott [Authorize] attribútumot, amely azt jelzi, hogy a felhasználót az alapértelmezett szabályzat alapján kell engedélyezni az erőforrás eléréséhez. Az alapértelmezett engedélyezési szabályzat az alapértelmezett hitelesítési séma használatára van konfigurálva, amelyet a AddIdentityServerJwt a fent említett házirendsémára állít be, így az ilyen segédmetódus által konfigurált JwtBearerHandler az alkalmazáshoz érkező kérések alapértelmezett kezelője.

ApplicationDbContext

A fájlban ugyanazt a DbContext használja Identity azzal a különbséggel, hogy kiterjeszti ApiAuthorizationDbContext (egy származtatottabb osztály IdentityDbContext-tól), hogy tartalmazza az IdentityServer sémáját.

Az adatbázisséma teljes körű vezérléséhez örökölje az egyik elérhető IdentityDbContext osztályt, és konfigurálja a környezetet úgy, hogy a Identity sémát is tartalmazza, ha meghívja builder.ConfigurePersistedGrantContext(_operationalStoreOptions.Value) a OnModelCreating metódusra.

OidcConfigurationController

A fájlban figyelje meg a végpontot, amely az ügyfél által használni kívánt OIDC-paraméterek kiszolgálására van kiépítve.

appsettings.json

A projektgyökér appsettings.json fájljában egy új IdentityServer szakasz ismerteti a konfigurált ügyfelek listáját. Az alábbi példában egyetlen ügyfél található. Az ügyfélnév megfelel az alkalmazás nevének, és konvenció szerint megfelel az OAuth ClientId paraméternek. A profil a konfigurált alkalmazástípust jelzi. Belsőleg a kiszolgáló konfigurációs folyamatát egyszerűsítő konvenciók kialakítására szolgál. A alkalmazásprofilok szakaszban ismertetett módon számos profil érhető el.

"IdentityServer": {
  "Clients": {
    "angularindividualpreview3final": {
      "Profile": "IdentityServerSPA"
    }
  }
}

appsettings.Development.json

A projekt gyökérkönyvtárának appsettings.Development.json fájljában található egy IdentityServer szakasz, amely leírja a tokenek aláírásához használt kulcsot. Éles környezetben történő üzembe helyezéskor az alkalmazás mellett ki kell telepíteni és üzembe kell helyezni egy kulcsot, amint az a Üzembe helyezés éles környezetben szakaszban található.

"IdentityServer": {
  "Key": {
    "Type": "Development"
  }
}

Az Angular-alkalmazás általános leírása

Az Angular-sablon hitelesítési és API-engedélyezési támogatása a saját Angular-moduljában található a ClientApp/src/api-authorization könyvtárban. A modul a következő elemekből áll:

  • 3 összetevő:
    • login.component.ts: Az alkalmazás bejelentkezési folyamatának kezelése.
    • logout.component.ts: Az alkalmazás kijelentkezés folyamatának kezelése.
    • login-menu.component.ts: Egy widget, amely a következő hivatkozások egyikét jeleníti meg:
      • A felhasználói profil kezelése és a kijelentkezési hivatkozások a felhasználó hitelesítésekor.
      • Regisztráció és bejelentkezési hivatkozások, ha a felhasználó nincs hitelesítve.
  • Egy útvonalvédelmi AuthorizeGuard, amely hozzáadható az útvonalakhoz, és megköveteli a felhasználó hitelesítését az útvonal felkeresése előtt.
  • Egy HTTP-elfogó AuthorizeInterceptor, amely csatolja a hozzáférési jogkivonatot az API-t megcélzó kimenő HTTP-kérésekhez a felhasználó hitelesítésekor.
  • Egy szolgáltatás AuthorizeService, amely kezeli a hitelesítési folyamat alacsonyabb szintű adatait, és a hitelesített felhasználó adatait teszi elérhetővé az alkalmazás többi része számára felhasználás céljából.
  • Egy Angular modul, amely meghatározza az alkalmazás hitelesítési részeihez társított útvonalakat. A bejelentkezési menü komponensét, az elfogót, a védelmet és a szolgáltatást elérhetővé teszi az alkalmazás többi része számára való felhasználásra.

A React alkalmazás általános leírása

A React-sablon hitelesítésének és API-engedélyezésének támogatása a ClientApp/src/components/api-authorization könyvtárban található. A következő elemekből áll:

  • 4 összetevő:
    • Login.js: Az alkalmazás bejelentkezési folyamatának kezelése.
    • Logout.js: Az alkalmazás kijelentkezés folyamatának kezelése.
    • LoginMenu.js: Egy widget, amely a következő hivatkozások egyikét jeleníti meg:
      • A felhasználói profil kezelése és a kijelentkezési hivatkozások a felhasználó hitelesítésekor.
      • Regisztráció és bejelentkezési hivatkozások, ha a felhasználó nincs hitelesítve.
    • AuthorizeRoute.js: Olyan útvonal-összetevő, amely megköveteli a felhasználó hitelesítését a Component paraméterben jelzett összetevő megjelenítése előtt.
  • Egy exportált authService osztály AuthorizeService példánya, amely a hitelesítési folyamat alacsonyabb szintű adatait kezeli, és a hitelesített felhasználó adatait elérhetővé teszi az alkalmazás többi részének felhasználás céljából.

Most, hogy megismerte a megoldás fő összetevőit, részletesebben áttekintheti az alkalmazás egyes forgatókönyveit.

Engedélyezés megkövetelése új API-n

Alapértelmezés szerint a rendszer úgy van konfigurálva, hogy egyszerűen megkövetelje az új API-k engedélyezését. Ehhez hozzon létre egy új vezérlőt, és adja hozzá a [Authorize] attribútumot a vezérlőosztályhoz vagy a vezérlőn belüli bármely művelethez.

Az API-hitelesítési kezelő testreszabása

Az API JWT-kezelőjének konfigurációjának testreszabásához konfigurálja a JwtBearerOptions-példányt:

builder.Services.AddAuthentication()
    .AddIdentityServerJwt();

builder.Services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme,
    options =>
    {
        ...
    });

Az API JWT-kezelője olyan eseményeket vet fel, amelyek lehetővé teszik a hitelesítési folyamat vezérlését JwtBearerEventshasználatával. Az API-engedélyezés támogatásához AddIdentityServerJwt regisztrálja saját eseménykezelőit.

Az esemény kezelésének testreszabásához szükség szerint csomagolja be a meglévő eseménykezelőt további logikával. Például:

builder.Services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme,
    options =>
    {
        var onTokenValidated = options.Events.OnTokenValidated;       

        options.Events.OnTokenValidated = async context =>
        {
            await onTokenValidated(context);
            ...
        }
    });

Az előző kódban a OnTokenValidated eseménykezelőt egy egyéni implementáció váltja fel. Ez a megvalósítás:

  1. Meghívja az API engedélyezési támogatás által biztosított eredeti implementációt.
  2. Futtassa saját egyéni logikáját.

Ügyféloldali útvonal védelme (Angular)

Az ügyféloldali útvonalak védelmére úgy van szükség, hogy hozzáadjuk az engedélyezési védelmet az útvonalak konfigurálásakor futtatandó védelmi beállítások listájához. Példaként láthatja, hogyan van konfigurálva a fetch-data útvonal a főalkalmazás Angular modulján belül:

RouterModule.forRoot([
  // ...
  { path: 'fetch-data', component: FetchDataComponent, canActivate: [AuthorizeGuard] },
])

Fontos megemlíteni, hogy az útvonalak védelme nem védi a tényleges végpontot (amelyhez továbbra is egy [Authorize] attribútumot kell alkalmazni), de csak akkor akadályozza meg a felhasználót, hogy a hitelesítés nélkül navigáljon az adott ügyféloldali útvonalra.

API-kérések hitelesítése (Angular)

Az alkalmazás mellett üzemeltetett API-khoz érkező kérések hitelesítése automatikusan történik az alkalmazás által meghatározott HTTP-ügyfélfogó használatával.

Ügyféloldali útvonal védelme (React)

Ügyféloldali útvonal védelme az egyszerű AuthorizeRoute összetevő helyett a Route összetevő használatával. Figyelje meg például, hogyan van konfigurálva a fetch-data útvonal a App összetevőn belül:

<AuthorizeRoute path='/fetch-data' component={FetchData} />

Útvonal védelme:

  • Nem védi a tényleges végpontot (amelyhez továbbra is [Authorize] attribútum szükséges).
  • Csak akkor akadályozza meg a felhasználót, hogy az adott ügyféloldali útvonalra navigáljon, ha nincs hitelesítve.

API-kérések hitelesítése (React)

A kérelmek hitelesítése a React használatával azzal történik, hogy először importáljuk a authService példányt a AuthorizeService-ból. A hozzáférési jogkivonatot a authService-ból nyerik ki, és az alább látható módon csatolják a kérelemhez. A React-összetevőkben ez a munka általában az componentDidMount életciklus-metódusban vagy valamilyen felhasználói beavatkozás eredményeként történik.

A authService importálása egy összetevőbe

import authService from './api-authorization/AuthorizeService'

A hozzáférési jogkivonat lekérése és csatolása a válaszhoz

async populateWeatherData() {
  const token = await authService.getAccessToken();
  const response = await fetch('api/SampleData/WeatherForecasts', {
    headers: !token ? {} : { 'Authorization': `Bearer ${token}` }
  });
  const data = await response.json();
  this.setState({ forecasts: data, loading: false });
}

Éles környezetbe telepítés

Az alkalmazás éles környezetben való üzembe helyezéséhez a következő erőforrásokat kell kiépíteni:

  • A Identity felhasználói fiókok és az IdentityServer által biztosított engedélyek tárolására használt adatbázis.
  • Gyártási tanúsítvány a jogkivonatok aláírásához.
    • A tanúsítványnak nincsenek konkrét követelményei; lehet egy önaláírt tanúsítvány vagy egy hitelesítésszolgáltatón keresztül kiépített tanúsítvány.
    • Ez olyan szabványos eszközökkel hozható létre, mint a PowerShell vagy az OpenSSL.
    • Telepíthető a célgépek tanúsítványtárolójába, vagy .pfx fájlként, erős jelszóval.

Példa: Üzembe helyezés nem Azure-beli webszolgáltatón

A web hosting panelen hozza létre vagy töltse be a tanúsítványt. Ezután az alkalmazás appsettings.json fájljában módosítsa a IdentityServer szakaszt, hogy tartalmazza a legfontosabb részleteket. Például:

"IdentityServer": {
  "Key": {
    "Type": "Store",
    "StoreName": "WebHosting",
    "StoreLocation": "CurrentUser",
    "Name": "CN=MyApplication"
  }
}

Az előző példában:

  • StoreName annak a tanúsítványtárolónak a nevét jelöli, amelyben a tanúsítványt tárolják. Ebben az esetben a webtárhelyre mutat.
  • StoreLocation a tanúsítvány betöltésének helye ( ebben az esetbenCurrentUser).
  • Name megfelel a tanúsítvány megkülönböztető tárgyának.

Példa: Üzembe helyezés az Azure App Service-ben

Ez a szakasz azt ismerteti, hogyan helyezheti üzembe az alkalmazást az Azure App Service-ben a tanúsítványtárolóban tárolt tanúsítvány használatával. Ha módosítani szeretné az alkalmazást a tanúsítványtárolóból származó tanúsítvány betöltéséhez, standard szintű szolgáltatási csomagra van szükség, vagy jobb, ha egy későbbi lépésben konfigurálja az alkalmazást az Azure Portalon.

Az alkalmazás appsettings.json fájljában módosítsa a IdentityServer szakaszt, hogy tartalmazza a legfontosabb részleteket:

"IdentityServer": {
  "Key": {
    "Type": "Store",
    "StoreName": "My",
    "StoreLocation": "CurrentUser",
    "Name": "CN=MyApplication"
  }
}
  • Az áruház neve annak a tanúsítványtárolónak a nevét jelöli, ahol a tanúsítványt tárolják. Ebben az esetben a személyes felhasználói tárolóra mutat.
  • Az áruház helye azt jelzi, hogy honnan töltheti be a tanúsítványt (CurrentUser vagy LocalMachine).
  • A tanúsítvány név tulajdonsága megfelel a tanúsítvány megkülönböztetett tárgyának.

Az Azure App Service-ben való üzembe helyezéshez kövesse az Az alkalmazás üzembe helyezése az Azure-ban című cikkben leírt lépéseket, amely bemutatja, hogyan hozhatja létre a szükséges Azure-erőforrásokat, és hogyan helyezheti üzembe az alkalmazást éles környezetben.

Az előző utasítások követését követően az alkalmazás üzembe lesz helyezve az Azure-ban, de még nem működik. Az alkalmazás által használt tanúsítványt az Azure Portalon kell konfigurálni. Keresse meg a tanúsítvány ujjlenyomatát, és kövesse Tanúsítványok betöltésecímű cikkben leírt lépéseket.

Az SSL megemlítése mellett van egy Privát tanúsítványok szakasz az Azure portálon, ahol feltöltheti a kiépített tanúsítványt az alkalmazás használatához.

Miután konfigurálta az alkalmazást és az alkalmazás beállításait az Azure Portalon, indítsa újra az alkalmazást a portálon.

Egyéb konfigurációs beállítások

Az API-engedélyezés támogatása az IdentityServerre épül, konvenciók, alapértelmezett értékek és fejlesztések halmazával, hogy egyszerűbbé tegye az SLA-k használatát. Mondanom sem kell, hogy az IdentityServer teljes ereje elérhető a színfalak mögött, ha a ASP.NET Core-integrációk nem fedik le a forgatókönyvet. A ASP.NET Core-támogatás az "első féltől származó" alkalmazásokra összpontosít, ahol az összes alkalmazást a szervezet hozza létre és telepíti. Ezért nem nyújtunk támogatást olyan dolgokhoz, mint a hozzájárulás vagy az összevonás. Ezekben a forgatókönyvekben használja az IdentityServert, és kövesse a dokumentációt.

Alkalmazásprofilok

Az alkalmazásprofilok előre definiált konfigurációk azokhoz az alkalmazásokhoz, amelyek tovább határozzák meg a paramétereiket. Jelenleg a következő profilok támogatottak:

  • IdentityServerSPA: Az IdentityServer mellett üzemeltetett SPA-t jelöli egyetlen egységként.
    • A redirect_uri alapértelmezettként /authentication/login-callbackértékre van állítva.
    • A post_logout_redirect_uri alapértelmezettként /authentication/logout-callbackértékre van állítva.
    • A hatókörök halmaza magában foglalja a openid, profile, valamint az alkalmazás API-jaihoz definiált összes hatókört.
    • Az engedélyezett OIDC-választípusok halmaza id_token token, vagy minden egyes típus külön-külön (id_token, token).
    • Az engedélyezett válasz mód fragment.
  • SPA: Olyan SPA-t jelöl, amely nem az IdentityServer szolgáltatással van üzemeltetve.
    • A hatókörök halmaza magában foglalja a openid, profile, valamint az alkalmazás API-jaihoz definiált összes hatókört.
    • Az engedélyezett OIDC-választípusok halmaza id_token token, vagy minden egyes típus külön-külön (id_token, token).
    • Az engedélyezett válasz mód fragment.
  • IdentityServerJwt: Az IdentityServerrel együtt üzemeltetett API-t jelöli.
    • Az alkalmazás úgy van konfigurálva, hogy egyetlen hatókörrel rendelkezzen, amely alapértelmezés szerint az alkalmazás nevéhez tartozik.
  • API: Olyan API-t jelöl, amely nem az IdentityServerrel van üzemeltetve.
    • Az alkalmazás úgy van konfigurálva, hogy egyetlen hatókörrel rendelkezzen, amely alapértelmezés szerint az alkalmazás nevéhez tartozik.

A konfiguráció a AppSettings-on keresztül

Konfigurálja az alkalmazásokat a konfigurációs rendszeren keresztül úgy, hogy hozzáadja őket a Clients vagy Resourceslistájához.

Konfigurálja az egyes ügyfelek redirect_uri és post_logout_redirect_uri tulajdonságát az alábbi példában látható módon:

"IdentityServer": {
  "Clients": {
    "MySPA": {
      "Profile": "SPA",
      "RedirectUri": "https://www.example.com/authentication/login-callback",
      "LogoutUri": "https://www.example.com/authentication/logout-callback"
    }
  }
}

Az erőforrások konfigurálásakor az alábbi módon konfigurálhatja az erőforrás hatóköreit:

"IdentityServer": {
  "Resources": {
    "MyExternalApi": {
      "Profile": "API",
      "Scopes": "a b c"
    }
  }
}

Konfiguráció kódon keresztül

Az ügyfeleket és az erőforrásokat programozottan is konfigurálhatja a beállítások konfigurálására alkalmas AddApiAuthorization metódus túlterhelésével.

AddApiAuthorization<ApplicationUser, ApplicationDbContext>(options =>
{
    options.Clients.AddSPA(
        "My SPA", spa =>
        spa.WithRedirectUri("http://www.example.com/authentication/login-callback")
           .WithLogoutRedirectUri(
               "http://www.example.com/authentication/logout-callback"));

    options.ApiResources.AddApiResource("MyExternalApi", resource =>
        resource.WithScopes("a", "b", "c"));
});

További erőforrások

A ASP.NET Core 3.1-es vagy újabb sablonjai az API-engedélyezés támogatásával nyújtanak hitelesítést egyoldalas alkalmazásokban (SPA-kban). Az ASP.NET Core Identity a felhasználók hitelesítésére és tárolására van kombinálva a IdentityServer eszközzel az OpenID Connect implementálásához.

A Angular és React projektsablonokhoz egy hitelesítési paraméter lett hozzáadva, amely hasonló a webalkalmazás (Model-View-Controller) (MVC) és webalkalmazás- (Razor Pages) projektsablonok hitelesítési paraméteréhez. Az engedélyezett paraméterértékek Nincs és Egyéni. A React.js és a Redux projektsablon jelenleg nem támogatja a hitelesítési paramétert.

Alkalmazás létrehozása API-engedélyezési támogatással

A felhasználói hitelesítés és engedélyezés az Angular és a React SLA-k használatával is használható. Nyisson meg egy parancshéjat, és futtassa a következő parancsot:

Szögletes:

dotnet new angular -o <output_directory_name> 

Reagálás:

dotnet new react -o <output_directory_name> -au Individual

Az előző parancs létrehoz egy ASP.NET Core-alkalmazást az SPA-t tartalmazó ClientApp könyvtárral.

Az alkalmazás ASP.NET Core összetevőinek általános leírása

A következő szakaszok a projekt kiegészítéseit ismertetik, ha a hitelesítési támogatás szerepel a csomagban:

Startup osztály

Az alábbi példakódok a Microsoft.AspNetCore.ApiAuthorization.IdentityServer NuGet-csomag alapulnak. A példák az API-hitelesítést és -engedélyezést a AddApiAuthorization és AddIdentityServerJwt bővítménymetelyekkel konfigurálják. A React- vagy Angular SPA-projektsablonokat hitelesítéssel használó projektek hivatkoznak erre a csomagra.

A Startup osztály a következő kiegészítésekkel rendelkezik:

  • A Startup.ConfigureServices metóduson belül:

    • Identity az alapértelmezett felhasználói felülettel:

      services.AddDbContext<ApplicationDbContext>(options =>
          options.UseSqlite(Configuration.GetConnectionString("DefaultConnection")));
      
      services.AddDefaultIdentity<ApplicationUser>()
          .AddEntityFrameworkStores<ApplicationDbContext>();
      
    • IdentityServer egy további AddApiAuthorization segédmetódussal, amely beállít néhány alapértelmezett ASP.NET Core-konvenciót az IdentityServeren felül:

      services.AddIdentityServer()
          .AddApiAuthorization<ApplicationUser, ApplicationDbContext>();
      
    • Hitelesítés egy további AddIdentityServerJwt segédmetódussal, amely konfigurálja az alkalmazást az IdentityServer által létrehozott JWT-tokenek ellenőrzésére:

      services.AddAuthentication()
          .AddIdentityServerJwt();
      
  • A Startup.Configure metóduson belül:

    • A hitelesítési köztes szoftver, amely a kérés hitelesítő adatainak érvényesítéséért és a felhasználó kérési környezethez való beállításáért felelős:

      app.UseAuthentication();
      
    • Az OpenID Connect-végpontokat elérhetővé tevő IdentityServer köztes szoftver:

      app.UseIdentityServer();
      

Figyelmeztetés

Ez a cikk a kapcsolati sztringek használatát mutatja be. Helyi adatbázis esetén a felhasználót nem kell hitelesíteni, de éles környezetben a kapcsolati sztringek néha tartalmaznak jelszót a hitelesítéshez. Az erőforrás-tulajdonosi jelszó hitelesítő adatai (ROPC) olyan biztonsági kockázatot jelentenek, amelyet el kell kerülni az éles adatbázisokban. A termelésben használt alkalmazásoknak az elérhető legbiztonságosabb hitelesítési folyamatot kell használniuk. A tesztelési vagy éles környezetekben üzembe helyezett alkalmazások hitelesítéséről további információt a Biztonságos hitelesítési folyamatokcímű témakörben talál.

Azure App Service on Linux

Az Azure App Service Linux környezetben történő üzembe helyezése esetén adja meg kifejezetten a Startup.ConfigureServices-ben a kiállítót.

services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme, 
    options =>
    {
        options.Authority = "{AUTHORITY}";
    });

Az előző kódban a {AUTHORITY} helyőrző az OpenID Connect-hívásokhoz használandó Authority-ként van megadva.

Példa:

options.Authority = "https://contoso-service.azurewebsites.net";

AddApiAuthorization

Ez a segédmetódus konfigurálja az IdentityServert a támogatott konfiguráció használatára. Az IdentityServer egy hatékony és bővíthető keretrendszer az alkalmazásbiztonsági problémák kezeléséhez. Ezzel egyidejűleg a leggyakoribb forgatókönyvek szükségtelen összetettségét teszi elérhetővé. Következésképpen olyan konvenciók és konfigurációs lehetőségek állnak rendelkezésre, amelyek jó kiindulási pontnak minősülnek. Miután a hitelesítést módosítani kell, az IdentityServer teljes ereje továbbra is elérhető az igényeinek megfelelő hitelesítés testreszabásához.

AddIdentityServerJwt

Ez a segédmetódus alapértelmezett hitelesítési kezelőként konfigurál egy szabályzatsémát az alkalmazáshoz. A szabályzat úgy van konfigurálva, hogy Identity kezelje a Identity URL-címtartomány "/Identity" bármely alútjára irányított kéréseket. A JwtBearerHandler kezeli az összes többi kérést. Emellett ez a módszer regisztrál egy <<ApplicationName>>API API-erőforrást az IdentityServerben az alapértelmezett <<ApplicationName>>API hatókörrel, és konfigurálja a JWT Bearer-jogkivonat köztes szoftverét az IdentityServer által az alkalmazáshoz kiadott jogkivonatok érvényesítéséhez.

WeatherForecastController

A fájlban figyelje meg az osztályra alkalmazott [Authorize] attribútumot, amely azt jelzi, hogy a felhasználót az alapértelmezett szabályzat alapján kell engedélyezni az erőforrás eléréséhez. Az alapértelmezett engedélyezési szabályzat az alapértelmezett hitelesítési séma használatára van konfigurálva, amelyet a AddIdentityServerJwt a fent említett házirendsémára állít be, így az ilyen segédmetódus által konfigurált JwtBearerHandler az alkalmazáshoz érkező kérések alapértelmezett kezelője.

ApplicationDbContext

A fájlban ugyanazt a DbContext használja Identity azzal a különbséggel, hogy kiterjeszti ApiAuthorizationDbContext (egy származtatottabb osztály IdentityDbContext-tól), hogy tartalmazza az IdentityServer sémáját.

Az adatbázisséma teljes körű vezérléséhez örökölje az egyik elérhető IdentityDbContext osztályt, és konfigurálja a környezetet úgy, hogy a Identity sémát is tartalmazza, ha meghívja builder.ConfigurePersistedGrantContext(_operationalStoreOptions.Value) a OnModelCreating metódusra.

OidcConfigurationController

A fájlban figyelje meg a végpontot, amely az ügyfél által használni kívánt OIDC-paraméterek kiszolgálására van kiépítve.

appsettings.json

A projektgyökér appsettings.json fájljában egy új IdentityServer szakasz ismerteti a konfigurált ügyfelek listáját. Az alábbi példában egyetlen ügyfél található. Az ügyfélnév megfelel az alkalmazás nevének, és konvenció szerint megfelel az OAuth ClientId paraméternek. A profil a konfigurált alkalmazástípust jelzi. Belsőleg a kiszolgáló konfigurációs folyamatát egyszerűsítő konvenciók kialakítására szolgál. A alkalmazásprofilok szakaszban ismertetett módon számos profil érhető el.

"IdentityServer": {
  "Clients": {
    "angularindividualpreview3final": {
      "Profile": "IdentityServerSPA"
    }
  }
}

appsettings.Development.json

A projekt gyökérkönyvtárának appsettings.Development.json fájljában található egy IdentityServer szakasz, amely leírja a tokenek aláírásához használt kulcsot. Éles környezetben történő üzembe helyezéskor az alkalmazás mellett ki kell telepíteni és üzembe kell helyezni egy kulcsot, amint az a Üzembe helyezés éles környezetben szakaszban található.

"IdentityServer": {
  "Key": {
    "Type": "Development"
  }
}

Az Angular-alkalmazás általános leírása

Az Angular-sablon hitelesítési és API-engedélyezési támogatása a saját Angular-moduljában található a ClientApp/src/api-authorization könyvtárban. A modul a következő elemekből áll:

  • 3 összetevő:
    • login.component.ts: Az alkalmazás bejelentkezési folyamatának kezelése.
    • logout.component.ts: Az alkalmazás kijelentkezés folyamatának kezelése.
    • login-menu.component.ts: Egy widget, amely a következő hivatkozások egyikét jeleníti meg:
      • A felhasználói profil kezelése és a kijelentkezési hivatkozások a felhasználó hitelesítésekor.
      • Regisztráció és bejelentkezési hivatkozások, ha a felhasználó nincs hitelesítve.
  • Egy útvonalvédelmi AuthorizeGuard, amely hozzáadható az útvonalakhoz, és megköveteli a felhasználó hitelesítését az útvonal felkeresése előtt.
  • Egy HTTP-elfogó AuthorizeInterceptor, amely csatolja a hozzáférési jogkivonatot az API-t megcélzó kimenő HTTP-kérésekhez a felhasználó hitelesítésekor.
  • Egy szolgáltatás AuthorizeService, amely kezeli a hitelesítési folyamat alacsonyabb szintű adatait, és a hitelesített felhasználó adatait teszi elérhetővé az alkalmazás többi része számára felhasználás céljából.
  • Egy Angular modul, amely meghatározza az alkalmazás hitelesítési részeihez társított útvonalakat. A bejelentkezési menü komponensét, az elfogót, a védelmet és a szolgáltatást elérhetővé teszi az alkalmazás többi része számára való felhasználásra.

A React alkalmazás általános leírása

A React-sablon hitelesítésének és API-engedélyezésének támogatása a ClientApp/src/components/api-authorization könyvtárban található. A következő elemekből áll:

  • 4 összetevő:
    • Login.js: Az alkalmazás bejelentkezési folyamatának kezelése.
    • Logout.js: Az alkalmazás kijelentkezés folyamatának kezelése.
    • LoginMenu.js: Egy widget, amely a következő hivatkozások egyikét jeleníti meg:
      • A felhasználói profil kezelése és a kijelentkezési hivatkozások a felhasználó hitelesítésekor.
      • Regisztráció és bejelentkezési hivatkozások, ha a felhasználó nincs hitelesítve.
    • AuthorizeRoute.js: Olyan útvonal-összetevő, amely megköveteli a felhasználó hitelesítését a Component paraméterben jelzett összetevő megjelenítése előtt.
  • Egy exportált authService osztály AuthorizeService példánya, amely a hitelesítési folyamat alacsonyabb szintű adatait kezeli, és a hitelesített felhasználó adatait elérhetővé teszi az alkalmazás többi részének felhasználás céljából.

Most, hogy megismerte a megoldás fő összetevőit, részletesebben áttekintheti az alkalmazás egyes forgatókönyveit.

Engedélyezés megkövetelése új API-n

Alapértelmezés szerint a rendszer úgy van konfigurálva, hogy egyszerűen megkövetelje az új API-k engedélyezését. Ehhez hozzon létre egy új vezérlőt, és adja hozzá a [Authorize] attribútumot a vezérlőosztályhoz vagy a vezérlőn belüli bármely művelethez.

Az API-hitelesítési kezelő testreszabása

Az API JWT-kezelőjének konfigurációjának testreszabásához konfigurálja a JwtBearerOptions-példányt:

services.AddAuthentication()
    .AddIdentityServerJwt();

services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme,
    options =>
    {
        ...
    });

Az API JWT-kezelője olyan eseményeket vet fel, amelyek lehetővé teszik a hitelesítési folyamat vezérlését JwtBearerEventshasználatával. Az API-engedélyezés támogatásához AddIdentityServerJwt regisztrálja saját eseménykezelőit.

Az esemény kezelésének testreszabásához szükség szerint csomagolja be a meglévő eseménykezelőt további logikával. Például:

services.Configure<JwtBearerOptions>(
    IdentityServerJwtConstants.IdentityServerJwtBearerScheme,
    options =>
    {
        var onTokenValidated = options.Events.OnTokenValidated;       

        options.Events.OnTokenValidated = async context =>
        {
            await onTokenValidated(context);
            ...
        }
    });

Az előző kódban a OnTokenValidated eseménykezelőt egy egyéni implementáció váltja fel. Ez a megvalósítás:

  1. Meghívja az API engedélyezési támogatás által biztosított eredeti implementációt.
  2. Futtassa saját egyéni logikáját.

Ügyféloldali útvonal védelme (Angular)

Az ügyféloldali útvonalak védelmére úgy van szükség, hogy hozzáadjuk az engedélyezési védelmet az útvonalak konfigurálásakor futtatandó védelmi beállítások listájához. Példaként láthatja, hogyan van konfigurálva a fetch-data útvonal a főalkalmazás Angular modulján belül:

RouterModule.forRoot([
  // ...
  { path: 'fetch-data', component: FetchDataComponent, canActivate: [AuthorizeGuard] },
])

Fontos megemlíteni, hogy az útvonalak védelme nem védi a tényleges végpontot (amelyhez továbbra is egy [Authorize] attribútumot kell alkalmazni), de csak akkor akadályozza meg a felhasználót, hogy a hitelesítés nélkül navigáljon az adott ügyféloldali útvonalra.

API-kérések hitelesítése (Angular)

Az alkalmazás mellett üzemeltetett API-khoz érkező kérések hitelesítése automatikusan történik az alkalmazás által meghatározott HTTP-ügyfélfogó használatával.

Ügyféloldali útvonal védelme (React)

Ügyféloldali útvonal védelme az egyszerű AuthorizeRoute összetevő helyett a Route összetevő használatával. Figyelje meg például, hogyan van konfigurálva a fetch-data útvonal a App összetevőn belül:

<AuthorizeRoute path='/fetch-data' component={FetchData} />

Útvonal védelme:

  • Nem védi a tényleges végpontot (amelyhez továbbra is [Authorize] attribútum szükséges).
  • Csak akkor akadályozza meg a felhasználót, hogy az adott ügyféloldali útvonalra navigáljon, ha nincs hitelesítve.

API-kérések hitelesítése (React)

A kérelmek hitelesítése a React használatával azzal történik, hogy először importáljuk a authService példányt a AuthorizeService-ból. A hozzáférési jogkivonatot a authService-ból nyerik ki, és az alább látható módon csatolják a kérelemhez. A React-összetevőkben ez a munka általában az componentDidMount életciklus-metódusban vagy valamilyen felhasználói beavatkozás eredményeként történik.

A authService importálása egy összetevőbe

import authService from './api-authorization/AuthorizeService'

A hozzáférési jogkivonat lekérése és csatolása a válaszhoz

async populateWeatherData() {
  const token = await authService.getAccessToken();
  const response = await fetch('api/SampleData/WeatherForecasts', {
    headers: !token ? {} : { 'Authorization': `Bearer ${token}` }
  });
  const data = await response.json();
  this.setState({ forecasts: data, loading: false });
}

Éles környezetbe telepítés

Az alkalmazás éles környezetben való üzembe helyezéséhez a következő erőforrásokat kell kiépíteni:

  • A Identity felhasználói fiókok és az IdentityServer által biztosított engedélyek tárolására használt adatbázis.
  • Gyártási tanúsítvány a jogkivonatok aláírásához.
    • A tanúsítványnak nincsenek konkrét követelményei; lehet egy önaláírt tanúsítvány vagy egy hitelesítésszolgáltatón keresztül kiépített tanúsítvány.
    • Ez olyan szabványos eszközökkel hozható létre, mint a PowerShell vagy az OpenSSL.
    • Telepíthető a célgépek tanúsítványtárolójába, vagy .pfx fájlként, erős jelszóval.

Példa: Üzembe helyezés nem Azure-beli webszolgáltatón

A web hosting panelen hozza létre vagy töltse be a tanúsítványt. Ezután az alkalmazás appsettings.json fájljában módosítsa a IdentityServer szakaszt, hogy tartalmazza a legfontosabb részleteket. Például:

"IdentityServer": {
  "Key": {
    "Type": "Store",
    "StoreName": "WebHosting",
    "StoreLocation": "CurrentUser",
    "Name": "CN=MyApplication"
  }
}

Az előző példában:

  • StoreName annak a tanúsítványtárolónak a nevét jelöli, amelyben a tanúsítványt tárolják. Ebben az esetben a webtárhelyre mutat.
  • StoreLocation a tanúsítvány betöltésének helye ( ebben az esetbenCurrentUser).
  • Name megfelel a tanúsítvány megkülönböztető tárgyának.

Példa: Üzembe helyezés az Azure App Service-ben

Ez a szakasz azt ismerteti, hogyan helyezheti üzembe az alkalmazást az Azure App Service-ben a tanúsítványtárolóban tárolt tanúsítvány használatával. Ha módosítani szeretné az alkalmazást a tanúsítványtárolóból származó tanúsítvány betöltéséhez, standard szintű szolgáltatási csomagra van szükség, vagy jobb, ha egy későbbi lépésben konfigurálja az alkalmazást az Azure Portalon.

Az alkalmazás appsettings.json fájljában módosítsa a IdentityServer szakaszt, hogy tartalmazza a legfontosabb részleteket:

"IdentityServer": {
  "Key": {
    "Type": "Store",
    "StoreName": "My",
    "StoreLocation": "CurrentUser",
    "Name": "CN=MyApplication"
  }
}
  • Az áruház neve annak a tanúsítványtárolónak a nevét jelöli, ahol a tanúsítványt tárolják. Ebben az esetben a személyes felhasználói tárolóra mutat.
  • Az áruház helye azt jelzi, hogy honnan töltheti be a tanúsítványt (CurrentUser vagy LocalMachine).
  • A tanúsítvány név tulajdonsága megfelel a tanúsítvány megkülönböztetett tárgyának.

Az Azure App Service-ben való üzembe helyezéshez kövesse az Az alkalmazás üzembe helyezése az Azure-ban című cikkben leírt lépéseket, amely bemutatja, hogyan hozhatja létre a szükséges Azure-erőforrásokat, és hogyan helyezheti üzembe az alkalmazást éles környezetben.

Az előző utasítások követését követően az alkalmazás üzembe lesz helyezve az Azure-ban, de még nem működik. Az alkalmazás által használt tanúsítványt az Azure Portalon kell konfigurálni. Keresse meg a tanúsítvány ujjlenyomatát, és kövesse Tanúsítványok betöltésecímű cikkben leírt lépéseket.

Az SSL megemlítése mellett van egy Privát tanúsítványok szakasz az Azure portálon, ahol feltöltheti a kiépített tanúsítványt az alkalmazás használatához.

Miután konfigurálta az alkalmazást és az alkalmazás beállításait az Azure Portalon, indítsa újra az alkalmazást a portálon.

Egyéb konfigurációs beállítások

Az API-engedélyezés támogatása az IdentityServerre épül, konvenciók, alapértelmezett értékek és fejlesztések halmazával, hogy egyszerűbbé tegye az SLA-k használatát. Mondanom sem kell, hogy az IdentityServer teljes ereje elérhető a színfalak mögött, ha a ASP.NET Core-integrációk nem fedik le a forgatókönyvet. A ASP.NET Core-támogatás az "első féltől származó" alkalmazásokra összpontosít, ahol az összes alkalmazást a szervezet hozza létre és telepíti. Ezért nem nyújtunk támogatást olyan dolgokhoz, mint a hozzájárulás vagy az összevonás. Ezekben a forgatókönyvekben használja az IdentityServert, és kövesse a dokumentációt.

Alkalmazásprofilok

Az alkalmazásprofilok előre definiált konfigurációk azokhoz az alkalmazásokhoz, amelyek tovább határozzák meg a paramétereiket. Jelenleg a következő profilok támogatottak:

  • IdentityServerSPA: Az IdentityServer mellett üzemeltetett SPA-t jelöli egyetlen egységként.
    • A redirect_uri alapértelmezettként /authentication/login-callbackértékre van állítva.
    • A post_logout_redirect_uri alapértelmezettként /authentication/logout-callbackértékre van állítva.
    • A hatókörök halmaza magában foglalja a openid, profile, valamint az alkalmazás API-jaihoz definiált összes hatókört.
    • Az engedélyezett OIDC-választípusok halmaza id_token token, vagy minden egyes típus külön-külön (id_token, token).
    • Az engedélyezett válasz mód fragment.
  • SPA: Olyan SPA-t jelöl, amely nem az IdentityServer szolgáltatással van üzemeltetve.
    • A hatókörök halmaza magában foglalja a openid, profile, valamint az alkalmazás API-jaihoz definiált összes hatókört.
    • Az engedélyezett OIDC-választípusok halmaza id_token token, vagy minden egyes típus külön-külön (id_token, token).
    • Az engedélyezett válasz mód fragment.
  • IdentityServerJwt: Az IdentityServerrel együtt üzemeltetett API-t jelöli.
    • Az alkalmazás úgy van konfigurálva, hogy egyetlen hatókörrel rendelkezzen, amely alapértelmezés szerint az alkalmazás nevéhez tartozik.
  • API: Olyan API-t jelöl, amely nem az IdentityServerrel van üzemeltetve.
    • Az alkalmazás úgy van konfigurálva, hogy egyetlen hatókörrel rendelkezzen, amely alapértelmezés szerint az alkalmazás nevéhez tartozik.

A konfiguráció a AppSettings-on keresztül

Konfigurálja az alkalmazásokat a konfigurációs rendszeren keresztül úgy, hogy hozzáadja őket a Clients vagy Resourceslistájához.

Konfigurálja az egyes ügyfelek redirect_uri és post_logout_redirect_uri tulajdonságát az alábbi példában látható módon:

"IdentityServer": {
  "Clients": {
    "MySPA": {
      "Profile": "SPA",
      "RedirectUri": "https://www.example.com/authentication/login-callback",
      "LogoutUri": "https://www.example.com/authentication/logout-callback"
    }
  }
}

Az erőforrások konfigurálásakor az alábbi módon konfigurálhatja az erőforrás hatóköreit:

"IdentityServer": {
  "Resources": {
    "MyExternalApi": {
      "Profile": "API",
      "Scopes": "a b c"
    }
  }
}

Konfiguráció kódon keresztül

Az ügyfeleket és az erőforrásokat programozottan is konfigurálhatja a beállítások konfigurálására alkalmas AddApiAuthorization metódus túlterhelésével.

AddApiAuthorization<ApplicationUser, ApplicationDbContext>(options =>
{
    options.Clients.AddSPA(
        "My SPA", spa =>
        spa.WithRedirectUri("http://www.example.com/authentication/login-callback")
           .WithLogoutRedirectUri(
               "http://www.example.com/authentication/logout-callback"));

    options.ApiResources.AddApiResource("MyExternalApi", resource =>
        resource.WithScopes("a", "b", "c"));
});

További erőforrások