## Introduktion [Logto](https://logto.io/) 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. Skapa din applikation i Logto ## 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: ```mermaid sequenceDiagram actor user as Slutanvändare participant app as Klientapp participant server as Auktorisationsserver participant resource as Privata resurser user ->> app: anonym besökare loggar in app ->> server: skickar autentiseringsförfrågan server -->> user: omdirigera till användarens inloggningssida user ->> server: logga in med referenser server -->> app: omdirigera tillbaka till klientappen med authorization_code app ->> server: tokenväxling förfrågan med authorization_code server ->> app: bevilja id_token, access_token och refresh_token app -->> user: autentiserad app ->> resource: privat API-förfrågan med access_token resource --> server: synkronisera signeringsnyckel resource -->> resource: tokenvalidering resource ->> app: 200 OK ``` #### 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 ```ts class LogtoClient { protected readonly logtoConfig: LogtoConfig; protected readonly storage: Storage; protected oidcConfig: OidcConfig; protected accessTokenMap: Map constructor(logtoConfig: LogtoConfig) {} get async idToken(){} private async getOidcConfig(){} private async getJwksFunction() {} private async verifyIdToken() {} private async saveTokens() {} private async setSignInSession() {} private async getSignInSession() {} private async getAccessTokenByRefreshToken() {} async signIn(redirectUri: string) {} async handlerSignInCallback (callbackUri: string) {} async getUserInfo() {} async getAccessToken(resource?: string, scopes?: string[]) {} } ``` ### Konstruktor Konstruktorn bör ta en [logtoConfig](#logto-config) 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. ```ts class LogtoClient { constructor(logtoConfig: LogtoConfig, storage: Storage) {} } ``` ### 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](https://datatracker.ietf.org/doc/html/rfc8414) för mer information.) ```ts const discoveryPath = "/oidc/.well-known/openid-configuration"; private async getOidcConfigs() { if (this.oidcConfig) { return this.oidcConfig; } const response = await fetch(`${this.logtoConfig.endpoint}${discoveryPath}`) this.oidcConfig = await response.json(); return this.oidcConfig; } ``` #### PKCE-generator Ett [PKCE (Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636)-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](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) och [code_verifier](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) spec för de detaljerade definitionerna. Om du arbetar med en konfidentiell klient eller serverrenderade webbapplikationer som express eller nextjs, hoppa direkt till nästa steg. För mer information om PKCE och skillnaden mellan offentliga kunder och konfidentiella kunder, vänligen kolla vår [OAuth Security Recap](https://blog.logto.io/oauth-security-recap). ```ts class PKCE { readonly codeVerifier: string; readonly codeChallenge: string; constructor() { this.codeVerifier = this.generateCodeVerifier(); this.codeChallenge = this.generateCodeChallenge(this.codeVerifier); } /** * Genererar kodverifierare * * @link [Klienten skapar en kodverifierare](https://datatracker.ietf.org/doc/html/rfc7636#section-4.1) */ private generateCodeVerifier() { return generateRandomString(); } /** * Beräknar S256 PKCE-kodutmaningen för en godtycklig kodverifierare och kodar den i URL-säker base64 * * @param {String} codeVerifier Kodverifierare för att beräkna S256-kodutmaningen för * @link [Klienten skapar kodutmaningen](https://datatracker.ietf.org/doc/html/rfc7636#section-4.2) */ private async generateCodeChallenge(codeVerifier: string) { const encodedCodeVerifier = new TextEncoder().encode(codeVerifier); const codeChallenge = new Uint8Array( await crypto.subtle.digest('SHA-256', encodedCodeVerifier) ); } } ``` #### Generera state-parameter I auktoriseringsflödet är [state-parameter](https://blog.logto.io/oauth-security-recap/#state) 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. ```ts const state = generateRandomString(); ``` #### 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. ```ts protected async setSignInSession (data: { codeVerifier: string; redirectUri: string; state: string; }) { await this.storage.setItem('signInSession', data); } ``` #### 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. ```ts async signIn(redirectUri: string) { const { appId, resources, scopes } = this.logtoConfig; const { authorizationEndpoint } = await this.getOidcConfig(); // Endast för offentliga klientapplikationer const pkce = new PKCE(); const state = generateRandomString(); const queryParameters = new URLSearchParams({ client_id: appId, redirect_uri: redirectUri, code_challenge: pkce.codeChallenge, code_challenge_method: 'S256', state, response_type: 'code', prompt: 'consent', scopes: [...reservedScopes, scopes], }); // Lägg till alla resursindikatorer om några for (const resource of resources ?? []) { urlSearchParameters.append('resource', resource); } const signInUrl = new URL(`${authorizationEndpoint}?${urlSearchParameters.toString()}`); await this.setSignInSession({ redirectUri, state, codeVerifier: pkce.codeVerifier }); navigate(signInUrl); } ``` ### 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. ```ts protected async getSignInSession () { session = await this.storage.getItem('signInSession', data); if (!session) { throw Error('Session not found'); } } ``` 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 ```ts verifyAndParseCodeFromCallbackUri(callbackUri: string, redirectUri: string, state: string) { const url = new URL(callbackUri) const parameters = url.searchParams; if (!callbackUri.startWith(redirectUri)) { throw new Error('redirect_uri_mismatched') } //Kontrollera felmeddelandet. // Om autentiseringen misslyckas kommer användaren att omdirigeras tillbaka med bifogade felparametrar const error = parameters.get('error'); const errorDescription = parameters.get('error_description'); if (error || errorDescription) { throw new Error(`${error}:${errorDescription}`) } // Verifiering av state const callbackState = parameter.get('state'); if (callbackState !== state) { throw new Error('state_mismatch'); } // Extrahera godkännandekod const code = parameters.get('code'); if (!code) { throw new Error('authorization_code_not_found') } return code; } ``` #### 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](https://datatracker.ietf.org/doc/html/rfc8693#section-2). - 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. ```ts const getTokenByAuthorizationCode = async (payload: { code: string; clientId: string; tokenEndpoint: string; redirectUri: string; codeVerifier: string; }) => { const parameters = new URLSearchParams({ client_id: payload.clientId, code: payload.code, code_verifier: payload.codeVerifier, redirect_uri: payload.redirectUri, grant_type: 'authorization_code', }); return fetch(tokenEndpoint, { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' } body: parameters, }); } ``` #### Hantera inloggningsåterkallelsen Sammanfatta allt vi har. Låt oss bygga metoden handleSignInCallback: ```ts private async saveTokens({refreshToken, idToken, accessToken}) { this.storage.setItem('refreshToken', refreshToken); this.storage.setItem('idToken', idToken); // oöverskådligt access token utan resursindikator specificering this.accessTokenMap.setItem('', accessToken) } async handleSignInCallback(callbackUri: string){ const signInSession = await this.getSignInSession(); if (!signInSession) { throw new Error('sign_in_session.not_found'); } const { redirectUri, state, codeVerifier } = signInSession; const code = verifyAndParseCodeFromCallbackUri(callbackUri, redirectUri, state); const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const response = await getTokenByAuthorizationCode({ code, clientId: appId, tokenEndpoint, redirectUri, codeVerifier, }); await this.saveTokens(response); } ``` 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](https://www.npmjs.com/package/jose) i vårt JavaScript SDK för att underlätta tokenvalidering och avkodning. ```sh npm install jose ``` ```ts import {createRemoteJWKSet, jwtVerify} from 'jose'; private async getJwksFunction() { const { jwksUri } = await this.getOidcConfig(); return createRemoteJWKSet(new URL(jwksUri))(); } private async verifyIdToken( idToken: string, clientId: string, issuer: string, ) { const jwks = await this.getJwksFunction(); const result = await jwtVerify(idToken, jwks, { audience: clientId, issuer }); if (Math.abs((result.payload.iat ?? 0) - Date.now() / 1000) > issuedAtTimeTolerance) { throw new Error('id_token.invalid_iat'); } return result; }; ``` ### 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. ```ts async getUserInfo() { const { userinfoEndpoint } = await this.getOidcConfig(); const accessToken = await this.getAccessToken(); return fetch(userinfoEndpoint, { headers: { Authorization: `Bearer ${accessToken}` } }); } ``` ### 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. Under användarinloggning är det avgörande att ange alla API-resursindikatorer till auktoriseringsservern. Efter en lyckad autentisering kan vi endast hämta `access_tokens` för de förkonfigurerade specifika resurserna. För att uppnå detta, före-konfigurera alla nödvändiga API-resursindikatorer i klientappens konfigurationsinställningar innan du genererar inloggnings-URL:n. ```ts private async getAccessTokenByRefreshToken(resource?:string, scopes?: string[]){ const { appId } = this.logtoConfig; const { tokenEndpoint } = await this.getOidcConfig(); const { refreshToken } = await this.storage.getItem('refreshToken'); const parameters = new URLSearchParams({ 'grant_type': 'refresh_token', 'client_id': appId, 'refresh_token': }); if (resource) { parameters.append('resource', resource); } if (scopes?.length) { parameters.append('scope', scopes.join(' ')); } const response = await fetch(tokenEndpoint, { method: 'POST', grant_type: 'authorization_code', body: parameters, }); // spara och ersätt den senaste returnerade refreshToken await this.storage.setItem('refreshToken', response.refreshToken); await this.accessTokenMap.setItem(`${resource}:${scopes.join(_)}`, response.accessToken); return response.accessToken; } async getAccessToken(resource?:string, scopes?: string[]) { if (!this.idToken) { throw new Error('User not authenticated'); } const accessTokenInStorage = this.accessTokenMap.getItem(`${resource}:${scopes.join(_)}`); if (accessTokenInStorage && accessTokenInStorage.expiresAt > Date.now() / 1000) { return accessToken.token; } return await this.getAccessTokenByRefreshToken(resource, scopes); } ``` ## 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 ```ts const generateRandomString = (length = 64) => fromUint8Array(crypto.getRandomValues(new Uint8Array(length)), true); ``` Testa Logto Cloud idag