OpenID Connect ve Azure Active Directory kullanarak web uygulamalarına erişimi yetkilendirme

Uyarı

Bu içerik eski Azure AD v1.0 uç noktasına yöneliktir. Yeni projeler için Microsoft kimlik platformu kullanın.

OpenID Connect, OAuth 2.0 protokolünün üzerine kurulmuş basit bir kimlik katmanıdır. OAuth 2.0, korumalı kaynaklara erişmek içinerişim belirteçlerini almak ve kullanmak için mekanizmalar tanımlar, ancak kimlik bilgileri sağlamak için standart yöntemler tanımlamaz. OpenID Connect, kimlik doğrulamasını OAuth 2.0 yetkilendirme işleminin uzantısı olarak uygular. Kullanıcının kimliğini doğrulayan ve kullanıcı hakkında temel profil bilgileri sağlayan bir id_token biçiminde son kullanıcı hakkında bilgi sağlar.

Sunucuda barındırılan ve tarayıcı üzerinden erişilen bir web uygulaması oluşturuyorsanız, OpenID Connect önerimizdir.

AD kiracınıza uygulamanızı kaydedin

İlk olarak uygulamanızı Azure Active Directory (Azure AD) kiracınıza kaydedin. Bu size uygulamanız için bir Uygulama Kimliği verir ve belirteçleri almasını sağlar.

1. Azure portalınaoturum açın.

2. Azure AD kiracınızı seçmek için, sayfanın sağ üst köşesinden hesabınızı seçin, ardından Dizin Değiştir navigasyonunu ve uygun kiracıya geçişi seçin.

   • Hesabınızda yalnızca bir Azure AD kiracısı varsa veya uygun Azure AD kiracısını zaten seçtiyseniz bu adımı atlayın.

3. Azure portalında Azure Active Directoryaraması yapın ve öğesini seçin.

4. Azure Active Directory sol menüsünde Uygulama Kayıtlarıve ardından Yeni Kayıtseçin.

5. İstemleri izleyin ve yeni bir uygulama oluşturun. Bu öğretici için bir web uygulaması veya genel istemci (mobil & masaüstü) uygulaması olması önemli değildir, ancak web uygulamaları veya genel istemci uygulamaları için belirli örnekler istiyorsanız hızlı başlangıçlarımıza göz atın.

   • Name uygulama adıdır ve uygulamanızı son kullanıcılara açıklar.
   • Desteklenen hesap türleri'nin altında Herhangi bir kuruluş dizinindeki hesaplar ve kişisel Microsoft hesapları'nı seçin.
   • Yönlendirme URI'sinisağlayın. Web uygulamaları için bu, uygulamanızın kullanıcıların oturum açabileceği temel URL'dir. Örneğin, http://localhost:12345. Genel istemci (mobil & masaüstü) için Azure AD bunu belirteç yanıtlarını döndürmek için kullanır. Uygulamanıza özgü bir değer girin. Örneğin, http://MyFirstAADApp.

6. Kaydı tamamladıktan sonra Azure AD, uygulamanıza benzersiz bir istemci tanımlayıcısı atar (Uygulama Kimliği). Sonraki bölümlerde bu değere ihtiyacınız vardır, bu nedenle uygulama sayfasından kopyalayın.

7. Uygulamanızı Azure portalında bulmak için Uygulama kayıtları'nı ve ardından tüm uygulamaları görüntüleseçin.

OpenID Connect kullanarak kimlik doğrulama akışı

En temel oturum açma akışı aşağıdaki adımları içerir. Bunların her biri aşağıda ayrıntılı olarak açıklanmıştır.

OpenId Connect Kimlik Doğrulama AkışıOpenId Connect Authentication Flow

OpenID Connect meta veri belgesi

OpenID Connect, bir uygulamanın oturum açma gerçekleştirmesi için gereken bilgilerin çoğunu içeren meta veri belgesini açıklar. Bu, kullanılacak URL'ler ve hizmetin genel imzalama anahtarlarının konumu gibi bilgileri içerir. OpenID Connect meta veri belgesine şu konumdan ulaşabilirsiniz:

https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration

Meta veriler basit bir JavaScript Nesne Gösterimi (JSON) belgesidir. Bir örnek için aşağıdaki kod parçacığına bakın. Kod parçacığının içeriği, OpenID Connect belirtimi'de tam olarak açıklanmıştır. Yukarıdaki {tenant} yerine common yerine kiracı kimliği sağlanmasının, döndürülen JSON nesnesinde kiracıya özgü URI'lere neden olacağını unutmayın.

{
    "authorization_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/authorize",
    "token_endpoint": "https://login.microsoftonline.com/{tenant}/oauth2/token",
    "token_endpoint_auth_methods_supported":
    [
        "client_secret_post",
        "private_key_jwt",
        "client_secret_basic"
    ],
    "jwks_uri": "https://login.microsoftonline.com/common/discovery/keys"
    "userinfo_endpoint":"https://login.microsoftonline.com/{tenant}/openid/userinfo",
    ...
}

Uygulamanızın talep eşleme özelliğini kullanmanın bir sonucu olarak özel imzalama anahtarları varsa, uygulama kimliğini içeren appid sorgu parametresini eklemeniz gerekir ki bu da uygulamanızın imzalama anahtarı bilgilerini işaret eden jwks_uri elde etmenizi sağlayacak. Örneğin: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e, jwks_uri'nin https://login.microsoftonline.com/{tenant}/discovery/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e'ini içerir.

Oturum açma isteğini gönderme

Web uygulamanızın kullanıcının kimliğini doğrulaması gerektiğinde, kullanıcıyı /authorize uç noktasına yönlendirmesi gerekir. Bu istek, OAuth 2.0 Yetkilendirme Kodu Akışıilk ayağına benzer ve birkaç önemli ayrım vardır:

• İstek, openid parametresinde kapsam scope içermelidir.
• response_type parametresi id_tokeniçermelidir.
• İstek nonce parametresini içermelidir.

Bu nedenle örnek istek şöyle görünür:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token
&redirect_uri=http%3A%2F%2Flocalhost%3a12345
&response_mode=form_post
&scope=openid
&state=12345
&nonce=7362CAEA-9CA5-4B43-9BA3-34D7C303EBA7

Parametre	Türü	Açıklama
kiracı	Gerekli	{tenant} İstek yolundaki değer, uygulamada kimlerin oturum açabileceğini denetlemek için kullanılabilir. İzin verilen değerler kiracı tanımlayıcılarıdır; örneğin, kiracıdan bağımsız belirteçler için 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 veya contoso.onmicrosoft.com ya da common
müşteri_kimlik	Gerekli	Azure AD'ye kaydettiğinizde uygulamanıza atanan Uygulama Kimliği. Bunu Azure portalında bulabilirsiniz. Azure Active Directorytıklayın, Uygulama Kayıtlarıtıklayın, uygulamayı seçin ve uygulama sayfasında Uygulama Kimliği'ni bulun.
yanıt_türü	Gerekli	OpenID Connect oturum açma için id_token içermelidir. code veya tokengibi diğer response_types de içerebilir.
kapsam	önerilen	OpenID Connect özellikleri, onay kullanıcı arabiriminde "Oturum açma izni" olarak çevrilen openidkapsamını gerektirir. Bu ve diğer OIDC kapsamları v1.0 uç noktasında görmezden gelinir, ancak yine de standartlara uygun istemciler için en iyi yöntemdir.
nonce	Gerekli	İstekte yer alan ve uygulama tarafından oluşturulan bir değer, sonuçta bir talep olarak id_token içinde dahil edilir. Uygulama daha sonra token yenileme saldırılarını önlemek için bu değeri doğrulayabilir. Değer genellikle isteğin kaynağını tanımlamak için kullanılabilecek rastgele, benzersiz bir dize veya GUID'dir.
yönlendirme_uri	önerilen	Uygulamanızın kimlik doğrulama yanıtlarının gönderilip alındığı endpoint olan redirect_uri'si. Portalda kaydettiğiniz redirect_uris'den biriyle, URL ile kodlanmış olması koşuluyla, tam olarak eşleşmelidir. Eksikse, kullanıcı aracısı rastgele olarak uygulama için kaydedilen yeniden yönlendirme URI'lerinden birine geri gönderilir. Uzunluk üst sınırı 255 bayttır
yanıt_modu	opsiyonel	Sonuçta elde edilen authorization_code uygulamanıza geri göndermek için kullanılacak yöntemi belirtir. Desteklenen değerler form_post ve fragment. Web uygulamaları için, belirteçlerin uygulamanıza en güvenli aktarımını sağlamak için response_mode=form_post kullanmanızı öneririz. id_token dahil olmak üzere tüm akışlar için varsayılan değer fragment.
devlet	önerilen	belirteç yanıtında döndürülen istekte yer alan bir değer. İstediğiniz herhangi bir içeriğin dizesi olabilir. Rastgele oluşturulan benzersiz bir değer genellikle siteler arası istek sahteciliği saldırılarını önlemek için kullanılır. Durum, kimlik doğrulaması isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri (örneğin, üzerinde bulunduğu sayfa veya görünüm) kodlamak için de kullanılır.
Uyarı	opsiyonel	Gerekli kullanıcı etkileşiminin türünü gösterir. Şu anda tek geçerli değerler 'login', 'none' ve 'consent' değerleridir. prompt=login, kullanıcıyı bu istekte kimlik bilgilerini girmeye zorlayarak çoklu oturum açmayı olumsuzlar. prompt=none tersidir; kullanıcıya herhangi bir etkileşimli istem sunulmamasını sağlar. İstek, çoklu oturum açma yoluyla sessizce tamamlanamıyorsa uç nokta bir hata döndürür. prompt=consent, kullanıcı oturum açtığında OAuth onayı iletişim kutusunu tetikler ve kullanıcıdan uygulamaya izin vermesini ister.
giriş_ipucu	opsiyonel	Kullanıcı kullanıcı adını önceden biliyorsanız, kullanıcının oturum açma sayfasının kullanıcı adı/e-posta adresi alanını önceden doldurmak için kullanılabilir. Uygulamalar, genellikle yeniden kimlik doğrulaması sırasında bu parametreyi kullanır; bu esnada, kullanıcı adını daha önce preferred_username talebini kullanarak yapılan bir oturum açmadan zaten ayıklamış olur.

Bu noktada kullanıcıdan kimlik bilgilerini girmesi ve kimlik doğrulamasını tamamlaması istenir.

Örnek yanıt

Kullanıcının kimliği doğrulandıktan sonra oturum açma isteğinde belirtilen redirect_uri gönderilen örnek yanıt şöyle görünebilir:

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&state=12345

Parametre	Açıklama
id_token	id_token olanı uygulamanın istediği. kullanıcının kimliğini doğrulamak ve kullanıcıyla oturum başlatmak için id_token kullanabilirsiniz.
devlet	İstekte bulunan ve belirteç yanıtında da döndürülen bir değer. Rastgele oluşturulan benzersiz bir değer genellikle siteler arası istek sahteciliği saldırılarını önlemek için kullanılır. Durum, kimlik doğrulaması isteği gerçekleşmeden önce kullanıcının uygulamadaki durumuyla ilgili bilgileri (örneğin, üzerinde bulunduğu sayfa veya görünüm) kodlamak için de kullanılır.

Hata yanıtı

Hata yanıtları da redirect_uri’e gönderilerek uygulamanın bunları uygun şekilde işleyebilmesi için sağlanabilir.

POST / HTTP/1.1
Host: localhost:12345
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Parametre	Açıklama
hata	Oluşan hata türlerini sınıflandırmak için kullanılabilecek ve hatalara tepki vermek için kullanılabilen bir hata kodu dizesi.
hata açıklaması	Bir geliştiricinin kimlik doğrulama hatasının kök nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi.

Yetkilendirme uç noktası hataları için hata kodları

Aşağıdaki tabloda, hata yanıtının parametresinde error döndürülebilecek çeşitli hata kodları açıklanmaktadır.

Hata Kodu	Açıklama	İstemci Eylemi
geçersiz_istek	Gerekli parametre eksik gibi protokol hatası.	İsteği düzeltin ve yeniden gönderin. Bu bir geliştirme hatasıdır ve genellikle ilk test sırasında yakalanılır.
yetkisiz_istemci	İstemci uygulamasının yetkilendirme kodu istemesine izin verilmiyor.	Bu durum genellikle istemci uygulaması Azure AD'ye kaydedilmediğinde veya kullanıcının Azure AD kiracısına eklenmediğinde oluşur. Uygulama, kullanıcıdan uygulamayı yükleme ve Azure AD'ye ekleme yönergelerini isteyebilir.
erişim reddedildi	Kaynak sahibi onayı reddetti	İstemci uygulaması, kullanıcı onay vermediği sürece devam edemeyeceğini kullanıcıya bildirebilir.
desteklenmeyen yanıt türü	Yetkilendirme sunucusu istekteki yanıt türünü desteklemiyor.	İsteği düzeltin ve yeniden gönderin. Bu bir geliştirme hatasıdır ve genellikle ilk test sırasında yakalanılır.
sunucu_hatası	Sunucu beklenmeyen bir hatayla karşılaştı.	İsteği yeniden deneyin. Bu hatalar geçici koşullardan kaynaklanabilir. İstemci uygulaması kullanıcıya geçici bir hata nedeniyle yanıtının geciktirildiğini açıklayabilir.
geçici olarak mevcut değil	Sunucu geçici olarak isteği işleyemeyecek kadar meşgul.	İsteği yeniden deneyin. İstemci uygulaması kullanıcıya yanıtının geçici bir koşul nedeniyle geciktirildiğini açıklayabilir.
geçersiz_kaynak	Hedef kaynak mevcut olmadığından, Azure AD kaynağı bulamadığından veya doğru yapılandırılmadığından geçersiz.	Bu, kaynak mevcutsa, kiracı ortamında yapılandırılmadığını gösterir. Uygulama, kullanıcıdan uygulamayı yükleme ve Azure AD'ye ekleme yönergelerini isteyebilir.

id_token'u doğrula

Yalnızca bir id_token almak kullanıcının kimliğini doğrulamak için yeterli değildir; imzayı doğrulamanız ve uygulamanızın gereksinimlerine göre id_token talepleri doğrulamanız gerekir. Azure AD uç noktası, belirteçleri imzalamak ve geçerli olduklarını doğrulamak için JSON Web Belirteçleri (JWT) ve ortak anahtar şifrelemesi kullanır.

İstemci kodundaki id_token doğrulamayı seçebilirsiniz, ancak yaygın bir yöntem id_token bir arka uç sunucusuna göndermek ve doğrulamayı orada gerçekleştirmektir.

Senaryonuza bağlı olarak ek talepleri de doğrulamak isteyebilirsiniz. Bazı yaygın doğrulamalar şunlardır:

• Kullanıcının/kuruluşun uygulamaya kaydolmasını sağlama.
• kullanıcının wids veya roles taleplerini kullanarak uygun yetkilendirme/ayrıcalıklara sahip olduğundan emin olun.
• Çok faktörlü kimlik doğrulaması gibi belirli bir kimlik doğrulaması gücünün oluştuğundan emin olun.

id_tokendoğruladıktan sonra kullanıcıyla oturum başlatabilir ve uygulamanızdaki kullanıcı hakkında bilgi edinmek için id_token talepleri kullanabilirsiniz. Bu bilgiler görüntüleme, kayıtlar, kişiselleştirme vb. için kullanılabilir. id_tokens ve talepler hakkında daha fazla bilgi için AAD id_tokens okuyun.

Oturum kapatma isteği gönderme

Kullanıcının uygulamadan çıkışını yapmak istediğinizde, uygulamanızın tanımlama bilgilerini temizlemek veya kullanıcıyla oturumu başka bir şekilde sonlandırmak yeterli değildir. Ayrıca, çıkış yapmak için kullanıcıyı end_session_endpoint'a yönlendirmelisiniz. Bunu yapmazsanız, kullanıcı Azure AD uç noktasıyla geçerli bir tek oturum açma oturumuna sahip olacağı için kimlik bilgilerini yeniden girmeden uygulamanıza yeniden kimlik doğrulaması yapabilir.

Kullanıcıyı basitçe OpenID Connect meta veri belgesinde listelenen end_session_endpoint'a yönlendirebilirsiniz.

GET https://login.microsoftonline.com/common/oauth2/logout?
post_logout_redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F

Parametre	Türü	Açıklama
çıkış sonrası yönlendirme URI	önerilen	Başarılı bir oturum kapatma işleminden sonra kullanıcının yönlendirileceği URL. Bu URL, uygulama kayıt portalınızda uygulamanız için kaydedilen yönlendirme URI'lerinden biriyle eşleşmelidir. post_logout_redirect_uri dahil değilse kullanıcıya genel bir ileti gösterilir.

Tek oturum kapatma

Kullanıcıyı end_session_endpointyönlendirdiğinizde, Azure AD kullanıcının oturumunu tarayıcıdan temizler. Ancak, kullanıcı kimlik doğrulaması için Azure AD kullanan diğer uygulamalarda oturum açmış olabilir. Bu uygulamaların oturumlarını aynı anda kapatmasını sağlamak için Azure AD, kullanıcının halihazırda oturum açmış olduğu tüm uygulamaların kayıtlı LogoutUrl adresine bir HTTP GET isteği gönderir. Uygulamalar, kullanıcıyı tanımlayan tüm oturumları temizleyerek ve 200 yanıt döndürerek bu isteğe yanıt vermelidir. Uygulamanızda tek oturum kapatmayı desteklemek istiyorsanız, uygulamanızın koduna bu tür bir LogoutUrl uygulamanız gerekir. azure portalından LogoutUrl ayarlayabilirsiniz:

1. Azure portalınaoturum açın.
2. Sayfanın sağ üst köşesindeki hesabınıza tıklayarak Active Directory'nizi seçin.
3. Sol gezinti panelinde Azure Active Directory 'ı ve ardından Uygulama kayıtları'nı seçin ve uygulamanızı seçin.
4. Ayarlar 'e tıkladıktan sonra, Özellikler'e tıklayın ve Oturum Kapatma URL'si metin kutusunu bulun.

Jeton Edinme

Birçok web uygulamasının yalnızca kullanıcının oturumunu açması değil, aynı zamanda OAuth kullanarak bu kullanıcı adına bir web hizmetine erişmesi gerekir. Bu senaryo, kullanıcı kimlik doğrulaması için OpenID Connect kullanırken, eşzamanlı olarak authorization_codearacılığıyla access_tokens elde etmek amacıyla kullanılabilecek bir da elde eder.

Erişim Belirteçleri Alma

Erişim belirteçleri almak için, yukarıdan oturum açma isteğini değiştirmeniz gerekir:

// Line breaks for legibility only

GET https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e        // Your registered Application ID
&response_type=id_token+code
&redirect_uri=http%3A%2F%2Flocalhost%3a12345          // Your registered Redirect Uri, url encoded
&response_mode=form_post                              // `form_post' or 'fragment'
&scope=openid
&resource=https%3A%2F%2Fservice.contoso.com%2F        // The identifier of the protected resource (web API) that your application needs access to
&state=12345                                          // Any value, provided by your app
&nonce=678910                                         // Any value, provided by your app

İzin kapsamlarını isteğe ekleyerek ve response_type=code+id_tokenkullanarak authorize uç noktası, kullanıcının scope sorgu parametresinde belirtilen izinlere onay verdiğinden emin olmasını sağlar ve uygulamanıza erişim belirteci değişimi için bir yetkilendirme kodu döndürür.

Başarılı yanıt

redirect_urikullanılarak response_mode=form_post gönderilen başarılı bir yanıt şöyle görünür:

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNB...&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...&state=12345

Parametre	Açıklama
id_token	id_token olanı uygulamanın istediği. kullanıcının kimliğini doğrulamak ve kullanıcıyla oturum başlatmak için id_token kullanabilirsiniz.
kod	Uygulamanın istediği yetkilendirme kodu. Uygulama, yetkilendirme kodunu kullanarak hedef kaynak için erişim belirteci isteyebilir. Yetkilendirme kodları kısa sürelidir ve genellikle yaklaşık 10 dakika sonra süresi dolar.
devlet	İstekte bir durum parametresi varsa, yanıtta aynı değer görünmelidir. Uygulama, istek ve yanıttaki durum değerlerinin aynı olduğunu doğrulamalıdır.

Hata yanıtı

Hata yanıtları da redirect_uri’e gönderilerek uygulamanın bunları uygun şekilde işleyebilmesi için sağlanabilir.

POST /myapp/ HTTP/1.1
Host: localhost
Content-Type: application/x-www-form-urlencoded

error=access_denied&error_description=the+user+canceled+the+authentication

Parametre	Açıklama
hata	Oluşan hata türlerini sınıflandırmak için kullanılabilecek ve hatalara tepki vermek için kullanılabilen bir hata kodu dizesi.
hata açıklaması	Bir geliştiricinin kimlik doğrulama hatasının kök nedenini belirlemesine yardımcı olabilecek belirli bir hata iletisi.

Olası hata kodlarının ve önerilen istemci eyleminin açıklaması için bkz. yetkilendirme uç noktası hataları için hata kodları.

Yetkilendirme code ve id_tokenaldıktan sonra, kullanıcının oturumunu açabilir ve onun adına erişim belirteçleri alabilirsiniz. Kullanıcının oturumunu açmak için id_token yukarıda açıklandığı gibi doğrulamanız gerekir. Erişim belirteçlerini almak için, OAuth kod akışı belgelerimizin "Erişim belirteci istemek için yetkilendirme kodunu kullanma" bölümünde açıklanan adımları izleyebilirsiniz.

Sonraki adımlar

• erişim belirteçleri hakkında daha fazla bilgi edinin.
• id_token vetalepleri hakkında daha fazla bilgi edinin.