Implementera JWT-autentisering i Node.js API:er som ett proffs

Hem » Python » Implementera JWT-autentisering i Node.js API:er som ett proffs

Om du bygger API:er med Node.js är det en av de saker som kan kännas skrämmande till en början att lägga till korrekt autentisering med JWT, men det behöver det verkligen inte vara. Med en handfull väl valda bibliotek, en tydlig struktur och några goda exempel på validering och säkerhet kan du skydda dina slutpunkter och ändå hålla din kodbas ren och lättskött.

I den här guiden går vi igenom hur man implementerar JWT-baserad autentisering i ett Node.js API med hjälp av Express, MongoDB och verktyg som jsonwebtoken, bcrypt, Joi och dotenv, och vi kommer också att se hur man validerar tokens med hjälp av en JWKS-slutpunkt från en auktoriseringsserver i mer företagsorienterade scenarier. Du kommer att lära dig hur du designar projektstrukturen, skapar modeller och rutter, genererar och verifierar tokens, lägger till en autentiseringsmellanprogramvara och kopplar ihop allt så att endast autentiserade användare kan nå skyddade resurser.

Vad JSON Web Tokens (JWT) tillför dina Node.js API:er

JSON Web Tokens (JWT) är kompakta, URL-säkra tokens som bär en uppsättning anspråk och tillåter två parter att utbyta autentiserad information utan att behålla sessionstillståndet på serversidan. I ett Node.js API-sammanhang betyder detta att när en användare loggar in och du utfärdar en JWT, kan varje efterföljande begäran verifieras av din backend med endast själva token och en hemlig eller offentlig nyckel, vilket skalar mycket bättre än traditionella serversessioner.

En typisk JWT består av tre delar: en rubrik, en nyttolast och en signatur, alla Base64URL-kodade och separerade med punkter, till exempel. xxxxx.yyyyy.zzzzz. Rubriken anger vanligtvis algoritmen och tokentypen, nyttolasten innehåller användarrelaterade anspråk som ID, roller eller behörigheter, och signaturen säkerställer integritet så att token inte kan manipuleras oupptäckt.

När du implementerar JWT i Node.js API:er använder du normalt token som en bearer-token i Authorization HTTP-rubrik, som Authorization: Bearer <token>, och sedan avkoda och validera den inuti din Express-mellanprogramvara eller route handlers. Om token är giltig kan du koppla den avkodade nyttolasten till förfrågningsobjektet och använda den senare för auktoriseringsbeslut eller för att anpassa svaret.

En kraftfull aspekt av JWT:er är att de är språkoberoende och stöds brett över ekosystem, vilket gör dem till ett utmärkt val för att säkra API:er som konsumeras av React, Vue, mobilappar eller andra tredjepartsklienter. Kombinerat med gedigen validering och korrekt nyckelhantering låter de Node.js-tjänster delta smidigt i OAuth 2.0- och OpenID Connect-baserade arkitekturer.

Projektöversikt: Node.js API med JWT-autentisering

Låt oss föreställa oss ett enkelt men realistiskt Node.js API där användare kan registrera sig, logga in och komma åt skyddade slutpunkter endast efter att ha presenterat en giltig JWT. Vi kommer att förlita oss på Express för routing, Mongoose för MongoDB-integration, jsonwebtoken för att skapa och verifiera tokens, bcrypt för säker lösenordshashing, Joi för indatavalidering och dotenv för konfigurationshantering.

En tydlig mapplayout hjälper till att hålla saker begripliga allt eftersom projektet växer, så istället för att dumpa allt i en fil kommer vi att definiera en grundläggande struktur med separata moduler för konfiguration, databas, modeller, rutter och mellanprogramvara. Denna modulära metod gör det också enklare att enhetstesta specifika delar av autentiseringsflödet.

På en hög nivå kommer API:et att exponera en uppsättning REST-slutpunkter för användarregistrering och inloggning, plus minst en skyddad resurs som bara kan nås med en giltig JWT i begärandehuvudena. Längs vägen kommer vi att se hur man validerar nyttolaster för förfrågningar, hashar och jämför lösenord, genererar tokens som bäddar in användar-ID:t och integrerar en autentiseringsmellanprogramvara som kontrollerar tokens på inkommande samtal.

Samma mönster kan utvidgas till mer komplexa system, inklusive de som integreras med en extern auktoriseringsserver och använder JWKS-slutpunkter för att validera inkommande åtkomsttokens från OAuth 2.0-klienter. Det andra scenariot är särskilt vanligt när du delegerar autentisering till identitetsleverantörer eller behöver stödja enkel inloggning över flera tjänster.

Innan vi går in på implementeringens grunder, låt oss beskriva de viktigaste delarna av miljön som vi kommer att förlita oss på och varför varje beroende är viktigt för säker JWT-hantering i Node.js.

Kärnberoenden för JWT-autentisering i Node.js

Express är ryggraden i många Node.js API:er och tillhandahåller ett minimalt men flexibelt ramverk för routing, middleware och HTTP-hantering. I vårt fall kommer Express att fungera som plattform där vi registrerar rutter som /api/users or /api/auth, och där vi installerar JWT-verifieringsmellanprogramvaran som skyddar känsliga slutpunkter.

Mongoose är ett ODM-bibliotek (Object Data Modeling) som gör det enklare att interagera med MongoDB via scheman och modeller, istället för att arbeta direkt med råa frågor. Vi kommer att använda den för att definiera en User modell med egenskaper som namn, e-postadress och lösenord, och för att bevara eller hämta dessa dokument från databasen på ett typsäkert sätt.

Ocuco-landskapet jsonwebtoken bibliotek är standardvalet i Node.js för att skapa och verifiera JWT:er med en hemlig eller offentlig nyckel. Under inloggningen signerar vi en token som bäddar in användar-ID:t (och alla andra anspråk vi behöver), och senare verifierar vi den token på skyddade rutter och avvisar alla förfrågningar som innehåller en ogiltig, felaktig eller utgången token.

För lösenordssäkerhet används bcrypt för att hasha lösenord i klartext före lagring och för att jämföra angivna inloggningsuppgifter med hashade värden under autentisering. Detta är avgörande, eftersom lagring av råa lösenord eller användning av svaga hashstrategier utsätter dina användare för enorma risker i händelse av en databasläcka, medan bcrypt erbjuder en beprövad och testad lösning.

Joi spelar en stor roll i att validera inkommande data vid API-gränsen, beskriva scheman för objekt och kontrollera att varje förfrågningsnyttolast beter sig som förväntat. Till exempel kan vi definiera att ett e-postmeddelande måste vara korrekt formaterat, att ett lösenord har en minimilängd och att vissa fält är obligatoriska, vilket avsevärt minskar risken för att felaktig eller skadlig inmatning slinker in i vår logik.

Slutligen tillåter dotenv oss att ladda miljövariabler från en .env fil, och förvarar hemligheter som JWT-signeringsnycklar, databas-URL:er eller konfigurationsinställningar utanför källkoden. Detta hjälper till att undvika hårdkodning av känsliga värden och det främjar bättre separation mellan utvecklings-, staging- och produktionskonfigurationer.

Konfigurera Express-servern och miljön

Ingångspunkten för vårt API är vanligtvis en index.js fil där vi bootstrapar Express, registrerar mellanprogram och monterar våra ruttdefinitioner. I den här filen behöver vi vår databaskonfiguration, våra ruttmoduler och all global mellanprogramvara som JSON-bodyparsing eller CORS.

Direkt efter att beroenden har laddats är det en bra idé att anropa require("dotenv").config() så miljövariabler från .env filen blir tillgänglig via process.env. Detta inkluderar nycklar som JWT_PRIVATE_KEY, MONGO_URI eller porten som servern lyssnar på, vilket håller konfigurationen flexibel och säker.

Själva Express-appen använder vanligtvis app.use(express.json()) för att analysera JSON-förfrågningskroppar och montera routrar för specifika URL-prefix, till exempel app.use("/api/users", usersRouter) och app.use("/api/auth", authRouter). Denna separation håller autentiseringsrelaterade rutter och användarhanteringsproblem isolerade från andra delar av API:et.

När miljön är konfigurerad och Express körs är nästa steg att ansluta MongoDB-databasen via en dedikerad modul, ofta en db.js filen, där vi konfigurerar anslutningslogiken.

Konfigurera MongoDB med Mongoose

I db.js modulen importerar vi vanligtvis Mongoose och anropar mongoose.connect() med MongoDB-anslutningssträngen lagrad i en miljövariabel. Vi kan också konfigurera alternativ som återförsökslogik, enhetlig topologi eller anslutningspooler för att säkerställa stabilt beteende i produktionsmiljöer.

Det är vanligt att logga ett meddelande när anslutningen lyckas och hantera fel smidigt så att API:et startar med tydlig diagnostik om MongoDB inte kan nås. I en fullständig applikation kan du till och med välja att avsluta processen om databasanslutningen misslyckas, eftersom många rutter är beroende av den.

När db.js filen är implementerad importerar vi den från index.js och anropa den tidigt under applikationsstart, och se till att vårt API är anslutet till databasen innan vi bearbetar någon förfrågan. Denna separation håller konfigurationen isolerad och återanvändbar, medan index.js fortsätter att fokusera på Express bekymmer.

Med databasen inkopplad kan vi gå vidare till att modellera de data som driver vårt autentiseringssystem, vilket börjar med definitionen av ett användarschema och en modell.

Bygga användarmodellen med JWT-stöd

Ocuco-landskapet User modell, vanligtvis placerad i /models/user.js, definierar strukturen för användardokumenten som lagras i MongoDB och inkapslar beteende relaterat till autentisering. Som minimum kommer vi att inkludera egenskaper som name, email och password, och vi kan också lägga till tidsstämplar, roller eller andra metadata efter behov.

Ett typiskt mönster är att markera e-postadressen som unik och obligatorisk, vilket säkerställer att inga två användare kan registrera sig med samma e-postadress. På samma sätt lagrar inte lösenordsfältet ett värde i vanlig text; istället lagrar vi en bcrypt-hash som genereras vid registreringstillfället eller när användaren uppdaterar sina inloggningsuppgifter.

Ett intressant och mycket praktiskt designbeslut är att lägga till en metod i användarschemat för att generera JWT:er, som tar användarens ID som nyttolast och signerar det med en hemlig nyckel som definieras i miljön. Den här metoden kan anropas under inloggning för att producera en token som är specifik för den användaren, och den håller tokengenereringslogiken samlokaliserad med modellen som äger identitetsdata.

I kombination med Joi-baserade valideringshjälpmedel blir användarmodellen den centrala delen för allt som rör identitet: att beskriva formen på användardata, validera inkommande nyttolaster och generera tokens som används av resten av API:et.

Härifrån kan vi implementera de rutter som ansvarar för att registrera nya konton och autentisera befintliga användare, med hjälp av användarmodellen, bcrypt och Joi tillsammans.

Skapa registreringsvägen

Registreringslogiken finns vanligtvis i en ruttmodul som /routes/users.js, där vi definierar en slutpunkt som POST /api/users för att hantera inkommande registreringsförfrågningar. Den här rutten validerar nyttolasten med Joi, kontrollerar om e-postadressen redan används, hashar lösenordet, skapar användaren och sparar den i databasen.

Innan vi sparar något kan vi använda ett Joi-schema som upprätthåller krav som obligatoriskt namn och e-postadress, korrekt e-postformat och minsta lösenordslängd. Om valideringen misslyckas svarar rutten med en lämplig felstatuskod och ett meddelande, vilket förhindrar att felaktigt formaterade data når affärslogiken.

Om e-postadressen inte redan finns genererar vi ett bcrypt-salt och hashar lösenordet, och ersätter det råa lösenordet med dess hashad version i användarobjektet. Detta hashade värde är det som slutligen lagras i MongoDB, vilket avsevärt begränsar effekterna av potentiella dataintrång.

Efter att den nya användaren har sparats väljer vissa implementeringar också att omedelbart generera en JWT och returnera den i svarshuvudet eller brödtexten, så att användaren anses autentiserad direkt efter registreringen. Andra API:er kan kräva ett separat inloggningssteg, beroende på systemets säkerhetskrav.

När registreringen är på plats kan den kompletterande rutten för inloggning återanvända mycket av samma valideringslogik samtidigt som fokus ligger på att verifiera inloggningsuppgifter och utfärda tokens.

Implementera inloggningsrutten och tokengenerering

Inloggningsflödet hanteras vanligtvis i /routes/auth.js, med en slutpunkt som POST /api/auth som tar emot en e-postadress och ett lösenord i förfrågningstexten. Den här rutten använder Joi igen för att säkerställa att båda fälten finns och är korrekt strukturerade innan användaren försöker autentiseras.

Efter validering frågar rutten databasen efter en användare med den angivna e-postadressen, och om den hittar en använder den bcrypt för att jämföra det angivna lösenordet med den lagrade hashen. Om jämförelsen misslyckas avvisas begäran med ett lämpligt felmeddelande; annars går vi vidare till tokenutfärdande.

I det ögonblick då autentiseringen lyckas anropar vi den tokengenererande metoden som definierats i användarmodellen, vilket skapar en JWT som bäddar in användarens identifierare (och eventuellt andra anspråk) och signerar den med en hemlig nyckel. Denna token kan sedan skickas till klienten, ofta i svarstexten eller en anpassad rubrik, där frontend- eller externa konsumenten lagrar och återanvänder den för framtida förfrågningar.

Från klientsidans perspektiv kommer varje efterföljande anrop till skyddade slutpunkter att inkludera denna JWT i Authorization header som en bärartoken, vilket är precis vad vår mellanprogramvara kommer att leta efter. På serversidan säkerställer en dedikerad autentiseringsmellanprogramvara att vi inte upprepar tokenverifieringslogik i varje enskild rutt.

Innan vi dyker in i den mellanprogramvaran är det värt att notera att samma mönster integreras väl med React eller andra SPA-ramverk, där JWT-baserade flöden vanligtvis används för både autentisering och enkla auktoriseringsbehov.

Bygga autentiserings-mellanprogramvaran för att skydda rutter

Aut.-mellanprogramvaran, ofta implementerad i /middleware/auth.js, fungerar som en grindvakt för alla rutter som kräver autentisering och fångar upp förfrågningar innan de når rutthanteraren. Dess primära uppgift är att läsa JWT från Authorization header, verifiera den och injicera den avkodade nyttolasten i förfrågningsobjektet för senare användning.

Mellanprogramvaran börjar med att kontrollera att Authorization rubriken finns och följer den förväntade Bearer <token> format; om token saknas eller är felaktigt formaterad svarar den omedelbart med en obehörig statuskod. Detta säkerställer att oskyddade förfrågningar inte av misstag hamnar i säkra slutpunkter.

När en token finns anropar mellanprogramvaran jwt.verify() (Från jsonwebtoken bibliotek), vilket skickar token och den hemliga eller offentliga nyckeln som används för signering. Om verifieringen misslyckas på grund av utgångsdatum, signaturavvikelse eller något annat problem, svarar mellanprogramvaran med ett fel; annars fångar den den avkodade nyttolasten.

Många implementeringar kopplar denna avkodade nyttolast till req.user eller en liknande egenskap, så att nedströms rutthanterare kan komma åt användarrelaterade anspråk utan att behöva omtolka eller verifiera token. Slutligen anropar mellanprogramvaran next() för att överföra kontrollen till nästa funktion i Express-pipelinen.

Genom att kombinera denna mellanprogramvara med ruttdefinitioner kan vi enkelt markera vissa slutpunkter som offentliga och andra som skyddade genom att helt enkelt lägga till mellanprogrammet i förfrågningshanteringskedjan för dessa rutter.

Åtkomst till skyddade resurser med JWT

Ett vanligt användningsfall efter implementering av autentisering är att tillhandahålla en rutt som hämtar den aktuella användarprofilen eller en lista över användare, endast tillgänglig för anropare som uppvisar en giltig token. Till exempel, i /routes/users.js, det kan finnas en GET /api/users/me slutpunkt som returnerar information om den inloggade användaren.

För att skydda den här rutten kopplar vi auth-mellanprogramvaran så att alla förfrågningar som träffar den måste innehålla en giltig JWT; annars avslutar mellanprogramvaran förfrågan innan den faktiska hanteraren körs. Eftersom den avkodade nyttolasten redan är kopplad till req.user, kan hanteraren hämta användar-ID:t direkt från token och fråga databasen därefter.

Det här mönstret säkerställer att affärslogiken inte bryr sig om hur autentiseringen utfördes; den litar helt enkelt på närvaron av en verifierad nyttolast och fokuserar på att hämta eller ändra domändata. I mer avancerade inställningar kan du också bädda in roller, behörigheter eller omfång i token och använda dem för att köra auktoriseringskontroller i hanterarna.

Ur konsumentsynpunkt kommer anroparen först att besöka inloggningsslutpunkten för att hämta en token och sedan inkludera den i efterföljande förfrågningar till dessa skyddade slutpunkter, ofta från ett SPA som React, en mobilapp eller en backend-till-backend-integration. Den övergripande upplevelsen är smidig om felmeddelanden är tydliga när en token har gått ut eller är ogiltig.

Vid det här laget har vi gått igenom en fristående JWT-installation med hjälp av en hemlighet som lagras i vår .env fil, men många produktionssystem integreras även med externa auktoriseringsservrar och använder JWKS-slutpunkter för att validera tokens; det är där Express-mellanprogramvara för OAuth-säkrade API:er kommer in i bilden.

Använda en JWKS-slutpunkt för att validera JWT:er i Node.js

I mer avancerade arkitekturer, särskilt de som förlitar sig på OAuth 2.0 och OpenID Connect, tar Node.js API:er ofta emot åtkomsttokens utfärdade av en extern auktoriseringsserver snarare än att generera JWT:er själva. I det här fallet måste API:et validera tokens som signerats med asymmetriska nycklar, vanligtvis RSA eller EC, där endast auktoriseringsservern innehar den privata nyckeln.

En vanlig lösning är att använda ett Express middleware-bibliotek som hämtar JSON Web Key Sets (JWKS) från en konfigurerad slutpunkt som exponeras av auktoriseringsservern. Den JWKS-slutpunkten exponerar publika nycklar i ett standardformat, vilket gör att API:et kan verifiera inkommande JWT-signaturer utan att någonsin behöva hantera privata nycklar.

Du kan till exempel installera ett paket som express-oauth-jwt och konfigurera den med JWKS-URL:en, som https://idsvr.example.com/oauth/v2/oauth-anonymous/jwksoch anslut sedan mellanprogramvaran till dina Node.js API-rutter. När den är integrerad hanterar mellanprogramvaran automatiskt de flesta valideringsuppgifterna för lågnivåtoken.

Med den konfigurationen på plats söker biblioteket upp kid (nyckel-ID) från JWT-headern, laddar ner lämplig publik nyckel från JWKS-slutpunkten (om den inte redan har cachats) och verifierar signaturen med den nyckeln. Den kontrollerar även tokenutgång, utfärdare, målgrupp och andra standardfält, beroende på hur du konfigurerar dess alternativ.

Efter lyckad validering blir den analyserade JWT:n och dess anspråk tillgängliga på Express. request objekt, vilket gör det möjligt för dina hanterare att inspektera omfattningar, användaridentifierare eller anpassade attribut för auktoriserings- och loggningsändamål. Om något går fel (till exempel om token har gått ut eller om signaturen inte matchar) svarar mellanprogramvaran med lämpliga HTTP-felkoder och inkluderar orsaken i WWW-Authenticate rubrik.

Omfattningar, anspråk och auktoriseringslogik i ditt API

När ditt Node.js API litar på en JWT, antingen för att den signerade den direkt eller för att en JWKS-baserad mellanprogramvara har validerat den, är nästa steg att använda dess anspråk och omfång för att implementera auktorisering. Det är här du går bortom enkel autentisering och börjar bevilja eller neka åtkomst baserat på vad användaren har behörighet att göra.

Omfång representerar vanligtvis grovkorniga behörigheter, till exempel read:users or write:orders, och de ingår vanligtvis i JWT:er under ett anspråk som scope or scopes. API:et kan kontrollera om det erforderliga omfånget finns innan en begäran som berör viss affärsdata bearbetas, och returnera ett förbjudet svar om det saknas.

På liknande sätt låter anspråk som användar-ID, e-postadress, roll eller hyresgästinformation dig implementera mer detaljerade regler; till exempel att säkerställa att användare bara får åtkomst till sina egna register eller begränsa administrativa åtgärder till specifika roller. I Express är det enkelt att skriva anpassade mellanprogram som undersöker dessa påståenden på req.user och tillämpa policykontroller.

Vissa JWT-valideringsbibliotek för Express erbjuder inbyggda hooks för att kontrollera nödvändiga omfång som en del av sina alternativ, vilket gör det enkelt att associera varje rutt eller router med en specifik behörighetsuppsättning. Den här metoden håller auktoriseringsproblem nära ruttdefinitionerna, vilket förbättrar läsbarheten och underhållbarheten.

Ur ett designperspektiv är det generellt bättre att behandla JWT-omfång och -anspråk som en del av en deklarativ policy, snarare än att sprida hårdkodade strängar i hela koden, för att undvika inkonsekvenser och underlätta framtida ändringar i din säkerhetsmodell.

Testning och felsökning av JWT-skyddade Node.js API:er

När allt är uppkopplat vill du testa att anropa ditt Node.js API med och utan giltiga JWT:er för att bekräfta att åtkomstkontrollen fungerar exakt som förväntat. Enkla verktyg som curl, HTTPie eller Postman är perfekta för detta, eftersom de låter dig enkelt ställa in rubriker och nyttolaster.

Ett typiskt testflöde innebär att man först anropar inloggningsslutpunkten för att hämta en token och sedan skickar en andra begäran till en skyddad rutt med Authorization: Bearer <token> rubrikuppsättning. Om din implementering är korrekt bör auktoriserade förfrågningar lyckas medan anrop utan tokens eller med ogiltiga tokens bör avvisas.

När man använder ett Express JWT-valideringsbibliotek integrerat med en JWKS-slutpunkt signaleras ofta problem med token med en 401 Unauthorized svar och detaljerad information i WWW-Authenticate svarsrubrik. Om till exempel en åtkomsttoken har gått ut, anger rubriken vanligtvis den specifika felkoden och beskrivningen.

Dessa detaljerade felmeddelanden är mycket användbara under utveckling och felsökning, men du bör vara försiktig så att du inte läcker alltför känslig intern information i produktionsloggar eller svar. Det är ofta en bra idé att centralisera loggning och maskera eller generalisera vissa meddelanden samtidigt som man behåller tillräckligt med kontext för att operatörer ska kunna diagnostisera problem.

Automatiserade tester och simulerade JWT:er kan ytterligare öka ditt förtroende, så att du kan verifiera att auktoriseringsbeteendet är stabilt när du ändrar rutter, lägger till omfång eller omstrukturerar mellanprogramlogik.

Sammantaget ger ett Node.js API som kombinerar Express, MongoDB, bcrypt, Joi och JWT – valfritt backat upp av ett JWKS-baserat valideringsbibliotek – dig en robust grund för att säkra slutpunkter samtidigt som du förblir tillräckligt flexibel för att integrera med moderna frontend-ramverk, mobilappar och företagsidentitetsleverantörer.