Yeniden yönlendirme URI'si (yanıt URL'si) ana hattı ve kısıtlamaları

Microsoft kimlik platformuyla tümleşen uygulamalar oluştururken, yeniden yönlendirme URI'lerinin nasıl yapılandırıldığını anlamak önemlidir. Bu makalede, URI en iyi yöntemlerini, desteklenen yapılandırmaları ve sınırlamaları yeniden yönlendirmek için kapsamlı bir kılavuz sağlanır. Web, mobil veya masaüstü uygulaması geliştirirken bu makale, yeniden yönlendirme URI'lerini güvenlik gereksinimlerini karşılayacak şekilde doğru şekilde yapılandırmanıza yardımcı olacaktır.

Yeniden yönlendirme URI'si nedir?

Yeniden yönlendirme URI'si veya yanıt URL'si, Microsoft Entra kimlik doğrulama sunucusunun kullanıcıyı başarıyla yetkilendikten ve erişim belirteci verildikten sonra gönderdiği konumdur. Bir kullanıcıda oturum açmak için uygulamanızın parametre olarak belirtilen yeniden yönlendirme URI'sine sahip bir oturum açma isteği göndermesi gerekir, bu nedenle kullanıcı başarıyla oturum açtıktan sonra, kimlik doğrulama sunucusu kullanıcıyı yeniden yönlendirir ve oturum açma isteğinde belirtilen yeniden yönlendirme URI'sine bir erişim belirteci verir.

Örneğin üretim web uygulamasında yeniden yönlendirme URI'si genellikle uygulamanızın çalıştığı genel bir uç noktadır, örneğin https://contoso.com/auth-response. Geliştirme sırasında uygulamanızı https://127.0.0.1/auth-response veya http://localhost/auth-responsegibi yerel olarak çalıştırdığınız uç noktayı da eklemek yaygın bir işlemdir. Üretim uygulamasında gereksiz geliştirme ortamlarının/yeniden yönlendirme URI'lerinin gösterilmediğinden emin olun. Bu, geliştirme ve üretim için ayrı uygulama kayıtlarına sahip olarak yapılabilir.

Yeniden yönlendirme URI'lerinin neden bir uygulama kaydına eklenmesi gerekiyor?

Güvenlik nedeniyle, kimlik doğrulama sunucusu kullanıcıları yeniden yönlendirmez veya belirteçleri uygulama kaydına eklenmemiş bir URI'ye göndermez. Microsoft Entra oturum açma sunucuları yalnızca kullanıcıları yeniden yönlendirir ve belirteçleri bir uygulama kaydına eklenmiş URI'leri yeniden yönlendirmek için gönderir. Oturum açma isteğinde belirtilen yeniden yönlendirme URI'leri uygulamanıza eklediğiniz yeniden yönlendirme URI'lerinden herhangi biriyle eşleşmiyorsa, gibi AADSTS50011: The reply URL specified in the request does not match the reply URLs configured for the applicationbir hata iletisi alırsınız.

Hata kodları hakkında daha fazla bilgi için bkz . Microsoft Entra kimlik doğrulaması ve yetkilendirme hata kodları.

Uygulama kaydına yeniden yönlendirme URI'sini eklemeli miyim?

Uygulama kaydınıza yeniden yönlendirme URI'sini eklemeniz gerekip gerekmediği, uygulamanızın kullandığı yetkilendirme protokolüne bağlıdır. Uygulamanız aşağıdaki yetkilendirme protokollerini kullanıyorsa, uygulama kaydınıza uygun yeniden yönlendirme URI'leri eklemeniz gerekir:

• OAuth 2.0 yetkilendirme kod akışı
• OAuth 2.0 istemci kimlik bilgileri akışı
• OAuth 2.0 örtük izin akışı
• OpenID Bağlan
• Çoklu oturum açma SAML protokolü

Uygulamanız aşağıdaki yetkilendirme protokollerini veya özelliklerini kullanıyorsa, uygulama kaydınıza yeniden yönlendirme URI'leri eklemeniz gerekmez.

• Yerel Kimlik Doğrulaması
• OAuth 2.0 cihaz kodu akışı
• OAuth 2.0 Adına akış
• OAuth 2.0 Kaynak sahibinin parola kimlik bilgileri akışı
• Windows Tümleşik Kimlik Doğrulama Akışı
• Çoklu Oturum Açma için SAML 2.0 Kimlik Sağlayıcısı (IdP)

Yeniden yönlendirme URI'lerimi hangi platforma eklemeliyim?

Oluşturduğunuz uygulama, uygulama kaydınızda bir veya birden çok yeniden yönlendirme URI'sini içeriyorsa, genel istemci akışı yapılandırmasını etkinleştirmeniz gerekir. Aşağıdaki tablolar, uygulamanızı oluşturduğunuz platforma göre eklemeniz gereken veya eklememeniz gereken yeniden yönlendirme URI'sinin türü hakkında rehberlik sağlar.

Web uygulaması yeniden yönlendirme URI yapılandırması

Uygulamanızın türü	Tipik diller/Çerçeveler	Uygulama Kaydı'nda yeniden yönlendirme URI'sini ekleme platformu
Uygulama mantığının çoğunun sunucuda gerçekleştirildiği geleneksel bir web uygulaması	Node.js, web, ASP.NET, Python, Java, ASP.NET Core, PHP, Ruby, Blazor Server	Ağ
Web tarayıcısında kullanıcı arabirimi mantığının çoğunun gerçekleştirildiği ve web API'leri kullanılarak web sunucusuyla iletişim kurulan bir tek sayfalı uygulama.	JavaScript, Angular, React, Blazor WebAssembly, Vue.js	Tek sayfalı uygulama (SPA)

Mobil ve masaüstü uygulamalar için yeniden yönlendirme URI yapılandırması

Uygulamanızın türü	Tipik diller/Çerçeveler	Uygulama Kaydı'nda yeniden yönlendirme URI'sini ekleme platformu
Bu tablonun altında listelenen senaryolar dışında bir iOS veya macOS uygulaması	Swift, Objective-C	IOS/macOS
Android uygulaması	Java veya Kotlin	Android
Mobil cihazda veya masaüstü makinede yerel olarak çalışan bir uygulama	Node.js elektron, Windows masaüstü, UWP, React Native, Android, iOS/macOS	Mobil ve masaüstü uygulamaları

Aşağıdaki yöntemlerden birini kullanarak bir iOS uygulaması oluşturuyorsanız mobil ve masaüstü uygulamaları platformunu kullanarak yeniden yönlendirme URI'sini ekleyin:

• açık kaynak SDK'ları kullanan iOS uygulamaları (AppAuth)
• Desteklemediğimiz platformlar arası teknoloji kullanan iOS uygulamaları (Flutter)
• OAuth protokollerimizi doğrudan uygulayan iOS uygulamaları
• Desteklemediğimiz platformlar arası teknoloji kullanan macOS uygulamaları (Electron)

Yeniden yönlendirme URI'sini gerektirmeyen uygulamalar

Uygulama türü	Örnekler/notlar	Bağlantılı OAuth akışı
Klavyesi olmayan cihazlarda çalışan uygulamalar	Akıllı TV, IoT cihazı veya yazıcıda çalışan uygulamalar	Cihaz kodu akışı hakkında daha fazla bilgi edinin
Kullanıcıların parolaları işleyen uygulamalar, kullanıcıları Entra barındırılan oturum açma web sitesine yönlendirmek ve Entra'nın kullanıcı parolasını güvenli bir şekilde işlemesine izin vermek yerine doğrudan girer.	Bu akışı, Yetkilendirme kodu akışı gibi diğer daha güvenli akışların uygulanabilir olmadığı durumlarda, çünkü yeterince güvenli değildir, kullanmanız gerekir.	Kaynak sahibi parola kimlik bilgisi akışı daha fazla bilgi edinin
Web hesabı yöneticisi yerine Windows Tümleşik Kimlik Doğrulama Akışı kullanarak Windows üzerinde veya Windows etki alanına bağlı bir makinede (AD veya Azure AD'ye katılmış) çalışan masaüstü veya mobil uygulamalar	Kullanıcı Windows bilgisayar sisteminde Entra kimlik bilgileriyle oturum açtıktan sonra otomatik olarak oturum açması gereken bir masaüstü veya mobil uygulama	Windows Tümleşik Kimlik Doğrulama Akışı daha fazla bilgi edinin

Microsoft Entra uygulamaları için yeniden yönlendirme URI'lerinin kısıtlamaları nelerdir?

Microsoft Entra uygulama modeli, URI'leri yeniden yönlendirmek için aşağıdaki kısıtlamaları belirtir:

• Yeniden yönlendirme URI'leri, bazı localhost yeniden yönlendirme URI'leri için istisnalar dışında, https şeması ile başlamalıdır.

• Yeniden yönlendirme URI'leri büyük/küçük harfe duyarlıdır ve çalışan uygulamanızın URL yolu ile eşleşmelidir.

  Örnekler:

  • Uygulamanız yolunun bir parçası olarak .../abc/response-oidc içeriyorsa, yeniden yönlendirme URI'sinde .../ABC/response-oidc belirtmeyin. Web tarayıcısı yolları büyük/küçük harfe duyarlı olarak ele aldığından, büyük/küçük harf uyuşmazlığı olan .../abc/response-oidc URL'ye yönlendirildiğinde, .../ABC/response-oidc ile ilişkili tanımlama bilgileri dışlanabilir.

• Yol kesimiyle yapılandırılmamış yeniden yönlendirme URI'leri yanıtta sonunda eğik çizgi ('/') olacak şekilde döndürülür. Bu yalnızca yanıt modu query veya fragment olduğunda geçerlidir.

  Örnekler:

  • https://contoso.com olarak döndürülür https://contoso.com/
  • http://localhost:7071 olarak döndürülür http://localhost:7071/

• Yol kesimi içeren yeniden yönlendirme URI'lerine yanıt içerisinde sondaki eğik çizgi eklenmez.

  Örnekler:

  • https://contoso.com/abc olarak döndürülür https://contoso.com/abc
  • https://contoso.com/abc/response-oidc olarak döndürülür https://contoso.com/abc/response-oidc

• Yeniden yönlendirme URI'leri özel karakterleri desteklemez - ! $ ' ( ) , ;

• Yeniden Yönlendirme URI'leri Uluslararası Etki Alanı Adlarını desteklemiyor

Yeniden yönlendirme URI'lerinin maksimum sayısı ve URI uzunluğu üst sınırı

Yeniden yönlendirme URI'lerinin en fazla sayısı güvenlik nedeniyle artırılamaz. Senaryonuz izin verilen en yüksek sınırdan daha fazla yeniden yönlendirme URI'sine ihtiyaç duyuyorsa çözüm olarak aşağıdaki durum parametresi yaklaşımını göz önünde bulundurun. Aşağıdaki tabloda, Microsoft kimlik platformu bir uygulama kaydına ekleyebileceğiniz maksimum yeniden yönlendirme URI'leri sayısı gösterilmektedir.

Oturum açan hesaplar	Yeniden yönlendirme URI'lerinin maksimum sayısı	Açıklama
Herhangi bir kuruluşun Microsoft Entra kiracısında Microsoft iş veya okul hesapları	256	signInAudienceuygulama bildirimindeki alanı AzureADMyOrg veya AzureADMultipleOrgs olarak ayarlanmıştır
Kişisel Microsoft hesapları, iş ve okul hesapları	100	signInAudienceuygulama bildirimindeki alanı AzureADandPersonalMicrosoftAccount olarak ayarlandı

Uygulama kaydına eklediğiniz her yeniden yönlendirme URI'sinde en fazla 256 karakter kullanabilirsiniz.

Uygulamadaki yönlendirme URI'leri ve hizmet asıl öğeleri

• Yeniden yönlendirme URI'lerini her zaman yalnızca uygulama nesnesine ekleyin.
• Hizmet sorumlusu nesnesi uygulama nesnesiyle eşitlendiğinde bu değerler kaldırılabildiği için hiçbir zaman hizmet sorumlusuna yeniden yönlendirme URI'si değerleri eklemeyin. Bu durum, iki nesne arasında eşitleme tetikleyen herhangi bir güncelleştirme işleminden kaynaklanabilir.

Yeniden yönlendirme URI'lerinde sorgu parametresi desteği

Sorgu parametrelerine, yalnızca iş veya okul hesabı olan kullanıcıları oturum açtıran uygulamalar için yeniden yönlendirme URI'lerinde izin verilir.

Outlook.com (Hotmail), Messenger, OneDrive, MSN, Xbox Live veya Microsoft 365 gibi kişisel Microsoft hesaplarına sahip kullanıcılarla oturum açmak üzere yapılandırılmış herhangi bir uygulama kaydı için yeniden yönlendirme URI'lerinde sorgu parametrelerine izin verilmez .

Uygulama kaydı için giriş yapan hedef kitle	Yeniden yönlendirme URI'sinde sorgu parametrelerini destekler
Yalnızca bu kuruluş dizinindeki hesaplar (yalnızca Contoso - Tek kiracı)
Herhangi bir organizasyon dizinindeki hesaplar (Herhangi bir Microsoft Entra dizini - Çok kiracılı)
Herhangi bir kuruluş dizinindeki hesaplar (Herhangi bir Microsoft Entra dizini - Çok Kiracılı) ve kişisel Microsoft hesapları (Skype ve Xbox gibi)
Yalnızca kişisel Microsoft hesapları

Desteklenen düzenler

HTTPS: HTTPS şeması (https://) tüm HTTP tabanlı yeniden yönlendirme URI'leri için desteklenir.

HTTP: HTTP şeması (http://) yalnızca localhost URI'leri için desteklenir ve yalnızca etkin yerel uygulama geliştirme ve test sırasında kullanılmalıdır.

Örnek yeniden yönlendirme URI'si	Geçerlilik
https://contoso.com	Geçerli
https://contoso.com/abc/response-oidc	Geçerli
https://localhost	Geçerli
http://contoso.com/abc/response-oidc	Geçersiz
http://localhost	Geçerli
http://localhost/abc	Geçerli

Localhost özel durumları

RFC 8252 bölümleri 8.3 ve 7.3'e göre, "loopback" veya "localhost" yeniden yönlendirme URI'leri iki özel hususla birlikte gelir:

1. http Yeniden yönlendirme hiçbir zaman cihazdan ayrılmadığından URI düzenleri kabul edilebilir. Bu nedenle, bu URI'lerin her ikisi de kabul edilebilir:

   • http://localhost/myApp
   • https://localhost/myApp

2. Genellikle yerel uygulamalar için gereken kısa ömürlü bağlantı noktası aralıkları nedeniyle, bağlantı noktası bileşeni (örneğin, :5001 veya :443) bir localhost yeniden yönlendirme URI'sini eşleştirme amacıyla yoksayılır. Sonuç olarak, bu URI'lerin tümü eşdeğer kabul edilir:

   • http://localhost/MyApp
   • http://localhost:1234/MyApp
   • http://localhost:5000/MyApp
   • http://localhost:8080/MyApp

   Bu yalnızca localhost yeniden yönlendirme URI'leri için geçerlidir. Diğer tüm durumlarda, yeniden yönlendirme URI'leri eşleştirilirken bağlantı noktası bileşeni yoksayılmaz .

Geliştirme açısından bakıldığında, bu birkaç anlama gelir:

• Yalnızca bağlantı noktasının farklı olduğu birden çok localhost yeniden yönlendirme URI'sini kaydetmeyin. Oturum açma sunucusu rastgele bir yeniden yönlendirme URI'si seçer ve bu kayıtlı yeniden yönlendirme URI'si ile ilişkili davranışı kullanır (örneğin, -, web-, veya native-type yeniden yönlendirmesispa).

  Bu, özellikle aynı uygulama kaydında farklı kimlik doğrulama akışları kullanmak istediğinizde (örneğin hem yetkilendirme kodu verme hem de örtük akış) önemlidir. Her yeniden yönlendirme URI'siyle doğru yanıt davranışını ilişkilendirmek için oturum açma sunucusunun yeniden yönlendirme URI'lerini ayırt edebilmesi gerekir ve yalnızca bağlantı noktası farklı olduğunda bunu yapamaz.

• Geliştirme sırasında farklı akışları test etmek üzere localhost'a birden çok yeniden yönlendirme URI'si kaydetmek için, bunları URI'nin yol bileşenini kullanarak ayırt edin. Örneğin, http://localhost/MyWebApp ile eşleşmiyor http://localhost/MyNativeApp.

• IPv6 geri döngü adresi ([::1]) şu anda desteklenmiyor.

Localhost yerine 127.0.0.1'i tercih edin

Yanlış yapılandırılmış güvenlik duvarları veya yeniden adlandırılmış ağ arabirimleri nedeniyle uygulamanızın bozulmasını önlemek için, yönlendirme URI'nizdeki 127.0.0.1 yerine IP sabit geri döngü adresi localhost kullanın. Örneğin, https://127.0.0.1.

Bununla birlikte, Azure portalındaki Yeniden Yönlendirme URI'leri metin kutusunu kullanarak şemayı kullanan geri döngü tabanlı bir yeniden yönlendirme URI'sini http ekleyemezsiniz:

Geri döngü adresiyle şeması kullanarak bir yönlendirme URI'si eklemek için, şu anda uygulama bildiriminde replyUrlsWithType özniteliğini değiştirmeniz gerekir.

Yeniden yönlendirme URI'lerinde joker karakter kullanımlarına getirilen kısıtlamalar

Gibi https://*.contoso.com joker karakter URI'leri kullanışlı görünebilir, ancak güvenlik etkilerinden dolayı kaçınılmalıdır. OAuth 2.0 belirtimine (RFC 6749'un bölüm 3.1.2) göre yeniden yönlendirme uç noktası URI'sinin mutlak bir URI olması gerekir. Bu nedenle, yapılandırılan bir joker URI, bir yönlendirme URI'si ile eşleştiğinde, yönlendirme URI'sindeki sorgu dizeleri ve parçalar çıkarılır.

Kişisel Microsoft hesaplarında ve iş veya okul hesaplarında oturum açmak üzere yapılandırılmış uygulama kayıtlarında joker karakter URI'leri şu anda desteklenmiyor. Ancak, kuruluşun Microsoft Entra kiracısında yalnızca iş veya okul hesaplarında oturum açmak üzere yapılandırılmış uygulamalar için joker karakter URI'lerine izin verilir.

İş veya okul hesaplarında oturum açabilen uygulama kayıtlarına joker karakterler içeren yeniden yönlendirme URI'leri eklemek için Azure portalındaki Uygulama kayıtları uygulama bildirimi düzenleyicisini kullanın. Bildirim düzenleyicisini kullanarak joker karakterle yeniden yönlendirme URI'sini ayarlamak mümkün olsa da RFC 6749'un 3.1.2 bölümüne bağlı kalmanızı kesinlikle öneririz. ve yalnızca mutlak URI'leri kullanın.

Senaryonuz izin verilen en yüksek sınırdan daha fazla yeniden yönlendirme URI'sine ihtiyaç duyuyorsa joker karakter yeniden yönlendirme URI'sini eklemek yerine aşağıdaki durum parametresi yaklaşımını göz önünde bulundurun.

Durum parametresi kullanma

Birkaç alt etki alanınız varsa ve senaryonuz başarılı kimlik doğrulamasından sonra kullanıcıları başlatıldıkları sayfaya yönlendirmenizi gerektiriyorsa, durum parametresi kullanmak yararlı olabilir.

Bu yaklaşımda:

1. Yetkilendirme uç noktasından aldığınız güvenlik belirteçlerini işlemek için uygulama başına "paylaşılan" yeniden yönlendirme URI'sini oluşturun.
2. Uygulamanız, durum parametresinde uygulamaya özgü parametreler (kullanıcının kaynaklandığı alt etki alanı URL'si veya marka bilgileri gibi herhangi bir şey) gönderebilir. Durum parametresi kullanırken, RFC 6749'un 10.12. bölümünde belirtildiği gibi CSRF korumasına karşı koruma sağlayın. Güvenlik ve gizlilik için URL'leri veya diğer hassas verileri doğrudan durum parametresine koymayın. Bunun yerine, localStorage veya sessionStorage gibi tarayıcı depolama alanında depolanan verilere karşılık gelen bir anahtar veya tanımlayıcı kullanın. Bu yaklaşım, uygulamanızın kimlik doğrulamasından sonra gerekli verilere güvenli bir şekilde başvurmasını sağlar.
3. Uygulamaya özgü parametreler, uygulamanın kullanıcı için doğru deneyimi işlemesi için gereken tüm bilgileri, yani uygun uygulama durumunu oluşturmasını içerir. Microsoft Entra yetkilendirme uç noktası, HTML'yi durum parametresinden kaldırır, bu nedenle bu parametreye HTML içeriği geçirmediğinizden emin olun.
4. Microsoft Entra Kimliği "paylaşılan" yeniden yönlendirme URI'sine bir yanıt gönderdiğinde, durum parametresini uygulamaya geri gönderir.
5. Uygulama daha sonra kullanıcıyı daha fazla göndereceği URL'yi belirlemek için durum parametresindeki değerini kullanabilir. CSRF koruması için doğrulama yaptığınızdan emin olun.

Uyarı

Bu yaklaşım, güvenliği aşılmış bir istemcinin durum parametresinde gönderilen ek parametreleri değiştirmesine olanak tanır ve böylece kullanıcıyı RFC 6819'da açıklanan açık yeniden yönlendirici tehdidi olan farklı bir URL'ye yönlendirir. Bu nedenle, istemci bu parametreleri korumak için durumu şifrelemeli veya başka bir yöntemle, örneğin yeniden yönlendirme URI'sindeki etki alanı adını belirteçle doğrulamak gibi bir doğrulama yapmalıdır.

Sonraki adımlar

Uygulama kaydı Uygulama bildirimi hakkında bilgi edinin.