Implementa un semplice SDK OIDC lato client
Logto offre una varietà di SDK per diverse piattaforme. Oltre ai nostri SDK ufficiali, incoraggiamo gli sviluppatori della comunità a creare i propri SDK user-friendly. Questo articolo ti guiderà nella costruzione di un SDK base lato client per OIDC.
Giriş
Logto geliştiricilerimize ve iş gruplarımıza kapsamlı bir Müşteri Kimlik ve Erişim Yönetimi (CIAM) çözümü sağlar. Farklı platformlar ve uygulama çerçeveleri için çok sayıda kullanıma hazır SDK'lar sunuyoruz. Logto bulut hizmetimizle birleştiğinde, uygulamanız için çok yüksek güvenlikli bir kullanıcı yetkilendirme akışını birkaç dakikada kolayca oluşturabilirsiniz. Bir geliştirici topluluğundan doğan bir şirket olan Logto, topluluk katılımını benimser ve değer verir. Resmi olarak geliştirilen Logto SDK'larına ek olarak, topluluktan geliştiricilerin, çeşitli platformlar ve çerçeveler için eşsiz ihtiyaçları karşılayacak daha çeşitli ve kullanıcı dostu SDK'lar oluşturarak uzmanlıklarını katkıda bulunmalarını sürekli olarak teşvik eder ve sıcak bir şekilde karşılar. Bu makalede, bir OIDC standart auth SDK'sını adım adım nasıl uygulayacağımızı kısaca göstereceğiz.
Bağlam
OpenID Connect (OIDC) akışı, OAuth 2.0 çerçevesi üzerine inşa edilen bir kimlik doğrulama protokolüdür ve kimlik doğrulama ve tek oturum açma yetenekleri sağlar. Kullanıcıların bir uygulamayla kimliklerini doğrulamalarını ve herhangi bir özel kaynağa güvenli bir şekilde daha fazla erişim için yetkili olmalarını sağlar. Daha fazla detay için lütfen OIDC özelliklerine başvurun.
İş Akışı
Standart bir yetkilendirme-kodu akışı, aşağıdaki adımları içerir:
Kimlik Doğrulama Akışı
- Kullanıcı oturum açma isteğini başlatır: Anonim bir kullanıcı, kamuya açık bir girişten uygulamanıza gelir. Kimlik doğrulaması için girişimde bulunur ve belki de üçüncü taraf bir uygulama veya hizmette korunan bir kaynağa daha fazla istek yapar.
- Kullanıcı kimlik doğrulaması: İstemci uygulaması bir kimlik doğrulama URI'si oluşturur ve kullanıcısını giriş sayfasına yönlendiren yetkilendirme sunucusuna bir istek gönderir. Kullanıcı, geniş bir giriş yöntemleri yelpazesini kullanarak giriş sayfasıyla et interacted girer ve yetkilendirme sunucusu tarafından kimlik doğrulamalarını alır.
- Giriş geri çağrısını işleme: Başarılı bir kimlik doğrulamasının ardından, kullanıcı bir yetkili
authorization_code
ile uygulamanıza geri yönlendirilecektir . Buauthorization_code
, authentication durumu ve istenen yetkilendirme verisi ile ilişkilendirilen tüm ilgili izinleri içerir. - Token değişimi: Yukarıdaki redirect adresinden elde edilen
authorization_code
kullanılarak token değişimi talep ediliyor. Buna karşılık olarak grilenler:id_token
: Doğrulanmış kullanıcı hakkında kimlik bilgilerini içeren dijital olarak imzalanmış bir JWT.access_token
: Kullanıcının temel bilgilerine erişim sağlamak için kullanılabilen saydam biraccess_token
.refresh_token
: Biraccess_token
alışverişi için kullanıcının sürekli değişim için izin veren kimlik bilgileri token.
Yetkilendirme Akışı
- Kullanıcı bilgilerine erişim: Daha fazla kullanıcı bilgisi elde etmek için, uygulama ilk token takas akışından elde edilen saydam
access_token
kullanarak UserInfo uç noktasına ek istekler yapabilir. Bu, kullanıcının e-posta adresi veya profil resmi gibi kullanıcı hakkında daha fazla ayrıntıyı almayı sağlar. - Korumalı kaynağa erişim yetkisi: Gerekirse, uygulama,
refresh_token
ile birlikteresource
vescope
parametrelerini kullanarak token değişim uç noktasına ek istekler yapabilir, buradan kullanıcıya hedef kaynağa erişim için özel biraccess_token
alabilir. Bu işlem, korumalı kaynağa erişim için gerekli yetkilendirme bilgilerini içeren bir JWT formatlanmışaccess_token
ın verilmesi şeklinde sonuçlanır.
Uygulama
Kendi istemci uygulamanız için basit bir SDK oluşturma sürecini göstermek için @logto/client JavaScript SDK'mızdaki bazı tasarım stratejilerini izleyeceğiz. Lütfen detaylı kod yapısının, üzerinde çalıştığınız istemci çerçevesine bağlı olarak farklı olabileceğini aklınızda bulundurun. Kendi SDK projeniz için örnek olarak herhangi bir Logto resmi SDK'yı seçmekten çekinmeyin.
Önizleme
Constructor
Constructor, giriş olarak logtoConfig'u almalıdır. Bu, bu SDK aracılığıyla auth bağlantısını kurmak için ihtiyaç duyacağınız tüm gerekli yapılandırmaları sağlar.
SDK için kullandığınız platform veya çerçeveye bağlı olarak, bir persistent yerel depolama örneğini constructor'a geçirebilirsiniz. Bu depolama örneği, tüm yetkilendirme ile ilgili token'lar ve sırları depolamak için kullanılacaktır.
Kullanıcı kimlik doğrulamasını başlat
Bir kimlik doğrulama istek URL'si oluşturmadan önce, güvenli bir süreci garanti etmek için birkaç hazırlık adımını tamamlamak gereklidir.
Yetkilendirme sunucusundan OIDC yapılandırmalarını alın
Yetkilendirme sunucusunun keşif uç noktasından OIDC yapılandırmalarını almak için bir private yöntem getOidcConfigs
tanımlayın. OIDC yapılandırmaları yanıtı, istemci'nin yetkilendirme sunucusuyla et interacted girerek sunucu'nun uç nokta konumlarını ve sunucu'nun yeteneklerini içeren tüm metadataya sahip olur. (Daha fazla detay için, lütfen OAuth OAuth Yetkilendirme Sunucusu Metadata Özelliklerine bakın.)
PKCE Generator
Bir PKCE(Proof Key for Code Exchange) doğrulama akışı, tüm kamu istemci yetkilendirme kodu değişim akışları için esastır. Yetkilendirme_kodunun interception saldırısının riskini azaltır. Böylece tüm kamu istemci uygulamaları (ör. yerli uygulama ve SPA) yetkilendirme isteklerinde bir code_challenge
ve code_verifier
gereklidir.
Uygulama yöntemleri dillerinize ve kullandığınız çerçevelere bağlı olarak değişebilir. Lütfen daha detaylı tanımlar için code_challenge ve code_verifier özelliklerine başvurun.
State parametresi oluştur
Yetkilendirme akışında, state parametresi istemci tarafından gönderilen yetkilendirme isteğine dahil edilen rastgele oluşturulmuş bir değerdir. Bu, cross-site request forgery (CSRF) saldırılarını önlemek amacıyla bir güvenlik önlemi olarak hareket eder.
Ara session bilgisini sakla
Kullanıcının kimlik doğrulandıktan ve client tarafına geri yönlendirildikten sonraki doğrulama amacıyla depolanması gereken birkaç parametre vardır. Bu ara parametreleri depolamak için bir yöntem uygulayacağız.
Sign-in
Yukarıda uygulanan her şeyi paketleyelim, bir kullanıcı oturum açma URL'si oluşturan ve kullanıcıyı kimlik doğrulamak için yetkilendirme sunucusuna yönlendiren bir yöntem tanımlayalım.
Kullanıcı oturum açma geri çağrısını işleme
Önceki bölümde, kullanıcı kimlik doğrulaması için bir URL içeren bir sign-in yöntemi oluşturduk. Bu URL, bir client uygulamasından kimlik doğrulama akışını başlatmak için gereken tüm gerekli parametreleri içerir. Kullanıcıyı autenticasyon için yetkilendirme sunucusunun giriş sayfasına yönlendirir. Başarılı bir sign-in'in ardından, kullanıcı üstte sağlanan redirect_uri konumuna yeniden yönlendirilir. Gerekli tüm parametreler, aşağıdaki token değişim akışlarını tamamlamak için redirect_uri'de taşınır.
Geri çağrı URL'sini çıkar ve doğrula
Bu doğrulama adımı, her tür sahte yetkilendirme callback saldırısını önlemek için son derece önemlidir. Callback URL MUTLAKA dikkatlice doğrulanmalıdır ve ardından yetkilendirme sunucusuna daha fazla kod değişim talebi gönderilmelidir. Öncelikle, uygulama depolamasından sakladığımız signInSession verilerini almamız gerekiyor.
Daha sonra token değişim isteği göndermeden önce callback URL’nin parametrelerinin doğrulanmasını yapın.
- Daha önce sakladığımız
redirectUri
'yi kullanarakcallbackUri
'nin yetkilendirme sunucusuna gönderdiğimizle aynı olup olmadığını doğrulayın. - Daha önce sakladığımız
state
'i kullanarak geri dönenstate
'in yetkilendirme sunucusuna gönderdiğimizle aynı olup olmadığını doğrulayın. - Yetkilendirme sunucusu tarafından herhangi bir hatanın dönüp dönmediğini kontrol edin
- Geri dönen
authorization_code
'un varlığını kontrol edin
Kod değişim talebini gönder
Kullanıcı kimlik doğrulama akışının son adımı olarak, döndürülen authorization_code
'u kullanarak bir token değişim talebi gönderip gerekli yetkilendirme token'larını elde edeceğiz. İstek parametrelerinin tanımlamaları hakkında daha fazla detay için, lütfen token değişim özelliklerine başvurun.
- code: callback URI'den aldığımız
authorization_code
- clientId: uygulama ID
- redirectUri: Kullanıcı için oturum açma URL'si oluştururken kullanılan aynı değer.
- codeVerifier: PKCE kod doğrulayıcı. redirectUri'ye benzer bir şekilde, yetkilendirme sunucusu bu değeri, gelen token değişim isteğinin doğrulanmasını sağlamak için daha önce gönderdiğimiz değerle karşılaştırır.
Kullanıcı oturum açma geri çağrısını işleme
Elimizde olduğu her şeyi toplayalım. signInCallback işleme yöntemini oluşturalım:
Sonuç olarak, token değişim talebi aşağıdaki token'ları dönecektir:
id_token
: OIDC idToken, doğrulanmış kullanıcı hakkında kimlik bilgilerini içeren bir JSON Web Token (JWT). id_token aynı zamanda kullanıcıların kimlik doğrulama durumunun Tek Gerçek Kaynağı (SSOT) olarak kullanılabilir.access_token
: Yetkilendirme sunucusu tarafından döndürülen varsayılan yetkilendirme kodu. kullanıcı bilgi uç noktasını çağırmak ve kimlik doğrulanmış kullanıcı bilgilerini almak için kullanılabilir.refresh_token
: (offline_access scope yetkilendirme isteğinde mevcutsa): Bu refresh token, kullanıcının yeniden kimlik doğrulaması yapmasını gerektirmeksizin kullanıcı kimlik doğrulama sürecinden daha uzun süre erişebilmek için yeni bir access token elde etmesine izin verir.expires_in
: Access token'ın süresi dolmadan önce geçerli olan saniye cinsi zaman süreci.
ID token doğrulaması
id_token
'ı doğrulamak ve claims'i çıkarmak, kimlik doğrulama sürecindeki token'ın otantisite ve bütünlüğünü sağlamak için önemli bir adımdır. İşte idToken
'ı doğrulamak için yer alan ana adımlar:
- İmza Doğrulama:
id_token
, yetkilendirme sunucusu tarafından özel anahtarıyla dijital olarak imzalandı. İstemci uygulaması, yetkilendirme sunucusunun genel anahtarı ile imzayı doğrulamalıdır. Bu, token'ın değiştirilmediğini ve gerçek yetkilendirme sunucusu tarafından düzenlendiğini garanti eder. - Issuer Doğrulaması**: **
id_token
'daki "iss" (publisher) claim'i beklenen değer ile eşleşiyor, bu da token'ın doğru yetkilendirme sunucusu tarafından düzenlendiğini gösterir. - Audience Doğrulaması:
id_token
'daki "aud" (audience) claim'in istemci uygulamasının client ID'si ile eşleştiğini kontrol edin, bu token'ın istemci için niyetlenildiğini garanti eder. - Süre Kontrolü:
id_token
'da bulunan"iat" (issued at) claim’in geçerli zamanın üzerinden geçip geçmediğini kontrol edin ki bu token'ın hala geçerli olduğunu garanti eder. Ağ işlem maliyetlerine sahip olunduğundan iat claim'i doğrularken bir çıktı süresi toleransı belirlememiz gerekiyor.
Dönen id_token, standart bir JavaScript Web Token (JWT)'dir. Kullandığınız çerçeveye bağlı olarak, token'i çözme ve doğrulamada yardımcı olacak bir dizi uygun JWT token doğrulama eklentisi bulabilirsiniz. Bu örnekte, token doğrulama ve çözme işlemini kolaylaştırmak için JavaScript SDK'mızda jose kullanacağız.
Kullanıcı bilgilerini al
Başarılı bir kullanıcı kimlik doğrulamasının ardından, yetkilendirme sunucusu tarafından düzenlenen OIDC id_token
'dan temel kullanıcı bilgileri alınabilir. Ancak, performans kaygıları nedeniyle, JWT token'ın içeriği sınırlıdır. Daha ayrıntılı kullanıcı profili bilgilerini elde etmek için, OIDC uyumlu yetkilendirme sunucuları, belirli kullanıcı profili kapsamlarını talep ederek ek kullanıcı profili verilerini almanızı sağlayan bir user info uç noktası sunar.
Bir token değişim uç noktasını belirli bir API kaynağını belirtmeden çağırırken, yetkilendirme sunucusu varsayılan olarak şeffaf bir tür access_token
çıkarır. Bu access_token
, temel kullanıcı profil bilgilerini almayı sağlayan user info uç noktasına erişmek için kullanılabilir.
Korumalı kaynak yetkilendirmesi için erişim tokenı al
Çoğu durumda, bir istemci uygulaması sadece kullanıcı kimlik doğrulamasına ihtiyaç duymaz, aynı zamanda belirli korunan kaynaklara veya API uç noktalarına erişim almak için kullanıcı yetkilendirmesine de ihtiyaç duyar. Burada, oturum açma sırasında elde edilen refresh_token
'ı kullanarak belirli kaynakları yönetmek için özellikle yetkilendirilmiş access_token(s)
elde edeceğiz. Bu, korunan API'lerin kullanılabilir hale gelmesini sağlar.
Özet
Müşteri tarafı uygulamanın kullanıcı kimlik doğrulaması ve yetkilendirme süreci için temel yöntem uygulamalarını sunduk. Özel senaryonuza bağlı olarak, SDK mantığını düzenleyip optimize edebilirsiniz. Lütfen farklı platformlar ve çerçeveler nedeniyle farklılıkların olabileceğini unutmayın.
Daha fazla detay için, Logto tarafından sunulan SDK paketlerini keşfedin. Daha fazla kullanıcının geliştirmeye katılmasını ve bizimle tartışmalara girmesini teşvik ediyoruz. SDK'nın yeteneklerini genişletme ve geliştirme sürecimiz boyunca geri bildirimleriniz ve katkılarınız çok değerlidir.
Ek
Ayrılmış kapsamlar
Başlangıç auth talebi sırasında geçirmeniz gereken Logto ayrılmış kapsamlar. Bu kapsamlar ya OIDC ayrılmış ya da başarılı bir yetkilendirme akışını tamamlamak için Logto'da ayrılmış temel kapsamlardır.
Scope adı | Açıklama |
---|---|
openid | Başarılı bir kimlik doğrulamadan sonra id_token 'u yetkili bir şekilde sağlama gereklidir. |
offline-access | Ekran dışında bir access_token yenilemek ve takas etmek için kullanıcınızın uzatılabilir erişim sağlama konusunda yetkili olması gerekir. |
profile | Temel kullanıcı bilgilerine erişim yetkisi sağlama gerekir. |
Logto Config
Özellik adı | Tip | Gerekli | Açıklama | Varsayılan Değer |
---|---|---|---|---|
appId | string | true | Eşsiz uygulama belirleyicisi. İstemci uygulamayı tanımlamak için yetkilendirme sunucusu tarafından oluşturulur. | |
appSecret | string | Uygulama sırrı, uygulama ID ile birlikte, isteğin kimliğini doğrulamak için kullanılır. Go web veya Next.js web uygulamaları gibi gizli clientlar için gereklidir ve native veya tek sayfalı uygulamalar (SPA'lar) gibi kamu clientları için opsiyoneldir | ||
endpoint | string | true | Yetkilendirme sunucusu kök uç noktası. Yetkilendirme isteklerini oluşturmak için genellikle kullanılır. | |
scopes | string list | Kullanıcının belirli bir korumanın altındaki herhangi bir kaynağa erişmek için yetkili olması gereken tüm gerekli kaynak kapsamlarını gösterir. | [reservedScopes] | |
resources | string list | Kullanıcının erişim talep edebileceği tüm korunan kaynak belirticileri |