"invalid_grant" hatasını anlama ve çözme üzerine OIDC hibeleri keşfetme

Arka plan#

Topluluğumuzda, kullanıcılarımızdan çoğunlukla tekrar eden bir soru duyarız: ** Logto'daki "invalid_grant" hatasının olması ne anlama geliyor?** İşte #503 gibi.

Bu, kullanıcılarımızın bazıları için Logto'yu kendi uygulamalarına entegre ederken karşılaştıkları genel bir sorun ve engeldir. Ancak, bu hatanın ardındaki sebepler durumdan duruma değişir ve bazen sağlanan sınırlı bağlama ile açıklaması zordur. Bu nedenle, tam OIDC kavramını anlamak ve sorunu çözme yolu öğrenmek herkes için gereklidir.

Şimdi OIDC hibelerinin temellerine bir göz atalım.

OIDC hibeleri açıklanıyor#

Daha önce bir blog gönderisinde tanıttığımız gibi, OpenID Connect (OIDC), OAuth 2.0 protokolünün üzerine inşa edilmiştir.

OIDC veya OAuth2 bağlamında, bir hibe genellikle bir kullanıcı olan kaynak sahibi tarafından bir istemci uygulamasına verilen bir dizi izindir. Hibeler, istemci uygulamanın kullanıcının kimlik bilgilerine ve diğer korunan kaynaklara erişimi için önemlidir. OIDC, her biri farklı bir senaryoya uyan ve bir uygulamanın bir erişim belgesine nasıl eriştiği konusunda farklı hibe türlerini tanımlar.

Size OIDC hibelerini daha iyi anlamanızı sağlamak için bir örnek verelim.

Farklı ülkelere seyahat ettiğinizi ve her ülkenin giriş için vize damgası talep ettiğini düşünün. Bu senaryoda, pasaportunuz kullanıcı hesabınız olarak hizmet eder ve kişisel bilgilerinizi içerir. OIDC hibeleri, bir ülkeye giriş yapmak için bir vize başvurusunda bulunmanın yolları gibidir. Bir vize size verildiğinde, bu ülkeye girebilmek için "belge" alırız.

Benzer bir şekilde, bir uygulamayı kullandığınızda, hibe talebi, yetkilendirme sunucusuna sizin erişim sağlamasını talep ettiğiniz eylemdir. Yetkilendirme sunucusu kimliği doğrular ve sizi uygulamaya giriş yapmak için "vize" (erişim belgesi) ile donatır.

Yaygın kullanılan OIDC hibe türleri:#

1. Yetkilendirme Kodu Hibe: Bu, OIDC'de en sık kullanılan hibe türüdür. Kullanıcının bir yetkilendirme sunucusuna yönlendirilmesini, bir yetkilendirme kodu elde etmeyi, uygulamaya geri yönlendirmeyi ve kodu bir erişim belgesi için takas etmeyi içerir. Bir yabancı ülkeye girmeden önce elçilikten bir vize almanın standart süreci gibi düşünebilirsiniz.
2. Yenileme Belgesi Hibe: OIDC'de bu hibe türü, bir istemci uygulamanın daha önce verilen bir yenileme belgesini kullanarak yeni bir erişim belgesi elde etmesine imkan tanır. Genellikle bir kullanıcının oturumunu kimlik bilgilerini tekrar girmelerini gerektirmeden uzatmak için kullanılır. Vizeniz, gümrüğe gitmeden ülkede kalmayı uzatmanızı sağlayan bir sihirli bir kartla geldiğini hayal edin.
3. Geçersiz Hibe: Bu hibe türü, eski tarayıcı tabanlı uygulamalar için kullanılır ve Yetkilendirme Kodu Hibe'den daha az güvenlidir. Erişim belgesini doğrudan istemci uygulamasına döndürür. Daha önce vize başvurusu gerektirmeyen bir "varışta vize" gibidir.
4. İstemci Kimlik Doğrulama Hibe: Sunucudan sunucuya iletişim için uygun olan bu hibe türü, bir istemci uygulamasının kimlik bilgilerini (istemci ID ve istemci gizli) kullanarak yetkilendirme sunucusunda doğrudan kimlik doğrulaması yapmasına olanak sağlar. Bu, bir özel ajanın vize başvurusu sürecine gitmeden, özel iş rozeti göstererek ülkeye giriş yapması gibidir.

Hibe nesne modeli:#

Logto'da, hibe, kullanıcı hesabı ID'si, uygulama ID'si, ilgili OIDC kaynakları ve kapsamları, süresi, ve daha fazlası gibi bilgileri içeren bir nesne varlığı olarak veritabanında saklanır. Her yenileme belgesi ve erişim belgesi, belirli bir hibe nesnesiyle ilişkilendirilmiştir.

Hibe talepleri:#

API’ler aracılığıyla yetkilendirme sunucusuna yapılan HTTP istekleri. Bir istemci uygulaması, yeni bir hibe başvurusu yapma (örneğin, oturum açma ve yenileme ve erişim belgeleri edinme), hibe detaylarını güncelleme (örneğin, yeni bir erişim belgesi için bir yenileme belgesini takas etme) veya bir hibe iptal etme (örneğin, oturum açmış kullanıcılara verilen tüm belgeleri iptal etme ve erişimlerini sonlandırma) gibi çeşitli amaçlarla, OIDC belge uç noktasına hibe talepleri gönderebilir.

Typical bir yetkilendirme kodu hibe talebi şöyle görünür:

"invalid_grant" hatasını anlama#

OIDC'de genellikle invalid_grant hatası almak, hibe türünün veya hibe talebi ile ilişkili verinin geçersiz veya desteklenmediğini gösterir. Bu hatanın ardında yatan bazı yaygın sebepler şunlardır:

1. Yanlış hibe türü: Uygulamanız için yanlış hibe türünü kullanıyor olabilir ve bu da invalid_grant hatasına yol açabilir. Uygulamanız için uygun hibe türünü kullandığınızdan emin olun, Logto SDK'larından faydalanın.
2. Eşleşmeyen yönlendirme URI'leri: Belirtilerin bir yetkilendirme kodu ile oturum açma kodu takas edilirken, istekte kullanılan yönlendirme URI'sinin ilk yetkilendirme talebi sırasında kullanılanla eşleşmesi gerekir. Eşleşmeme, bir invalid_grant hatasına yol açabilir.
3. Süresi dolmuş veya kullanılmış yetkilendirme kodu: Yetkilendirme Kodu oturum açma akışında, yetkilendirme kodunun sınırlı bir ömrü vardır ve belgeleri almak için kullanıldığında "kullanılmış" olarak işaretlenir. Süresi dolmuş veya kullanılan bir kodun erişim belgesi için takas edilmesi, bir invalid_grant hatasına yol açar.
4. Süresi dolmuş veya dönen yenileme belgesi: Bir yenileme belgesini bir erişim belgesi için takas ederken, yenileme belgesinin zaten sona ermiş olması durumunda invalid_grant hatası oluşur. Ayrıca, daha fazla güvenlik için, Logto varsayılan olarak yenileme belgesi döndürmeyi etkinleştirir. Aynı yenileme belgesi ile ikinci defa belge uç noktasını talep etmek, "dönüşmüş" bir yenileme belgesini kullanmak olarak kabul edilir ve reddedilir.
5. Zorunlu verinin veya istek başlıklarının eksik olması: Bir hibe isteği oluştururken, belirli bir hibe türü için zorunlu parametreler ve istek başlıkları sağlanmalıdır. Örneğin, istemci ID'si tüm hibe isteklerinde sağlanmalıdır ve İstemci Kimlik Bilgileri Hibe için istemci ID'si ve istemci gizlisi sağlanmalıdır. Bu risk, Logto SDK'larından faydalanarak da azaltılabilir.
6. Diğer sebepler: Bu hata, müşteri kimlik bilgileri uyuşmazlığı, hibenin süresinin dolmuş olması veya bulunabilir olmaması, yenileme belgesinin bulunamaması vb. nedenlerle de meydana gelebilir.

Sorun giderme#

"invalid_grant" hatasını etkili bir şekilde gidermek için bazı ipuçları:

1. Logto'yu uygulamanıza entegre etmek için her zaman bir Logto istemci SDK'sını kullanın, böylece hibe taleplerinin ilgili uç noktasına ve doğru verilerle yapıldığından emin olabilirsiniz.
2. Uygulama kimlik bilgilerinizin ve yönlendirme URI'lerinizin Yönetici Konsolu'ndaki yapılandırmalarla eşleştiğini doğrulayın.
3. Fazla istekler yapmaktan kaçının, özellikle bağımlılık değişikliklerinden dolayı sayfa bileşenlerinin yeniden oluşturulabileceği SPA'lar (tek sayfalık uygulamalar) gibi React ve Vue için. Kodların veya yenileme belgelerinin erişim belgeleri için takas edilmek üzere kullanılan fonksiyonların aynı istek parametreleriyle birden çok kez tetiklenmediğinden emin olun.
4. Süre sonu zamanlarını kontrol edin. Örneğin, yenileme belgenizin süresi dolmuş (varsayılan olarak 14 gün) ve invalid_grant hatasını alıyorsanız, bir kullanıcı oturum açma akışını tekrar başlatarak bunu uygun bir şekilde yönetmelisiniz. Eğer Logto SDK'sını kullanıyorsanız, kullanıcılarınızı tekrar oturum açma sayfasına yönlendirmek için signIn() fonksiyonunu tekrar çağırabilirsiniz.
5. Denetim kayıtlarını izleyin. Yönetici Konsolu'na gidin→ Denetim Kayıtları, olayla ilişkili hata günlüğünü bulun ve ayrıntılı hata yığın izini kontrol edin. Genellikle, invalid_grant hatasının ardında "Grant bulunamadı" veya "Yenileme belgesi sona erdi" gibi daha spesifik bir sebep bulunur.

Sonuç notları#

invalid_grant hatası, başlangıçta zor ve karışık olabilir, ancak OIDC hibelerinin net bir anlayışına ve detaylara dikkat ederek, sorunu kendiniz belirleyebilir ve çözebilirsiniz. Discord veya GitHub'daki tartışmalarımıza katılın ve bu blogun karışıklığı aydınlattığını ve karşılaştığınız sorunları belirlemenize yardımcı olup olmadığını bize bildirin. Logto dev ekibi her zaman size yardımcı olmaktan mutluluk duyar.

Birlikte, sevdiğiniz uygulamalarınız için sorunsuz ve güvenli bir kimlik doğrulama deneyimi oluşturalım.