Basit bir istemci-tarafı OIDC SDK'sı oluşturun

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ışı#

1. 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.
2. 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.
3. 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 . Bu authorization_code, authentication durumu ve istenen yetkilendirme verisi ile ilişkilendirilen tüm ilgili izinleri içerir.
4. 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 bir access_token.
   • refresh_token: Bir access_token alışverişi için kullanıcının sürekli değişim için izin veren kimlik bilgileri token.

Yetkilendirme Akışı#

1. 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.
2. Korumalı kaynağa erişim yetkisi: Gerekirse, uygulama, refresh_token ile birlikte resource ve scope parametrelerini kullanarak token değişim uç noktasına ek istekler yapabilir, buradan kullanıcıya hedef kaynağa erişim için özel bir access_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 kullanarak callbackUri'nin yetkilendirme sunucusuna gönderdiğimizle aynı olup olmadığını doğrulayın.
• Daha önce sakladığımız state'i kullanarak geri dönen state'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

Util metotları#

generateRandomString#