Türkçe

SDK
OIDC

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

Logto, farklı platformlar için çeşitli SDK'lar sunar. Resmi SDK'larımızın dışında, topluluktan geliştiricilerin kendi kullanıcı dostu SDK'larını oluşturmalarını teşvik ediyoruz. Bu makale, bir OIDC için temel bir istemci-tarafı SDK oluşturma konusunda size rehberlik edecek.

Simeng

Developer

8/1/2023

Kullanıcı kimlik doğrulamasına haftalar harcamayı bırakın

Logto ile güvenli uygulamaları daha hızlı yayınlayın. Kullanıcı kimlik doğrulamasını dakikalar içinde entegre edin ve temel ürününüze odaklanın.

Başlayın

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.

Logto'da uygulamanızı oluşturun

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 . Bu authorization_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 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ışı

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 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.

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

Bugün Logto Cloud'u deneyin

Giriş#

Bağlam#

İş Akışı#

Kimlik Doğrulama Akışı#

Yetkilendirme Akışı#

Uygulama#

Önizleme#

Constructor#

Kullanıcı kimlik doğrulamasını başlat#

Yetkilendirme sunucusundan OIDC yapılandırmalarını alın#

PKCE Generator#

State parametresi oluştur#

Ara session bilgisini sakla#

Sign-in#

Kullanıcı oturum açma geri çağrısını işleme#

Geri çağrı URL'sini çıkar ve doğrula#

Kod değişim talebini gönder#

Kullanıcı oturum açma geri çağrısını işleme#

ID token doğrulaması#

Kullanıcı bilgilerini al#

Korumalı kaynak yetkilendirmesi için erişim tokenı al#

Özet#

Ek#

Ayrılmış kapsamlar#

Logto Config#

Util metotları#

generateRandomString#

Giriş#

Bağlam#

İş Akışı#

Kimlik Doğrulama Akışı#

Yetkilendirme Akışı#

Uygulama#

Önizleme#

Constructor#

Kullanıcı kimlik doğrulamasını başlat#

Yetkilendirme sunucusundan OIDC yapılandırmalarını alın#

PKCE Generator#

State parametresi oluştur#

Ara session bilgisini sakla#

Sign-in#

Kullanıcı oturum açma geri çağrısını işleme#

Geri çağrı URL'sini çıkar ve doğrula#

Kod değişim talebini gönder#

Kullanıcı oturum açma geri çağrısını işleme#

ID token doğrulaması#

Kullanıcı bilgilerini al#

Korumalı kaynak yetkilendirmesi için erişim tokenı al#

Özet#

Ek#

Ayrılmış kapsamlar#

Logto Config#

Util metotları#

generateRandomString#

Giriş

Bağlam

İş Akışı

Kimlik Doğrulama Akışı

Yetkilendirme Akışı

Uygulama

Önizleme

Constructor

Kullanıcı kimlik doğrulamasını başlat

Yetkilendirme sunucusundan OIDC yapılandırmalarını alın

PKCE Generator

State parametresi oluştur

Ara session bilgisini sakla

Sign-in

Kullanıcı oturum açma geri çağrısını işleme

Geri çağrı URL'sini çıkar ve doğrula

Kod değişim talebini gönder

Kullanıcı oturum açma geri çağrısını işleme

ID token doğrulaması

Kullanıcı bilgilerini al

Korumalı kaynak yetkilendirmesi için erişim tokenı al

Özet

Ek

Ayrılmış kapsamlar

Logto Config

Util metotları

generateRandomString

Giriş

Bağlam

İş Akışı

Kimlik Doğrulama Akışı

Yetkilendirme Akışı

Uygulama

Önizleme

Constructor

Kullanıcı kimlik doğrulamasını başlat

Yetkilendirme sunucusundan OIDC yapılandırmalarını alın

PKCE Generator

State parametresi oluştur

Ara session bilgisini sakla

Sign-in

Kullanıcı oturum açma geri çağrısını işleme

Geri çağrı URL'sini çıkar ve doğrula

Kod değişim talebini gönder

Kullanıcı oturum açma geri çağrısını işleme

ID token doğrulaması

Kullanıcı bilgilerini al

Korumalı kaynak yetkilendirmesi için erişim tokenı al

Özet

Ek

Ayrılmış kapsamlar

Logto Config

Util metotları

generateRandomString