Implementer JWT-godkendelse i Node.js API'er som en professionel

Hjem » Python » Implementer JWT-godkendelse i Node.js API'er som en professionel

Hvis du bygger API'er med Node.js, er det at tilføje korrekt godkendelse med JWT en af ​​de ting, der kan føles skræmmende i starten, men det behøver det virkelig ikke at være. Med en håndfuld velvalgte biblioteker, en klar struktur og nogle gode fremgangsmåder omkring validering og sikkerhed kan du beskytte dine endpoints og stadig holde din kodebase ren og vedligeholdelig.

I denne guide gennemgår vi, hvordan man implementerer JWT-baseret godkendelse i en Node.js API ved hjælp af Express, MongoDB og værktøjer som jsonwebtoken, bcrypt, Joi og dotenv, og vi vil også se, hvordan man validerer tokens ved hjælp af et JWKS-slutpunkt fra en autorisationsserver i mere virksomhedsorienterede scenarier. Du lærer, hvordan du designer projektstrukturen, opretter modeller og ruter, genererer og verificerer tokens, tilføjer en autentificerings-middleware og forbinder alt sammen, så kun godkendte brugere kan få adgang til beskyttede ressourcer.

Hvad JSON Web Tokens (JWT) bringer til dine Node.js API'er

JSON Web Tokens (JWT) er kompakte, URL-sikre tokens, der bærer et sæt krav og giver to parter mulighed for at udveksle autentificerede oplysninger uden at bevare server-side sessionstilstanden. I en Node.js API-kontekst betyder det, at når en bruger logger ind, og du udsteder en JWT, kan alle efterfølgende anmodninger verificeres af din backend ved kun at bruge selve tokenet og en hemmelig eller offentlig nøgle, hvilket skalerer langt bedre end traditionelle serversessioner.

En typisk JWT består af tre dele: en header, en payload og en signatur, alle Base64URL-kodet og adskilt af punktummer, for eksempel xxxxx.yyyyy.zzzzz. Headeren angiver normalt algoritmen og tokentypen, nyttelasten indeholder brugerrelaterede krav såsom et ID, roller eller tilladelser, og signaturen sikrer integritet, så tokenet ikke kan manipuleres uopdaget.

Når du implementerer JWT i Node.js API'er, bruger du normalt tokenet som et bearer-token i Authorization HTTP-header, som f.eks. Authorization: Bearer <token>, og derefter afkode og validere den i din Express middleware eller rutehandlere. Hvis tokenet er gyldigt, kan du vedhæfte den afkodede nyttelast til anmodningsobjektet og bruge det senere til godkendelsesbeslutninger eller til at personliggøre svaret.

Et stærkt aspekt ved JWT'er er, at de er sproguafhængige og understøttes bredt på tværs af økosystemer, hvilket gør dem til et fremragende valg til at sikre API'er, der forbruges af React, Vue, mobilapps eller enhver tredjepartsklient. Kombineret med solid validering og korrekt nøglehåndtering, lader de Node.js-tjenester deltage rent i OAuth 2.0- og OpenID Connect-baserede arkitekturer.

Projektoversigt: Node.js API med JWT-godkendelse

Lad os forestille os en simpel, men realistisk Node.js API, hvor brugere kun kan registrere sig, logge ind og få adgang til beskyttede endpoints efter at have præsenteret en gyldig JWT. Vi vil bruge Express til routing, Mongoose til MongoDB-integration, jsonwebtoken til at oprette og verificere tokens, bcrypt til sikker adgangskode-hashing, Joi til inputvalidering og dotenv til konfigurationsstyring.

Et rent mappelayout hjælper med at holde tingene forståelige, efterhånden som projektet vokser, så i stedet for at dumpe alt i én fil, definerer vi en grundlæggende struktur med separate moduler til konfiguration, database, modeller, ruter og middleware. Denne modulære tilgang gør det også nemmere at enhedssteste specifikke dele af godkendelsesflowet.

På et højt niveau vil API'en eksponere et sæt REST-slutpunkter til brugerregistrering og login, plus mindst én beskyttet ressource, der kun kan nås med en gyldig JWT i anmodningsheaderne. Undervejs vil vi se, hvordan man validerer forespørgselsdata, hasher og sammenligner adgangskoder, genererer tokens, der integrerer bruger-ID'et, og integrerer en godkendelses-middleware, der kontrollerer tokens på indgående opkald.

Det samme mønster kan udvides til mere komplekse systemer, herunder dem, der integrerer med en ekstern autorisationsserver og bruger JWKS-slutpunkter til at validere indgående adgangstokens fra OAuth 2.0-klienter. Det andet scenarie er særligt almindeligt, når du delegerer godkendelse til identitetsudbydere eller har brug for at understøtte single sign-on på tværs af flere tjenester.

Før vi går i dybden med implementeringens detaljer, lad os skitsere de vigtigste dele af miljøet, vi vil stole på, og hvorfor hver afhængighed er vigtig for sikker JWT-håndtering i Node.js.

Kerneafhængigheder for JWT-godkendelse i Node.js

Express er rygraden i mange Node.js API'er og leverer et minimalt, men fleksibelt framework til routing, middleware og HTTP-håndtering. I vores tilfælde vil Express fungere som platformen, hvor vi registrerer ruter som f.eks. /api/users or /api/auth, og hvor vi tilslutter JWT-verifikationsmiddleware, der beskytter følsomme endpoints.

Mongoose er et Object Data Modeling (ODM)-bibliotek, der gør det nemmere at interagere med MongoDB via skemaer og modeller i stedet for at arbejde direkte med rå forespørgsler. Vi vil bruge det til at definere en User model med egenskaber som navn, e-mail og adgangskode, og til at bevare eller hente disse dokumenter fra databasen på en typesikker måde.

jsonwebtoken `bibliotek` er standardvalget i Node.js til oprettelse og verificering af JWT'er ved hjælp af en hemmelig eller offentlig nøgle. Under login signerer vi et token, der integrerer bruger-ID'et (og eventuelle andre nødvendige krav), og senere verificerer vi dette token på beskyttede ruter og afviser enhver anmodning, der indeholder et ugyldigt, misdannet eller udløbet token.

Til adgangskodesikkerhed bruges bcrypt til at hashe almindelige tekstadgangskoder før lagring og til at sammenligne angivne legitimationsoplysninger med hashede værdier under godkendelse. Dette er afgørende, fordi lagring af rå adgangskoder eller brug af svage hashingstrategier udsætter dine brugere for enorme risici i tilfælde af en databaselækage, mens bcrypt leverer en gennemprøvet og kamptestet løsning.

Joi spiller en stor rolle i validering af indgående data ved API-grænsen, beskrivelse af skemaer for objekter og kontrol af, at hver anmodningsnyttelast opfører sig som forventet. For eksempel kan vi definere, at en e-mail skal være korrekt formateret, at en adgangskode har en minimumslængde, og at visse felter er obligatoriske, hvilket reducerer risikoen for, at forkert eller ondsindet input slipper ind i vores logik betydeligt.

Endelig giver dotenv os mulighed for at indlæse miljøvariabler fra en .env fil, der holder hemmeligheder som JWT-signeringsnøgler, database-URL'er eller konfigurationsindstillinger uden for kildekoden. Dette hjælper med at undgå hardkodning af følsomme værdier, og det fremmer bedre adskillelse mellem udviklings-, staging- og produktionskonfigurationer.

Opsætning af Express-serveren og -miljøet

Indgangspunktet for vores API er normalt et index.js fil hvor vi bootstrapper Express, registrerer middleware og monterer vores rutedefinitioner. I denne fil skal vi bruge vores databasekonfiguration, vores rutemoduler og eventuel global middleware som JSON body parsing eller CORS.

Lige efter indlæsning af afhængigheder er det en god idé at kalde require("dotenv").config() så miljøvariabler fra .env filen bliver tilgængelig via process.env. Dette inkluderer nøgler som JWT_PRIVATE_KEY, MONGO_URI eller den port, som serveren lytter på, hvilket holder konfigurationen fleksibel og sikker.

Selve Express-appen bruger typisk app.use(express.json()) at analysere JSON-anmodningstekster og montere routere for specifikke URL-præfikser, f.eks. app.use("/api/users", usersRouter) og app.use("/api/auth", authRouter). Denne adskillelse holder godkendelsesrelaterede ruter og brugeradministrationsproblemer isoleret fra andre dele af API'en.

Når miljøet er konfigureret og Express kører, er næste skridt at forbinde MongoDB-databasen via et dedikeret modul, ofte et db.js fil, hvor vi opsætter forbindelseslogikken.

Konfiguration af MongoDB med Mongoose

I db.js modul, importerer vi typisk Mongoose og kalder mongoose.connect() med MongoDB-forbindelsesstrengen gemt i en miljøvariabel. Vi kan også konfigurere muligheder som gentagelseslogik, samlet topologi eller forbindelsespooling for at sikre stabil adfærd i produktionsmiljøer.

Det er almindeligt at logge en besked, når forbindelsen lykkes, og håndtere fejl problemfrit, så hvis MongoDB ikke kan nås, starter API'en op med klar diagnosticering. I en fuld applikation kan du endda vælge at afslutte processen, hvis databaseforbindelsen fejler, da mange ruter afhænger af den.

Når db.js filen er implementeret, importerer vi den fra index.js og kalde den tidligt under applikationsopstart, og sørg for at vores API er forbundet til databasen, før vi behandler en anmodning. Denne adskillelse holder konfigurationen isoleret og genanvendelig, mens index.js forbliver fokuseret på Express' bekymringer.

Når databasen er tilsluttet, kan vi gå videre til modellering af de data, der driver vores autentificeringssystem, hvilket starter med definitionen af ​​et brugerskema og en model.

Opbygning af brugermodellen med JWT-understøttelse

User model, normalt placeret i /models/user.js, definerer strukturen af ​​de brugerdokumenter, der er gemt i MongoDB, og indkapsler adfærd relateret til godkendelse. Som minimum vil vi inkludere ejendomme som f.eks. name, email og password, og vi kan også tilføje tidsstempler, roller eller andre metadata efter behov.

Et typisk mønster er at markere e-mailfeltet som unikt og obligatorisk, hvilket sikrer, at ikke to brugere kan registrere sig med den samme e-mailadresse. Ligeledes gemmer adgangskodefeltet ikke en almindelig tekstværdi; i stedet gemmer vi en bcrypt-hash, der genereres ved registrering eller når brugeren opdaterer sine legitimationsoplysninger.

En interessant og meget praktisk designbeslutning er at tilføje en metode på brugerskemaet til at generere JWT'er, som tager brugerens ID som nyttelast og signerer den med en hemmelig nøgle defineret i miljøet. Denne metode kan kaldes under login for at producere et token specifikt for den pågældende bruger, og den holder tokengenereringslogik samlokaliseret med den model, der ejer identitetsdataene.

I kombination med Joi-baserede valideringshjælpere bliver brugermodellen det centrale element for alt, der har med identitet at gøre: beskrivelse af brugerdataenes form, validering af indgående nyttelast og generering af tokens, der bruges af resten af ​​API'en.

Herfra kan vi implementere de ruter, der er ansvarlige for registrering af nye konti og godkendelse af eksisterende brugere, ved hjælp af brugermodellen, bcrypt og Joi i tandem.

Oprettelse af registreringsruten

Registreringslogikken findes normalt i et rutemodul som f.eks. /routes/users.js, hvor vi definerer et slutpunkt, såsom POST /api/users til at håndtere indgående tilmeldingsanmodninger. Denne rute vil validere nyttelasten ved hjælp af Joi, kontrollere om e-mailen allerede er i brug, hashe adgangskoden, oprette brugeren og gemme den i databasen.

Før vi persisterer noget, kan vi bruge et Joi-skema, der håndhæver krav som obligatorisk navn og e-mail, korrekt e-mailformat og minimumslængde på adgangskoden. Hvis valideringen mislykkes, svarer ruten med en passende fejlstatuskode og -meddelelse, hvilket forhindrer misdannede data i at nå forretningslogikken.

Hvis e-mailen ikke allerede findes, genererer vi et bcrypt-salt og hasher adgangskoden, hvorved den rå adgangskode erstattes med dens hashede version i brugerobjektet. Denne hashede værdi er det, der i sidste ende gemmes i MongoDB, hvilket betydeligt begrænser virkningen af ​​potentielle databrud.

Efter at have gemt den nye bruger, vælger nogle implementeringer også at generere en JWT med det samme og returnere den i svarheaderen eller -brødteksten, så brugeren betragtes som godkendt umiddelbart efter registrering. Andre API'er kan kræve et separat logintrin, afhængigt af systemets sikkerhedskrav.

Når registreringen er på plads, kan den ledsagende rute til login genbruge meget af den samme valideringslogik, samtidig med at der fokuseres på at verificere legitimationsoplysninger og udstede tokens.

Implementering af loginruten og tokengenerering

Login-processen håndteres typisk i /routes/auth.js, med et slutpunkt som POST /api/auth der modtager en e-mail og adgangskode i anmodningsteksten. Denne rute bruger Joi igen for at sikre, at begge felter er til stede og korrekt struktureret, før brugeren forsøges at godkende.

Efter validering forespørger ruten databasen efter en bruger med den givne e-mail, og hvis den finder en, bruger den bcrypt til at sammenligne den angivne adgangskode med den gemte hash. Hvis sammenligningen mislykkes, afvises anmodningen med en passende fejlmeddelelse; ellers går vi videre til tokenudstedelse.

I det øjeblik, hvor godkendelsen er vellykket, kalder vi den token-genererende metode, der er defineret på brugermodellen, som opretter en JWT, der integrerer brugerens identifikator (og muligvis andre krav) og signerer den med en hemmelig nøgle. Dette token kan derefter sendes til klienten, ofte i svarteksten eller en brugerdefineret header, hvor frontend'en eller den eksterne forbruger gemmer og genbruger det til fremtidige anmodninger.

Fra klientsidens perspektiv vil ethvert efterfølgende kald til beskyttede slutpunkter inkludere denne JWT i Authorization header som en bearer-token, hvilket er præcis, hvad vores middleware vil lede efter. På serversiden sikrer en dedikeret godkendelses-middleware, at vi ikke gentager token-verifikationslogik i hver eneste rute.

Før vi dykker ned i den middleware, er det værd at bemærke, at det samme mønster integrerer fint med React eller andre SPA-frameworks, hvor JWT-baserede flows ofte bruges til både godkendelse og simple autorisationsbehov.

Opbygning af Auth Middleware for at beskytte ruter

Aut.-middleware, ofte implementeret i /middleware/auth.js, fungerer som gatekeeper for enhver rute, der kræver godkendelse, og opfanger anmodninger, før de når rutehandleren. Dens primære opgave er at læse JWT'en fra Authorization header, verificer den og injicer den afkodede nyttelast i anmodningsobjektet til senere brug.

Middlewaren begynder med at kontrollere, at Authorization header findes og følger den forventede Bearer <token> format; hvis tokenet mangler eller er forkert udformet, reagerer det straks med en uautoriseret statuskode. Dette sikrer, at ubeskyttede anmodninger ikke ved et uheld glider ind i sikrede slutpunkter.

Når en token er til stede, kalder middlewaren jwt.verify() (fra jsonwebtoken bibliotek), hvor tokenet og den hemmelige eller offentlige nøgle, der bruges til underskrift, videregives. Hvis verifikationen mislykkes på grund af udløb, uoverensstemmelse i signaturen eller andre problemer, svarer middlewaren med en fejl; ellers registrerer den den dekodede nyttelast.

Mange implementeringer knytter denne afkodede nyttelast til req.user eller en lignende egenskab, så downstream-rutehåndterere kan få adgang til brugerrelaterede krav uden at skulle genparse eller genverificere tokenet. Endelig kalder middleware-systemet next() for at overføre kontrollen til den næste funktion i Express-pipelinen.

Ved at kombinere denne middleware med rutedefinitioner kan vi nemt markere nogle slutpunkter som offentlige og andre som beskyttede ved blot at tilføje middlewaren til anmodningshåndteringskæden for disse ruter.

Adgang til beskyttede ressourcer med JWT

Et almindeligt anvendelseseksempel efter implementering af godkendelse er at levere en rute, der henter den aktuelle brugerprofil eller en liste over brugere, som kun er tilgængelig for opkaldere, der fremviser et gyldigt token. For eksempel, i /routes/users.js, der kan være en GET /api/users/me slutpunkt, der returnerer oplysninger om den indloggede bruger.

For at beskytte denne rute tilknytter vi auth-middlewaren, så enhver anmodning, der rammer den, skal indeholde en gyldig JWT; ellers vil middlewaren afslutte anmodningen, før den faktiske handler udføres. Fordi den afkodede nyttelast allerede er knyttet til req.user, kan handleren hente bruger-ID'et direkte fra tokenet og forespørge databasen i overensstemmelse hermed.

Dette mønster sikrer, at forretningslogikken er ligeglad med, hvordan godkendelsen blev udført; den stoler blot på tilstedeværelsen af ​​en verificeret nyttelast og fokuserer på at hente eller ændre domænedata. I mere avancerede opsætninger kan du også integrere roller, tilladelser eller scopes i tokenet og bruge dem til at udføre godkendelsestjek i handlerne.

Fra et forbrugersynspunkt vil den, der ringer op, først nå login-slutpunktet for at få et token og derefter inkludere det i efterfølgende anmodninger til disse beskyttede slutpunkter, ofte fra et SPA som React, en mobilapp eller en backend-to-backend-integration. Den samlede oplevelse er problemfri, hvis fejlmeddelelserne er tydelige, når et token er udløbet eller ugyldigt.

På dette tidspunkt har vi dækket en selvstændig JWT-opsætning ved hjælp af en hemmelighed gemt i vores .env fil, men mange produktionssystemer integrerer også med eksterne autorisationsservere og bruger JWKS-slutpunkter til at validere tokens; det er her, Express middleware til OAuth-sikrede API'er kommer i spil.

Brug af et JWKS-slutpunkt til at validere JWT'er i Node.js

I mere avancerede arkitekturer, især dem der er afhængige af OAuth 2.0 og OpenID Connect, modtager Node.js API'er ofte adgangstokens udstedt af en ekstern autorisationsserver i stedet for selv at generere JWT'er. I dette tilfælde skal API'en validere tokens signeret med asymmetriske nøgler, typisk RSA eller EC, hvor kun autorisationsserveren besidder den private nøgle.

En almindelig løsning er at bruge et Express middleware-bibliotek, der henter JSON Web Key Sets (JWKS) fra et konfigureret slutpunkt, der er eksponeret af Authorization Server. Det pågældende JWKS-slutpunkt eksponerer offentlige nøgler i et standardformat, hvilket gør det muligt for API'en at verificere indgående JWT-signaturer uden nogensinde at skulle administrere private nøgler.

For eksempel kan du installere en pakke som f.eks. express-oauth-jwt og konfigurer den med JWKS URL'en, f.eks. https://idsvr.example.com/oauth/v2/oauth-anonymous/jwks, og tilslut derefter middlewaren til dine Node.js API-ruter. Når den er integreret, håndterer middlewaren automatisk de fleste lavniveau-tokenvalideringsopgaver.

Med den konfiguration på plads, slår biblioteket op i kid (nøgle-ID) fra JWT-headeren, downloader den relevante offentlige nøgle fra JWKS-slutpunktet (hvis den ikke allerede er cachelagret) og verificerer signaturen ved hjælp af den pågældende nøgle. Den kontrollerer også tokenudløb, udsteder, målgruppe og andre standardfelter, afhængigt af hvordan du konfigurerer dens indstillinger.

Efter vellykket validering bliver den parsede JWT og dens krav tilgængelige på Express. request objekt, der gør det muligt for dine handlere at inspicere scopes, bruger-id'er eller brugerdefinerede attributter til godkendelses- og logføringsformål. Hvis noget går galt (for eksempel hvis tokenet er udløbet, eller signaturen ikke stemmer overens), svarer middlewaren med passende HTTP-fejlkoder og inkluderer årsagen i WWW-Authenticate header.

Omfang, krav og godkendelseslogik i din API

Når din Node.js API har tillid til en JWT, enten fordi den har signeret den direkte, eller fordi en JWKS-baseret middleware har valideret den, er næste trin at bruge dens krav og scopes til at implementere godkendelse. Det er her, du går ud over simpel godkendelse og begynder at give eller nægte adgang baseret på, hvad brugeren har tilladelse til at gøre.

Scopes repræsenterer typisk grovkornede tilladelser, såsom read:users or write:orders, og de er normalt inkluderet i JWT'er under et krav som scope or scopes. API'en kan kontrollere, om det nødvendige omfang er til stede, før en anmodning, der berører bestemte forretningsdata, behandles, og returnere et forbudt svar, hvis det mangler.

På samme måde giver krav som bruger-ID, e-mail, rolle eller lejeroplysninger dig mulighed for at implementere mere detaljerede regler; for eksempel at sikre, at brugerne kun har adgang til deres egne poster eller begrænse administrative handlinger til bestemte roller. I Express er det ligetil at skrive brugerdefinerede middlewares, der undersøger disse påstande. req.user og anvende politikkontroller.

Nogle JWT-valideringsbiblioteker til Express tilbyder indbyggede hooks til at kontrollere nødvendige scopes som en del af deres muligheder, hvilket gør det nemt at knytte hver rute eller router til et specifikt tilladelsessæt. Denne tilgang holder godkendelsesproblemer tæt på rutedefinitionerne, hvilket forbedrer læsbarheden og vedligeholdelsen.

Fra et designperspektiv er det generelt bedre at behandle JWT-scopes og -claims som en del af en deklarativ politik i stedet for at sprede hardcodede strenge i hele din kode for at undgå uoverensstemmelser og lette fremtidige ændringer i din sikkerhedsmodel.

Test og fejlfinding af JWT-beskyttede Node.js API'er

Når alt er tilsluttet, vil du gerne teste kald af din Node.js API med og uden gyldige JWT'er for at bekræfte, at adgangskontrollen opfører sig præcis som forventet. Enkle værktøjer som curl, HTTPie eller Postman er perfekte til dette, da de giver dig mulighed for nemt at indstille headers og payloads.

Et typisk testflow involverer først at kalde login-slutpunktet for at hente et token og derefter sende en anden anmodning til en beskyttet rute med Authorization: Bearer <token> overskriftssæt. Hvis din implementering er korrekt, burde autoriserede anmodninger lykkes, mens kald uden tokens eller med ugyldige tokens burde afvises.

Når man bruger et Express JWT-valideringsbibliotek integreret med et JWKS-slutpunkt, signaleres ethvert problem med tokenet ofte med en 401 Unauthorized svar og detaljerede oplysninger i WWW-Authenticate svaroverskrift. Hvis f.eks. et adgangstoken er udløbet, vil headeren normalt angive den specifikke fejlkode og beskrivelse.

Disse detaljerede fejlmeddelelser er meget nyttige under udvikling og fejlfinding, men du skal være forsigtig med ikke at lække alt for følsomme interne oplysninger i produktionslogfiler eller svar. Det er ofte en god idé at centralisere logføring og maskere eller generalisere bestemte meddelelser, samtidig med at der bevares tilstrækkelig kontekst til, at operatørerne kan diagnosticere problemer.

Automatiserede tests og simulerede JWT'er kan yderligere øge din tillid, så du kan verificere, at autorisationsadfærden er stabil, når du ændrer ruter, tilføjer scopes eller refaktorerer middleware-logik.

Alt dette kombinerer en Node.js API, der kombinerer Express, MongoDB, bcrypt, Joi og JWT – eventuelt understøttet af et JWKS-baseret valideringsbibliotek – og giver dig et robust fundament for at sikre endpoints, samtidig med at du forbliver fleksibel nok til at integrere med moderne frontend-frameworks, mobilapps og virksomhedsidentitetsudbydere.