Implementera ett enkelt klientbaserat OIDC-SDK

Introduktion#

Logto ger våra utvecklare och företagsgrupper en omfattande lösning för kundidentitets- och åtkomsthantering (CIAM). Vi erbjuder ett brett utbud av färdiganvända SDK:er för olika plattformar och applikationsramverk. Kombinerat med vår Logto-molntjänst kan du enkelt upprätta ett mycket säkert användarauktoriseringsflöde för din applikation på några minuter. Som ett företag som föddes ur utvecklargemenskapen, omfamnar och värderar Logto vårt samhällsengagemang. Utöver de officiellt utvecklade Logto SDK:erna, uppmuntrar och välkomnar vi kontinuerligt utvecklare från samhället att bidra med sin expertis genom att skapa mer diversifierade och användarvänliga SDK:er, som uppfyller de unika behoven på olika plattformar och ramverk. I denna artikel kommer vi kort att demonstrera hur man implementerar ett auth-SDK enligt OIDC-standarden, steg för steg.

Kontext#

OpenID Connect (OIDC)-flödet är ett autentiseringsprotokoll som bygger på OAuth 2.0-ramverket för att tillhandahålla identitetsverifiering och enkel inloggning. Det gör det möjligt för användare att autentisera sig med en applikation och få åtkomst till alla privata resurser säkert. Se OIDC-specifikationerna för mer information.

Arbetsflöde#

Ett standardflöde för auktorisationskod innehåller följande steg:

Autentiseringsflöde#

1. Användare initierar inloggningsförfrågan: En anonym användare kommer till din applikation från en offentlig ingång. Försöker bli autentiserad och kanske begär vidare åtkomst till en skyddad resurs på en tredjepartsapplikation eller tjänst.
2. Användarautentisering: Klientappen genererar en autentiserings-URI och skickar en förfrågan till auktorisationsservern, som omdirigerar användaren till dess inloggningssida. Användaren interagerar med inloggningssidan med ett brett spektrum av inloggningsmetoder och blir autentiserad av auktorisationsservern.
3. Hantera inloggningsåterkallelse: Vid en lyckad autentisering kommer användaren att omdirigeras tillbaka till din applikation med ett beviljat authorization_code. Detta authorization_code innehåller alla relevanta behörigheter kopplade till autentiseringsstatusen och begärda åtkomstdata.
4. Tokenutbyte: Begär tokenutbyte med hjälp av authorization_code som extraheras från omdirigeringsadressen ovan. I utbyte:
   • id_token: En digitalt signerad JWT som innehåller identitetsinformation om den autentiserade användaren.
   • access_token: Ett oöverskådligt access_token som kan användas för att komma åt användarens grundläggande informationstjänst endpoint.
   • refresh_token: Referenstoken som möjliggör för användaren att behålla kontinuerlig utbyte för en access_token

Auktoriseringsflöde#

1. Åtkomst till användarinformation: För att komma åt mer användarinformation kan applikationen göra ytterligare förfrågningar till användarinformationstjänsten med hjälp av det oöverskådliga access_token som erhölls under det initiala tokenutbytesflödet. Detta möjliggör hämtning av ytterligare detaljer om användaren, såsom deras e-postadress eller profilbild.
2. Bevilja åtkomst till den skyddade resursen: Om nödvändigt kan applikationen göra ytterligare förfrågningar till tokenväxlingsendpointen genom att använda refresh_token kombinerad med resource och scope-parametrar, för att erhålla ett särskilt access_token för användaren att komma åt målet resursen. Denna process resulterar i utfärdandet av ett JWT-formaterat access_token som innehåller all nödvändig auktoriseringsinformation för att komma åt den skyddade resursen.

Implementering#

Vi kommer att följa några designstrategier inom vårt @logto/client JavaScript SDK för att demonstrera processen att implementera ett enkelt SDK för din egen klientapplikation. Kom ihåg att den detaljerade kodstrukturen kan skilja sig beroende på det klientramverk du arbetar med. Känn dig fri att välja något av de officiella Logto SDK:erna som exempel för ditt eget SDK-projekt.

Förhandsgranskning#

Konstruktor#

Konstruktorn bör ta en logtoConfig som sin indata. Detta ger alla nödvändiga konfigurationsinställningar du behöver för att upprätta en auktoriserad anslutning via detta SDK.

Beroende på plattformen eller ramverket du använder för SDK:et kan du skicka in en bestående lokal lagringsinstans till konstruktorn. Denna lagringsinstans kommer att användas för att lagra alla auktoriseringsrelaterade tokens och hemligheter.

Initiera användarautentisering#

Innan en autentiseringsförfrågnings-URL genereras är det viktigt att slutföra flera förberedande steg för att säkerställa en säker process.

Hämta OIDC-konfigurationer från auktorisationsservern#

Definiera en privat metod `getOidcConfigs`` för att hämta OIDC-konfigurationer från auktorisationsserverns upptäcktsendpoint. OIDC-konfigurationsresponsen innehåller all metadatainformation som klienten kan använda för att interagera med auktorisationsservern, inklusive dess endpoint-platser och serverns kapacitet. (Vänligen se OAuth OAuth Authorization Server Metadata Specs för mer information.)

PKCE-generator#

Ett PKCE (Proof Key for Code Exchange)-valideringsflöde är väsentligt för alla offentliga klientauktoriseringsflöden för kodutbyte. Det minskar risken för avlyssningsattacker mot authorization_code. Därför krävs en code_challenge och code_verifier för alla offentliga klientapplikationer (t.ex. native app och SPA) auktoriseringsförfrågningar.

Implementeringsmetoderna kan variera beroende på de språk och ramverk du använder. Vänligen se code_challenge och code_verifier spec för de detaljerade definitionerna.

Generera state-parameter#

I auktoriseringsflödet är state-parameter ett slumpmässigt genererat värde som ingår i auktoriseringsförfrågan som skickas av klienten. Det fungerar som en säkerhetsåtgärd för att förhindra cross-site request forgery (CSRF)-attacker.

Lagra mellansessioninformaiton#

Det finns flera parametrar som behöver bevaras i lagringen för valideringsändamål efter att användaren blivit autentiserad och omdirigerad tillbaka till klientens sida. Vi kommer att implementera en metod för att ställa in dessa mellanliggande parametrar i lagringen.

Logga in#

Låt oss sammanfatta allt som implementerats ovan, definiera en metod för att generera en användarinloggnings-URL och omdirigera användaren till auktoriseringsservern för att bli autentiserad.

Hantera användarinloggningsåterkallelse#

I föregående avsnitt skapade vi en inloggningsmetod som genererar en URL för användarautentisering. Denna URL innehåller alla erforderliga parametrar som behövs för att initiera ett autentiseringsflöde från en klientapp. Metoden omdirigerar användaren till auktoriseringsserverns inloggningssida för autentisering. Efter en lyckad inloggning kommer slutanvändaren att omdirigeras tillbaka till redirect_uri-platsen som angavs tidigare. Alla nödvändiga parametrar kommer att bäras i redirect_uri för att slutföra efterföljande tokenutbytesflöden.

Extrahera och verifiera återkallelse-URL#

Detta valideringssteg är extremt viktigt för att förhindra alla former av förfalskade auktoriseringsåterkallelsattacker. Återkallelse-URL:n MÅSTE verifieras noggrant innan en ytterligare kodbytesbegäran skickas till auktoriseringsservern. Först och främst måste vi hämta signInSession-data vi lagrade från appens lagring.

Verifiera sedan återkallelse-URL:ns parameter innan du skickar ut tokenbytesförfrågan.

• Använd den tidigare lagrade redirectUri för att verifiera om callbackUri är densamma som den vi skickade till auktoriseringsservern.
• Använd den tidigare lagrade state för att verifiera om det returnerade state är detsamma som den vi skickade till auktoriseringsservern.
• Kontrollera om något fel returneras av auktoriseringsservern
• Kontrollera om det returnerade authorization_code existerar

Skicka kodbytesbegäran#

Som det sista steget av användarens autentiseringsflöde kommer vi att använda den returnerade authorization_code för att skicka en förfrågan om tokenutbyte och erhålla de nödvändiga autensieringstoken. För mer information om definitionerna av request-parametrar, se bytespecificeringen för token.

• code: det authorization_code vi fick från callback URI
• clientId: applikations-ID
• redirectUri: Samma värde används när inloggnings-URL genereras för användaren.
• codeVerifier: PKCE-kodverifierare. Precis som med redirectUri kommer auktoriseringsservern att jämföra detta värde med det vi tidigare skickade, vilket säkerställer valideringen av den inkommande förfrågan om tokenbyte.

Hantera inloggningsåterkallelsen#

Sammanfatta allt vi har. Låt oss bygga metoden handleSignInCallback:

Som ett resultat, kommer förfrågan om tokenbyte att returnera följande token:

• id_token: OIDC idToken, en JSON Web Token (JWT) som innehåller identitetsinformation om den autentiserade användaren. id_token kan också användas som den enda källan till sanning (SSOT) för en användares autentiseringsstatus.
• access_token: Den standardgodkännandekod som returneras av auktoriseringsservern. Kan användas för att ringa användarinformationstjänstens endpoint och hämta autentiserad användarinformation.
• refresh_token: (om offline_access scope är närvarande i autentiseringsbegäran): Detta refresh token gör det möjligt för klientapplikationen att erhålla en ny access token utan att kräva att användaren autentiserar sig igen, vilket ger långvarig åtkomst till resurserna.
• expires_in: Varaktigheten av tid i sekunder, under vilken access token är giltig innan den går ut.

Validering av ID token#

Att verifiera och extrahera påståenden från id_token är ett avgörande steg i autentiseringsprocessen för att säkerställa autentisiteten och integriteten hos token. Här är de viktigaste stegen som är inblandade i verifieringen av en idToken.

• Signaturverifiering: id_token är digitalt signerad av auktoriseringsservern med hjälp av dess privata nyckel. Klientapplikationen behöver validera signaturen med hjälp av auktoriseringsserverns offentliga nyckel. Detta säkerställer att token inte har manipulerats och verkligen har utfärdats av den legitima auktoriseringsservern.
• Utfärdare verifikation: Kontrollera att "iss" (utfärdare) påståendet i id_token matchar det förväntade värdet, vilket indikerar att token utfärdades av rätt auktoriseringsserver.
• Publikverifikation: Se till att "aud" (publik) påståendet i id_token matchar klient-ID:t för klientapplikationen, vilket säkerställer att token är avsedd för klientens
• Kontrollera förfall: Kontrollera att "iat" (utfärdad vid) påståendet i id_token inte har passerat den aktuella tiden, vilket säkerställer att token är fortfarande giltig. Eftersom det finns nätverksöverföringskostnader måste vi ställa in en utfärdad tolerans för tid när vi validerar den mottagna tokenens iat-krav.

Den returnerade id_token är en standardiserad JSON Web Token (JWT). Beroende på det ramverk du använder kan du hitta olika praktiska JWT-tokenvalideringspluginer för att hjälpa till vid avkodning och validering av token. För detta exempel kommer vi att använda jose i vårt JavaScript SDK för att underlätta tokenvalidering och avkodning.

Hämta användarinformation#

Efter lyckad användarautentisering kan grundläggande användarinformation hämtas från OIDC id_token som utfärdats av auktoriseringsservern. Men på grund av prestandahänsyn är innehållet i JWT-token begränsat. För att erhålla mer detaljerad användarprofilinformation, erbjuder OIDC-kompatibla auktoriseringsservrar en färdiganpassad användarinformationsendpoint. Denna endpoint tillåter dig att hämta ytterligare användarprofildata genom att skicka förfrågningar om specifika användarprofilscopes.

När du anropar en tokenopsjöningsendpoint utan att indikera en specifik API-ressurs, kommer auktoriseringsservern att utfärda en oöverskådlig typ access_token som standard. Detta access_token kan endast användas för att komma åt användarinformationstjänsten, vilket gör det möjligt att hämta grundläggande användarprofildata.

Hämta access token för skyddad resursauktorisation#

I de flesta fall kräver en klientapplikation inte bara användarautentisering, utan även användarens auktorisering för att komma åt vissa skyddade resurser eller API-tjänster. Här kommer vi att använda det refresh_token som erhölls under inloggningen för att skaffa access_token(s) som specifikt beviljas för att hantera särskilda resurser. Detta gör att vi kan erhålla åtkomst till dessa skyddade API-tjänster.

Sammanfattning#

Vi har tillhandahållit grundläggande metodimplementeringar för användarautentisering och -auktorisering i klientappen. Beroende på din specifika situation kan du organisera och optimera SDK-logiken därefter. Observera att variationer kan existera på grund av olika plattformar och ramverk.

För ytterligare detaljer, utforska SDK-paketen som erbjuds av Logto. Vi uppmuntrar fler användare att delta i utvecklingen och delta i diskussioner med oss. Din feedback och dina bidrag är mycket värdefulla eftersom vi fortsätter att förbättra och utöka SDK:ernas kapacitet.

Bilaga#

Reserverade scopes#

Logto reserverade scopes som du behöver skicka med under den initiala åtkomstförfrågan. Dessa scopes är antingen OIDC-reserverade eller Logto-reserverade grundläggande scopes för att slutföra ett framgångsrikt auktoriseringsflöde.

Scopenamn	Beskrivning
openid	Krävs för att bevilja id_token efter en lyckad autentisering.
offline-access	Krävs för att bevilja en refresh_token som låter din klientapplikation växla och förnya en access_token bortom skärmen.
profile	Krävs för att få tillgång till den grundläggande användarinformationen

Logto Konfiguration#

Egenskapsnamn	Typ	Krävd	Beskrivning	Standardvärde
appId	string	true	Det unika applikationsidentifieraren. Genererad av auktoriseringsservern för att identifiera klientapplikationen.
appSecret	string		Applikationshemligheten används, tillsammans med applikations-ID:t, för att verifiera identiteten av begäraren. Det krävs för konfidentiella klienter som Go web eller Next.js web app, och valfritt för offentliga klienter som native eller singelsidesapplikationer (SPAs)
endpoint	string	true	Din auktoriseringsserversning rotendpoint. Denna egenskap kommer att användas i stor utsträckning för att generera åtkomstförfrågningar.endpoint.
scopes	string lista		Indikerar alla de nödvändiga resurs scopes användaren kan behöva beviljas för att få åtkomst till någon given skyddad resurs.	[reservedScopes]
resources	string lista		Alla de skyddade resursindikatorer användaren kan begära åtkomst för

Användbara metoder#

generateRandomString#