Toteuta yksinkertainen asiakaspään OIDC SDK

Johdanto#

Logto tarjoaa kehittäjillemme ja liikeryhmillemme kattavan asiakasidentiteetin ja pääsynhallintaratkaisun (CIAM). Tarjoamme laajan valikoiman käyttövalmiita SDK:ita eri alustoille ja sovelluskehyksille. Yhdistämällä Logto-pilvipalvelumme voit vaivattomasti luoda erittäin turvallisen käyttäjän valtuutusprosessin sovellukseesi muutamassa minuutissa. Logto on kehittäjäyhteisöstä lähtöisin oleva yritys, joka arvostaa yhteisömme osallistumista ja panosta. Lisäksi virallisesti kehitettyihin Logto SDK:ihin kannustamme ja toivotamme lämpimästi tervetulleiksi yhteisön kehittäjät jakamaan asiantuntemustaan ja tuomaan monipuolisempia ja käyttäjäystävällisempiä SDK:ita, jotka vastaavat erityyppisten alustojen ja kehysten tarpeita. Tässä artikkelissa näytämme lyhyesti, kuinka OIDC-standardiin perustuva valtuutus-SDK toteutetaan vaihe vaiheelta.

Yhteys#

OpenID Connect (OIDC) -virtaus on autentikointiprotokolla, joka perustuu OAuth 2.0 -kehykseen tarjotakseen identiteetin todentamisen ja kertakirjautumisen ominaisuuksia. Sen avulla käyttäjät voivat todennella itsensä sovelluksessa ja saada valtuutuksen pääsyyn yksityisiin resursseihin turvallisesti. Katso lisätietoja OIDC-määrityksistä.

Työnkulku#

Vakiomuotoinen valtuutuskoodin virtaus sisältää seuraavat vaiheet:

Todennusvirtaus#

1. Käyttäjä aloittaa kirjautumispyynnön: Anonyymi käyttäjä tulee sovellukseesi julkisesta sisäänkäynnistä. Hän yrittää saada todentamista ja mahdollisesti pyytää pääsyä suojattuun resurssiin kolmannen osapuolen sovelluksessa tai palvelussa.
2. Käyttäjän todennus: Asiakassovellus luo todennus-URI:n ja lähettää pyynnön valvontapalvelimelle, joka ohjaa käyttäjän sen kirjautumissivulle. Käyttäjä toimii kirjautumissivun kautta useilla eri kirjautumistavoilla ja valtuutuspalvelin valtuuttaa hänet.
3. Käsittele kirjautumispalautus: Onnistuneen todennuksen jälkeen käyttäjä ohjataan takaisin sovellukseesi myönnetyn authorization_code -koodin kanssa. Tämä authorization_code sisältää kaikki relevantit todennustilaan ja pyydettyyn valtuutukseen liittyvät oikeudet.
4. Tokenin vaihto: Pyydä tokenin vaihtoa käyttämällä yllä olevasta palautusosoitteesta poimitun authorization_code:n avulla. Vastauksena:
   • id_token: Digitaalisesti allekirjoitettu JWT, joka sisältää identiteettitietoja todennetusta käyttäjästä.
   • access_token: Opaque access_token, jota voidaan käyttää käyttäjän perusinfon päätepisteen saavuttamiseksi.
   • refresh_token: Tunnistetoken, joka antaa käyttäjälle mahdollisuuden ylläpitää jatkuvan vaihdon access_token:iin.

Valtuutusvirtaus#

1. Käyttäjätietojen käyttö: Lisäkäyttäjätietojen saamiseksi sovellus voi tehdä lisäpyyntöjä UserInfo-päätepisteeseen käyttäen opakista access_token-tokenia, joka on saatu alun perin tokeninvaihtovirrassa. Näin voidaan saada lisätietoja käyttäjästä, kuten hänen sähköpostiosoitteensa tai profiilikuvansa.
2. Pääsy suojattuun resurssiin: Tarvittaessa sovellus voi tehdä lisäpyyntöjä tokeninvaihtopäätepisteelle käyttäen refresh_token:ia yhdistettynä resource- ja scope-parametreihin saadakseen erityisen access_token:in, jotta käyttäjä pääsee kohderesurssiin. Tämä prosessi johtaa JWT-muodostetun access_token:in myöntämiseen, joka sisältää kaikki tarvittavat valtuutustiedot suojatun resurssin saavuttamiseksi.

Toteutus#

Seuraamme joitakin suunnittelustrategioita @logto/client JavaScript SDK:ssa osoittaaksemme prosessin yksinkertaisen SDK:n toteuttamiseen omalle asiakassovelluksellesi. Huomioithan, että yksityiskohtainen koodirakenne saattaa erota käyttämäsi asiakassovelluskehyksen mukaan. Voit vapaasti valita minkä tahansa virallisista Logto SDK:ista esimerkkinä omaan SDK-projektiisi.

Esikatselu#

Konstruktori#

Konstruktorin tulisi ottaa logtoConfig syötönään. Tämä tarjoaa kaikki tarvittavat määritykset, joita tarvitset auth-yhteyden luomiseen tämän SDK:n kautta.

Riippuen käyttämäsi SDK:n alustasta tai kehyksestä, voit antaa konstruktorille pysyvän paikallisen säilytysinstanssin. Tätä säilytysinstanssia käytetään kaikkien valtuutukseen liittyvien tokenien ja salaisuuksien tallentamiseen.

Käyttäjäautentikoinnin alustus#

Ennen kuin luodaan todennuspyyntö-URL, on välttämätöntä suorittaa useita valmisteluvaiheita turvallisen prosessin varmistamiseksi.

Saavuta OIDC-määritykset valvontapalvelimelta#

Määrittele yksityinen metodi getOidcConfigs, joka hakee OIDC-määrityksiä valvontapalvelimen hakuosoitteesta. OIDC-määritysten vastaus sisältää kaiken metadatainformaation, jota asiakas voi käyttää kommunikoidessaan valvontapalvelimen kanssa, mukaan lukien sen päätepisteiden sijainnit ja palvelimen ominaisuudet. (Katso OAuth Valtuutuspalvelimen Metadata Specs saadaksesi lisää tietoja.)

PKCE Generaattori#

PKCE:n (Proof Key for Code Exchange) PKCE validointivirtaus on välttämätöntä kaikille yleisten asiakassovellusten valtuutuskoodinvaihtovirroille. Se vähentää valtuustus-koodin sieppausriskin. Näin ollen "code_challenge" ja "code_verifier" tarvitaan kaikissa julkisten asiakassovellusten (esim. natiivi sovellus ja SPA) valtuutuspyynnöissä.

Toteutusmenetelmät vaihtelevat käyttämiesi kielten ja kehysten mukaan. Katso lisätiedot code_challenge ja code_verifier määräyksistä.

Generoi tilaparametri#

Valtuutusprosessissa tilaparametri on satunnaisesti tuotettu arvo, joka sisällytetään todennuspyyntöön, jonka asiakas lähettää. Se toimii turvatoimenpiteenä estämään CSRF-hyökkäykset (ristiinsivustojen pyyntöväärentäminen).

Väliprosessitietojen tallentaminen#

On olemassa useita parametreja, jotka on säilytettävä tallennuksessa todentamis- ja palautusprosessin jälkeen. Aiomme toteuttaa menetelmän, jolla asetamme nämä väliprosessiparametrit tallennukseen.

Kirjautuminen#

Yhteenvetona kaikesta edellä, määrittele menetelmä, joka luo käyttäjän kirjautumis-URL:n ja ohjaa käyttäjän valvontapalvelimelle todennusta varten.

Käsittele käyttäjän kirjautumispalautus#

Edellisessä osiossa loimme kirjautumismenetelmän, joka luo URL:n käyttäjätodennusta varten. Tämä URL sisältää kaikki tarvittavat parametrit, jotka ovat tarpeen todennusprosessin aloittamiseksi asiakassovelluksesta. Menetelmä ohjaa käyttäjän valvontapalvelimen kirjautumissivulle todennusta varten. Onnistuneen kirjautumisen jälkeen loppukäyttäjä ohjataan takaisin yllä ilmoitettuun redirect_uri-sijaintiin. Kaikki tarvittavat parametrit kulkevat redirect_uri:ssa seuraavan tokeninvaihtovirran suorittamiseksi.

Palautus-URL:n poimiminen ja tarkistaminen#

Tämä validointivaihe on erittäin tärkeä estääkseen minkäänlaisia väärennettyjä valtuutuspaluuhyökkäyksiä. Palautus-URL TÄYTYY tarkistaa huolellisesti ennen valtuutuspaluunpyynnön lähettämistä valvontapalvelimelle. Ensinnäkin meidän on haettava sovellustallennukseen tallennetut signInSession-tiedot.

Tarkista sitten palautus-URL:n parametrit ennen tokeninvaihtopyynnön lähettämistä.

• Käytä aiemmin tallennettua redirectUri:ta selvittääksesi, onko callbackUri sama kuin se, jonka lähetimme valvontapalvelimelle.
• Käytä aiemmin tallennettua state:a selvittääksesi, onko palautettu tila sama kuin se, jonka lähetimme valvontapalvelimelle.
• Tarkista, onko valvontapalvelin palauttanut virheen
• Tarkista palautetun authorization_code:n olemassaolo

Lähetä koodinvaihtopyyntö#

Käyttäjän todennusprosessin viimeisessä vaiheessa käytämme palautettua authorization_code:a lähettääksemme tokeninvaihtopyynnön ja saadaksemme tarvittavat valtuutustokenit. Katso tarkemmat määritykset pyyntöhallinta-arvoihin tokeninvaihtomäärityksistä.

• code: saatu authorization_code palautus-URI:sta
• clientId: sovelluksen ID
• redirectUri: sama arvo käytetään, kun generoidaan kirjautumis-URL käyttäjälle.
• codeVerifier: PKCE-koodivarmistaja. Vastaavasti redirectUri:n, valvontapalvelin vertaa tätä arvoa aiemmin lähettämäämme arvoon varmistaakseen saapuvan tokeninvaihtopyynnön validoinnin.

Käsittele kirjautumispalautus#

Kootaan kaikki edellä oleva. Rakennetaan signInCallback-käsittelymetodi:

Seurauksena on, että tokeninvaihtopyyntö palauttaa seuraavat tokenit:

• id_token: OIDC idToken, JSON Web Token (JWT), joka sisältää todennetun käyttäjän identiteettitietoja. id_token voidaan myös käyttää käyttäjän todennustilan todistuslähteenä (SSOT).
• access_token: Oletusaika, jonka valvontapalvelin palauttaa. Sitä voidaan käyttää käyttäjäinfon päätepisteen pyynnön tekemiseen ja todennettujen käyttäjätietojen hakemiseen.
• refresh_token: (jos offline_access-tila on läsnä valtuutuspyynnössä): tämä refresh-token mahdollistaa asiakassovellukselle uuden access tokenin hankkimisen ilman, että käyttäjän tarvitsee uudelleen kirjautua sisään, mikä antaa pidemmän aikavälin pääsyn resursseihin.
• expires_in: Keston, sekunteina, jonka ajan access token on voimassa ennen kuin se vanhenee.

ID-tokenin tarkistus#

id_token-tokenin tarkistaminen ja vaatimusten poimiminen on ratkaiseva vaihe todennusprosessissa tokenin aitouden ja eheyden varmistamiseksi. Tässä ovat tärkeimmät vaiheet idToken:in tarkistamisessa.

• Allekirjoituksen tarkistus: id_token on valvontapalvelimen yksityisellä avaimella digitaalisesti allekirjoitettu. Asiakassovelluksen täytyy tarkistaa allekirjoitus valvontapalvelimen julkisella avaimella. Tämä varmistaa, ettei tokenia ole muokattu ja että se on todellakin laillisen valvontapalvelimen antama.
• Liikkeellelaskijan tarkastus**:** Tarkista, että "iss" (liikkeellelaskija) vaade id_token:issa vastaa odotettavissa olemaa arvoa, joka ilmaisee, että token on valvontapalvelimen myöntämä.
• Yleisön tarkastus: Varmista, että "aud" (yleisö) vaade id_token:issa vastaa asiakasohjelman asiakas ID:tä, jolloin varmistetaan, että token on tarkoitettu asiakkaalle
• Vanhenemisen tarkastus: Tarkista, ettei "iat" (annettu) vaade id_token:issa ole kulunut ohi nykyisen ajan, varmistaen, että token on yhä voimassa. Koska on olemassa verkon siirtokustannuksia, meidän täytyy asettaa "issued"-ajan toleranssi, kun validoimme vastaanotetun tokenin "iat"-vaatetta.

Palautettava id_token on vakiomuotoinen JSON Web Token (JWT). Riippuen käyttämästäsi kehyksestä voit löytää valikoiman käteviä JWT-token-validointilaajennoksia, jotka voivat auttaa koodin dekoodaamisessa ja validoinnissa. Tässä esimerkissä käytämme JavaScript-SDK:ssamme jose helpottamaan tokenin validointia ja dekoodausta.

Hae käyttäjätiedot#

Onnistuneen käyttäjän todennuksen jälkeen peruskäyttäjätietoja voidaan saada OIDC id_token:sta, joka on annettu valvontapalvelimen toimesta. Suorituskykysyistä johtuen JWT-tokenin sisältö on kuitenkin rajallinen. Lisätietojen käyttäjäprofiilitietojen saamiseksi OIDC-yhteensopivat valvontapalvelimet tarjoavat valmiina käyttäjätieto-päätepisteen. Tämä päätepiste mahdollistaa lisäprofiilitietojen hakemisen pyytämällä erityisiä käyttäjäprofiileja koskevia tilavuusparametreja.

Kun kutsutaan tokeninvaihtopäätepistettä osoittamatta tiettyä resurssia, valvontapalvelin myöntää oletuksena opakityyppisen access_tokenin. Tätä access_tokenia voidaan käyttää vain käyttämään käyttäjäinfopäätepistettä, sallien pääsyn peruskäyttäjäprofiilitietoja.

Hanki pääsytoken suojatun resurssin valtuutusta varten#

Useimmissa tapauksissa asiakassovellus ei vain vaadi käyttäjän todennusta vaan tarvitsee myös käyttäjävaltuutusta päästäkseen tiettyihin suojattuihin resursseihin tai API-endpointteihin. Tässä käytämme kirjautumisen yhteydessä saatua refresh_token:ia saadaksemme access_token:ia, jotka on erityisesti myönnetty tiettyjen resurssien hallinnointiin. Tämä mahdollistaa pääsyn suojattuihin sovellusliittymiin.

Yhteenveto#

Olemme toimittaneet olennaisia menetelmätoteutuksia asiakassovelluksen käyttäjäntodennukselle ja -valtuutukselle. Riippuen skenaariostasi, voit järjestää ja optimoida SDK-logiikan vastaavasti. Huomaa, että eri alustoilla ja kehyksissä voi esiintyä variaatioita.

Tutustu lisätietoihin Logton tarjoamiin SDK-paketteihin. Kannustamme useampia käyttäjiä liittymään kehitykseen ja osallistumaan keskusteluihin kanssamme. Palautteesi ja panoksesi ovat erittäin arvokkaita, kun jatkamme SDK:n kykyjen parantamista ja laajentamista.

Liite#

Varatut tilat#

Logto-varatut tilat, jotka sinun on toimitettava ensimmäisen testipyynnön aikana. Nämä tilat ovat joko OIDC-varattuja tai Logto-varattuja perusomistuksia onnistuneeseen valtuutukseen.

Tilavan nimi	Kuvaus
openid	Vaaditaan id_token:n myöntämiseen onnistuneen todennuksen jälkeen.
offline-access	Vaaditaan refresh_token:n myöntämiseen, jolloin asiakassovelluksen avulla voidaan vaihtaa ja uusia access_token näyttöruudun ulkopuolella.
profile	Vaaditaan pään pääsyn saamiseksi perustietoihin käyttäjästä

Logto Konfigurointi#

Ominaisuuden nimi	Tyyppi	Vaadittu	Kuvaus	Oletusarvo
appId	string	true	Yksilöllinen sovellustunniste. Valvontapalvelimen tuottama, joka tunnistaa asiakassovelluksen.
appSecret	string		Sovelluksen salaisuus, jota käytetään yhdessä sovelluksen ID:n kanssa pyytäjän henkilöllisyyden varmistamiseksi. Se on tarpeen luottamuksellisille asiakkaille kuten Go-verkkosovellukset tai Next.js-verkkosovellukset, ja valinnainen julkisille asiakkaille kuten natiivi- tai yksisivun sovelluksille (SPA)
endpoint	string	true	Oma valvontapalvelimesi juuripäätepiste. Tämä ominaisuus käytetään laajalti valtuutuspyyntöjen tuottamiseksi.
scopes	string lista		Ilmaisee kaikki tarvittavat resurssitilat, jotka käyttäjän on annettava pääsyä tiettyihin suojattuihin resursseihin.	[reservedScopes]
resources	string lista		Kaikki suojatut resurssitunnisteet, joihin käyttäjä voi pyytää pääsyä.

Aputoiminnot#

generateRandomString#