Implementeer een eenvoudige client-side OIDC SDK

Introductie#

Logto biedt onze ontwikkelaars en zakelijke groepen een uitgebreide Customer Identity and Access Management (CIAM) oplossing. We bieden een breed scala aan kant-en-klare SDK's voor verschillende platforms en applicatiekaders. Gecombineerd met onze Logto cloudservice, kun je moeiteloos een zeer veilige gebruikersautorisatiestroom voor je applicatie in slechts enkele minuten opzetten. Als een bedrijf dat is ontstaan uit de ontwikkelaarsgemeenschap, omarmt en waardeert Logto onze betrokkenheid bij de gemeenschap. Naast de officieel ontwikkelde Logto SDK's, moedigen we ontwikkelaars uit de gemeenschap continu aan en verwelkomen we ze om hun expertise bij te dragen door meer diverse en gebruiksvriendelijke SDK's te creëren, waarmee aan de unieke behoeften van verschillende platforms en kaders wordt voldaan. In dit artikel zullen we kort demonstreren hoe je stapsgewijs een OIDC-standaard authenticatie SDK implementeert.

Context#

De OpenID Connect (OIDC) flow is een authenticatieprotocol dat voortbouwt op het OAuth 2.0-kader om identiteitsverificatie en single sign-onmogelijkheden te bieden. Het stelt gebruikers in staat zichzelf bij een applicatie te authenticeren en verder veilig toegang te krijgen tot privébronnen. Raadpleeg de OIDC-specificaties voor meer details.

Werkstroom#

Een standaard autorisatiecode-flow omvat de volgende stappen:

Authenticatiestroom#

1. Gebruiker initieert het aanmeldverzoek: Een anonieme gebruiker komt via een openbare ingang bij je applicatie. Proberen zich te authenticeren en misschien verder vragen om toegang tot een beschermd middel op een applicatie of dienst van een derde partij.
2. Gebruikersauthenticatie: De client-app genereert een authenticatie-URI en stuurt een verzoek naar de autorisatieserver, die de gebruiker omleidt naar zijn aanmeldingspagina. De gebruiker interacteert met de aanmeldingspagina met behulp van een breed scala aan aanmeldmethoden en wordt geauthenticeerd door de autorisatieserver.
3. Afhandelen van aanmeldingscallback: Na succesvolle authenticatie wordt de gebruiker teruggeleid naar jouw applicatie met een verleende authorization_code. Deze authorization_code bevat alle relevante machtigingen die zijn gekoppeld aan de authenticatiestatus en gevraagde autorisatiegegevens.
4. Tokenuitwisseling: Doe een verzoek om tokenuitwisseling met de authorization_code die is opgehaald uit het bovenstaande redirectadres. In ruil daarvoor:
   • id_token: Een digitaal ondertekende JWT die identiteitsinformatie bevat over de geauthenticeerde gebruiker.
   • access_token: Een ondoorzichtige access_token die kan worden gebruikt om toegang te krijgen tot het gebruikersinfo-eindpunt.
   • refresh_token: Het token waarmee de gebruiker een continue uitwisseling voor een access_token kan behouden.

Autorisatiestroom#

1. Toegang tot gebruikersinformatie: Om meer gebruikersinformatie te benaderen, kan de applicatie aanvullende verzoeken doen aan het UserInfo-eindpunt, gebruikmakend van de ondoorzichtige access_token verkregen uit de initiële tokenuitwisselingsflow. Dit maakt een retrieval mogelijk van aanvullende gegevens over de gebruiker, zoals hun e-mailadres of profielfoto.
2. Toegang verlenen tot het beschermde middel: Indien nodig kan de applicatie aanvullende verzoeken doen aan het tokenuitwisselingsendpunt, gebruikmakend van de refresh_token gecombineerd met resource en scope parameters, om een speciale access_token voor de gebruiker te verkrijgen om toegang te krijgen tot het doelmiddel. Dit proces resulteert in de uitgifte van een JWT-geformateerde access_token die alle benodigde autorisatie-informatie bevat om toegang te krijgen tot het beschermde middel.

Implementatie#

We zullen enkele ontwerpstrategieën volgen binnen onze @logto/client JavaScript SDK om het proces van het implementeren van een eenvoudige SDK voor je eigen client applicatie te demonstreren. Houd er rekening mee dat de gedetailleerde code structuur kan verschillen, afhankelijk van het client framework waarmee je werkt. Voel je vrij om een van de officiële Logto SDK's als voorbeeld voor je eigen SDK project te kiezen.

Voorbeeld#

Constructor#

De constructor moet een logtoConfig als invoer nemen. Dit biedt alle nodige configuraties die je nodig hebt om een authenticatieverbinding tot stand te brengen via deze SDK.

Afhankelijk van het platform of kader dat je gebruikt voor de SDK, kun je een instance van een persistente lokale opslag aan de constructor doorgeven. Deze opslaginstance wordt gebruikt om alle autorisatie-gerelateerde tokens en geheimen op te slaan.

Initiëer gebruikersauthenticatie#

Voordat je een authenticatieverzoek-URL kunt genereren, is het essentieel om verschillende voorbereidende stappen te voltooien om een veilig proces te waarborgen.

Verkrijg OIDC-configuraties van de autorisatieserver#

Definieer een privé methode getOidcConfigs om OIDC-configuraties op te halen van het ontdekkingsendpunt van de autorisatieserver. De OIDC-configuraties reactie bevat alle metadata informatie die de client kan gebruiken om te communiceren met de autorisatieserver, inclusief zijn eindpuntlocaties en de mogelijkheden van de server. (Raadpleeg OAuth OAuth Authorization Server Metadata Specs voor meer details.)

PKCE Generator#

Een PKCE(Proof Key for Code Exchange) validatiestroom is essentieel voor alle openbare client autorisatiecode uitwisselingsflows. Het vermindert het risico van onderschepping van authorization_code aanvallen. Dus een code_challenge en code_verifier is vereist voor alle openbare client applicaties (bijv. native app en SPA) autorisatieverzoeken.

De implementatiemethoden kunnen variëren, afhankelijk van de talen en kaders die je gebruikt. Raadpleeg de code_challenge en code_verifier spec voor gedetailleerde definities.

Genereer staat parameter#

In de autorisatiestroom is de staat parameter een willekeurig gegenereerde waarde die is opgenomen in het autorisatieverzoek dat door de client is verzonden. Het fungeert als een beveiligingsmaatregel om cross-site request forgery (CSRF) aanvallen te voorkomen.

Bewaar tussentijdse sessie-info#

Er zijn verschillende parameters die moeten worden bewaard in de opslag voor validatiedoeleinden nadat de gebruiker is geauthenticeerd en teruggeleid naar de clientkant. We gaan een methode implementeren om die tussentijdse parameters naar de opslag op te slaan.

Aanmelden#

Laten we alles wat hierboven is geïmplementeerd, samenvoegen, een methode definiëren die een URL voor gebruikersaanmelding genereert en de gebruiker omleiden naar de autorisatieserver om te worden geauthenticeerd.

Behandel user sign-in callback#

In de vorige sectie maakten we een aanmeldmethode die een URL voor gebruikersauthenticatie genereert. Deze URL bevat alle vereiste parameters die nodig zijn om een authenticatiestroom vanuit een client-app te initiëren. De methode leidt de gebruiker om naar de aanmeldingspagina van de autorisatieserver voor authenticatie. Na een succesvolle aanmelding wordt de eindgebruiker teruggeleid naar de redirect_uri locatie die hierboven is verstrekt. Alle benodigde parameters worden in de redirect_uri meegedragen om de volgende tokenuitwisselingsflows te voltooien.

Extraheer en verifieer de callback-URL#

Deze validatiestap is uiterst belangrijk om elke vorm van vervalste autorisatiecallback-aanvallen te voorkomen. De callback-URL MOET zorgvuldig worden geverifieerd voordat verdere aanvraag voor code-uitwisseling naar de autorisatieserver wordt verzonden. Allereerst moeten we de signInSession gegevens ophalen die we vanuit de app-opslag hebben opgeslagen.

Verifieer vervolgens de parameters van de callback-URL voordat je het tokenuitwisselingsverzoek verzendt.

• Gebruik de eerder opgeslagen redirectUri om te verifiëren of de callbackUri hetzelfde is als die we naar de autorisatieserver hebben verzonden.
• Gebruik de eerder opgeslagen state om te verifiëren of de geretourneerde staat hetzelfde is als degene die we naar de autorisatieserver hebben verzonden.
• Controleer of er een fout is geretourneerd door de autorisatieserver.
• Controleer of het geretourneerde authorization_code bestaat.

Stuur het code-uitwisselingsverzoek#

Als laatste stap van de gebruikersauthenticatiestroom zullen we de geretourneerde authorization_code gebruiken om een tokenuitwisselingsverzoek te sturen en de vereiste autorisatietokens te verkrijgen. Voor meer details over de definities van de aanvraagparameters, raadpleeg de tokenuitwisselingsspecificatie.

• code: de authorization_code die we van de callback URI hebben ontvangen.
• clientId: de applicatie ID.
• redirectUri: Dezelfde waarde die wordt gebruikt bij het genereren van de aanmeldings-URL voor de gebruiker.
• codeVerifier: PKCE code verifier. Net als de redirectUri, vergelijkt de autorisatieserver deze waarde met degene die we eerder hebben verzonden, wat de validatie van het binnenkomende tokenuitwisselingsverzoek waarborgt.

Behandel sign-in callback#

Laten we alles wat we hebben samengebracht afronden. Laten we de signInCallback afhandelingsmethode bouwen:

Als resultaat zal het tokenuitwisselingsverzoek de volgende tokens teruggeven:

• id_token: OIDC idToken, een JSON Web Token (JWT) dat identiteitsinformatie bevat over de geauthenticeerde gebruiker. id_token kan ook worden gebruikt als de Single Source of Truth (SSOT) van de authenticatiestatus van een gebruiker.
• access_token: De standaard autorisatiecode die wordt geretourneerd door de autorisatieserver. Kan worden gebruikt om het gebruikersinformatie-eindpunt aan te roepen en geauthenticeerde gebruikersinformatie op te halen.
• refresh_token: (indien offline_access scope aanwezig in het autorisatieverzoek): Dit vernieuwtoken stelt de client-applicatie in staat om een nieuw toegangstoken te verkrijgen zonder dat de gebruiker opnieuw hoeft te authentiseren, waardoor langduriger toegang tot de bronnen wordt verleend.
• expires_in: De duur van de tijd, in seconden, waarvoor het toegangstoken geldig is voordat het verloopt.

Verificatie van id_token#

Het verifiëren en extraheren van claims uit de id_token is een cruciale stap in het authenticatieproces om de authenticiteit en integriteit van het token te waarborgen. Hier zijn de belangrijkste stappen die betrokken zijn bij het verifiëren van een idToken.

• Handtekeningverificatie: De id_token is digitaal ondertekend door de autorisatieserver met behulp van zijn privésleutel. De clientapplicatie moet de handtekening verifiëren met de openbare sleutel van de autorisatieserver. Dit verzekert dat het token niet is geknoeid en daadwerkelijk is uitgegeven door de legitieme autorisatieserver.
• Uitgever verificatie**:** Controleer of de "iss" (uitgever) claim in de id_token overeenkomt met de verwachte waarde, ter bevestiging dat het token is uitgegeven door de juiste autorisatieserver.
• Publiek verificatie: Zorg ervoor dat de "aud" (publiek) claim in de id_token overeenkomt met de client ID van de clientapplicatie, om ervoor te zorgen dat het token bedoeld is voor de client.
• Vervaldatum controle: Controleer of de "iat" (uitgegeven op) claim in de id_token niet is verstreken, ter bevestiging dat het token nog steeds geldig is. Aangezien er sprake is van netwerktransactiekosten, moeten we een uitzonderingstijd instellen wanneer we de ontvangen iat-claim valideren.

Het geretourneerde id_token is een standaard JSON Web Token (JWT). Afhankelijk van het framework dat je gebruikt, kun je verschillende handige JWT-token validatie plugins vinden om te helpen bij het decoderen en valideren van het token. Voor dit voorbeeld zullen we jose in onze JavaScript SDK gebruiken om token validatie en decodering te vergemakkelijken.

Verkrijg gebruikersinformatie#

Na succesvolle gebruikersauthenticatie kan basisgebruikersinformatie worden opgehaald uit de OIDC id_token die wordt uitgegeven door de autorisatieserver. Echter, vanwege prestatieoverwegingen is de inhoud van het JWT-token beperkt. Om meer gedetailleerde gebruikersprofielinformatie te verkrijgen, bieden OIDC-conforme autorisatieservers een kant-en-klare gebruikersinfo-eindpunt. Dit eindpunt stelt je in staat om aanvullende gebruikersprofielgegevens op te halen door specifieke gebruikersprofielscopes aan te vragen.

Bij het oproepen van een tokenuitwisselingseindpunt zonder een specifiek API-bron aan te geven, zal de autorisatieserver standaard een ondoorzichtig type access_token afgeven. Dit access_token kan alleen worden gebruikt om toegang te krijgen tot het gebruikersinfo-eindpunt, waardoor retrieval van basisgebruikersprofielgegevens mogelijk is.

Verkrijg toegangstoken voor beschermde bron autorisatie#

In de meeste gevallen heeft een clientapplicatie niet alleen gebruikersauthenticatie nodig, maar ook gebruikersautorisatie om toegang te krijgen tot bepaalde beschermde middelen of API-eindpunten. Hier zullen we het refresh_token gebruiken dat tijdens het inloggen is verkregen om access_token(s) te verkrijgen die specifiek zijn verleend om bepaalde middelen te beheren. Hiermee kunnen we toegang krijgen tot die beschermde API's.

Samenvatting#

We hebben essentiële methode implementaties verstrekt voor het gebruikersauthenticatie- en autorisatieproces van de client-side app. Afhankelijk van je specifieke scenario kun je de SDK-logica naar wens organiseren en optimaliseren. Houd er rekening mee dat er variaties kunnen bestaan vanwege verschillende platforms en kaders.

Voor aanvullende details, verken de SDK-pakketten die Logto aanbiedt. We moedigen meer gebruikers aan om deel te nemen aan de ontwikkeling en om met ons in discussie te gaan. Je feedback en bijdragen worden zeer gewaardeerd terwijl we de capaciteiten van de SDK blijven verbeteren en uitbreiden.

Bijlage#

Gereserveerde scopes#

Door Logto gereserveerde scopes die je moet doorgeven tijdens het initiële authenticatieverzoek. Deze scopes zijn óf OIDC-gereserveerde óf Logto-gereserveerde fundamentele scopes om een succesvolle autorisatiestroom te volbrengen.

Schaalnaam	Beschrijving
openid	Vereist voor de toekenning van id_token na een succesvolle authenticatie.
offline-access	Vereist voor de toekenning van een refresh_token waarmee je clientapplicatie een exchange en een access_token off the screen kan vernieuwen.
profile	Vereist voor het verkrijgen van toegang tot de basisgebruikersinfo

Logto Config#

Eigenschapsnaam	Type	Vereist	Beschrijving	Standaardwaarde
appId	string	true	De unieke applicatie-identificator. gegenereerd door de autorisatieserver om de client applicatie te identificeren.
appSecret	string		Het applicatiegeheim wordt gebruikt, samen met het applicatie ID, om de identiteit van de aanvrager te verifiëren. Het is vereist voor vertrouwelijke clients zoals Go web of Next.js webapps, en optioneel voor openbare clients zoals native of single-page applicaties (SPA's)
endpoint	string	true	Je autorisatieserver basiseindpunt. Deze eigenschap zal op grote schaal worden gebruikt om autorisatieverzoeken te generen.
scopes	string list		Benadrukt alle nodige ressourcetrucs die de gebruiker moet krijgen om toegang te krijgen tot alle gegeven beschermde sources.	[reservedScopes]
resources	string list		Alle beschermde bronindicatoren waarvoor de gebruiker toegang kan aanvragen.

Hulpmethoden#

generateRandomString#