Hızlı Başlangıç - Örnek Node.js web uygulamasında kullanıcılarda oturum açma ve web API'sini çağırma

Şunun için geçerlidir: Dış kiracılar (daha fazla bilgi edinin)

Bu Hızlı Başlangıçta, dış kiracınızdaki bir Node.js web uygulamasından kullanıcılarda oturum açmayı ve web API'sini çağırmayı öğreneceksiniz. Örnek uygulama bir .NET API'sini çağırır. Örnek web uygulaması, kimlik doğrulamasını işlemek için Node için Microsoft Kimlik Doğrulama Kitaplığı (MSAL) kullanır.

Önkoşullar

• Hızlı Başlangıç: Örnek bir web uygulamasında kullanıcıların oturum açmasını sağlamak için makalesindeki adımları ve önkoşulları tamamlayın. Bu makalede, örnek bir Node.js web uygulaması kullanarak kullanıcıların nasıl oturum açabileceğiniz gösterilmektedir.
• Dış kiracı. Oluşturmak için aşağıdaki yöntemlerden birini seçin:
  • (Önerilen) Visual Studio Code'da doğrudan bir dış kiracı oluşturmak için Microsoft Entra Dış Kimlik uzantısını kullanın.
  • Microsoft Entra yönetim merkezinde Yeni bir dış kiracı oluşturun.
• Web API'niz için Microsoft Entra yönetim merkezine, yalnızca bu kuruluş dizinindeki Hesaplar için yapılandırılmış yeni bir uygulama kaydedin. Daha fazla bilgi için Bir uygulamayı kaydetme bölümüne bakın. Daha sonra kullanmak üzere uygulamaya Genel Bakış sayfasından aşağıdaki değerleri kaydedin:
  • Uygulama (istemci) kimliği
  • Dizin (kullanıcı) kimliği
• Visual Studio Code veya başka bir kod düzenleyicisi.
• Node.js.
• .NET 7.0 veya sonraki .

API kapsamlarını ve rollerini yapılandırma

Web API'sini kaydederek, bir istemci uygulamasının web API'sine erişmek için isteyebileceği izinleri tanımlamak için API kapsamlarını yapılandırmanız gerekir. Ayrıca, kullanıcıların veya uygulamaların kullanabileceği rolleri belirtmek için uygulama rolleri ayarlamanız ve web api'sini çağırmasını sağlamak için web uygulamasına gerekli API izinlerini vermeniz gerekir.

API kapsamlarını yapılandırma

İstemci uygulamalarının kullanıcı için erişim belirtecini başarıyla alabilmesi için api'nin Temsilci İzinolarak da adlandırılan en az bir kapsam yayımlaması gerekir. Kapsamı yayınlamak için şu adımları izleyin:

1. Uygulama kayıtları sayfasında, oluşturduğunuz API uygulamasını (ciam-ToDoList-api) seçerek Genel Bakış sayfasını açın.

2. Yönetaltında API'yi kullanıma sunmayıseçin.

3. Sayfanın üst kısmında, Uygulama Kimliği URI'siyanındaki Ekle bağlantısını seçerek bu uygulama için benzersiz bir URI oluşturun.

4. Önerilen Uygulama Kimliği URI'sini api://{clientId}olarak kabul edin ve Kaydetöğesini seçin. Web uygulamanız web API'si için bir erişim belirteci istediğinde, API için tanımladığınız her kapsam için ön ek olarak URI'yi ekler.

5. Bu API tarafından tanımlananKapsamlar altında Kapsam ekleöğesini seçin.

6. API'ye okuma erişimi tanımlayan aşağıdaki değerleri girin, ardından değişikliklerinizi kaydetmek için Kapsam ekle seçin:

   Mülk	Değer
   Kapsam adı	YapılacaklarListesi.Oku
   Kim onay verebilir?	Yalnızca Yöneticiler
   Yönetici onayı görüntüleme adı	'TodoListApi' kullanarak kullanıcıların ToDo listesini okuma
   Yönetici onayı açıklaması	'TodoListApi'kullanarak uygulamanın kullanıcının ToDo listesini okumasına izin verin.
   Devlet	Etkinleştirilmiş

7. Kapsam ekle'yi yeniden seçin ve API'ye okuma ve yazma erişim kapsamı tanımlayan aşağıdaki değerleri girin. "Kapsam ekle'yi seçin, değişikliklerinizi kaydedin."

   Mülk	Değer
   Kapsam adı	ToDoList.ReadWrite
   Kim onay verebilir?	Yalnızca Yöneticiler
   Yönetici onayı görüntüleme adı	Kullanıcıların 'ToDoListApi' kullanarak Yapılacaklar listesini okuma ve yazma
   Yönetici onayı açıklaması	'ToDoListApi' kullanarak uygulamanın kullanıcının ToDo listesini okumasına ve yazmasına izin ver
   Devlet	Etkinleştirilmiş

Web API'sine yönelik izinler yayımlarken en az ayrıcalık ilkesi hakkında daha fazla bilgi edinin.

Uygulama rollerini yapılandırma

bir API'nin, istemci uygulamalarının kendileri gibi bir erişim belirteci elde etmesi için uygulamalar için uygulama izni olarak da adlandırılan en az bir uygulama rolü yayımlaması gerekir. Uygulama izinleri, istemci uygulamaların kendi kimlikleriyle başarılı bir şekilde doğrulanabilmesi ve kullanıcı oturumu açmalarına gerek kalmaması için API'lerin yayımlaması gereken izin türüdür. Uygulama izni yayımlamak için şu adımları izleyin:

1. Uygulama kayıtları sayfasında, oluşturduğunuz uygulamayı (ciam-ToDoList-api) seçerek Genel Bakış sayfasını açın.

2. Yönetaltında Uygulama rolleriseçin.

3. uygulama rolü oluşturseçin, ardından aşağıdaki değerleri girin ve değişikliklerinizi kaydetmek için uygula seçin:

   Mülk	Değer
   Görünen ad	ToDoList.Read.All
   İzin verilen üye türleri	Uygulamaları
   Değer	ToDoList.Read.All
   Açıklama	Uygulamanın 'TodoListApi' kullanarak her kullanıcının ToDo listesini okumasına izin ver
   Bu uygulama rolünü etkinleştirmek istiyor musunuz?	İşaretli tutun

4. Uygulama rolü oluştur yeniden seçin, ardından ikinci uygulama rolü için aşağıdaki değerleri girin ve ardından değişikliklerinizi kaydetmek için uygula seçin:

   Mülk	Değer
   Görünen ad	ToDoList.ReadWrite.All
   İzin verilen üye türleri	Uygulamaları
   Değer	ToDoList.ReadWrite.All
   Açıklama	'ToDoListApi' kullanarak uygulamanın her kullanıcının ToDo listesini okumasına ve yazmasına izin ver
   Bu uygulama rolünü etkinleştirmek istiyor musunuz?	İşaretli tutun

İsteğe bağlı talepleri yapılandırma

Web API'sinin bir uygulama belirteci mi yoksa uygulama + kullanıcı belirteci mi olduğunu belirlemesine yardımcı olmak için idtyp isteğe bağlı talebi ekleyebilirsiniz. Aynı amaçla scp ve rolleri taleplerin birleşimini kullanabilirsiniz ancak idtyp talebi, uygulama belirteci ile uygulama + kullanıcı belirtecini birbirinden ayırt etmenin en kolay yoludur. Örneğin, belirteç yalnızca uygulama için olan bir belirteç olduğunda, bu talebin değeri uygulama olur.

erişim jetonuna idtyp talebini eklemek için İsteğe bağlı talepleri yapılandırma makalesindeki adımları kullanın.

• Belirteci Türü içinErişim seçin.
• İsteğe bağlı talepler listesinden idtypöğesini seçin.

Web uygulamasına API izinleri verme

İstemci uygulamanıza (ciam-client-app) API izinleri vermek için şu adımları izleyin:

1. Uygulama kayıtları sayfasında, oluşturduğunuz uygulamayı (ciam-client-app) seçerek Genel Bakış sayfasını açın.

2. Önce Yönetaltında, API izinleriniseçin.

3. Yapılandırılmış izinleraltında İzinekle'yi seçin.

4. Kuruluşumun kullandığı API'lerini seçmek için sekmesine tıklayın.

5. API'ler listesinde ciam-ToDoList-apigibi API'yi seçin.

6. Temsilci izinleri seçeneğini seç.

7. İzinler listesinden ToDoList.Read, ToDoList.ReadWrite seçin (gerekirse arama kutusunu kullanın).

8. İzin ekle düğmesini seçin. Bu noktada izinleri doğru atamış olursunuz. Ancak, kiracı bir müşterinin kiracısı olduğundan, tüketici kullanıcıları bu izinlere onay veremez. Bu sorunu çözmek için, yönetici olarak kiracıdaki tüm kullanıcılar adına bu izinleri onaylamanız gerekir:

   1. Kullanıcınız için yönetici onayını ver ve ardından Evet seçin.

   2. Yenile'yi seçin, ardından < altında her iki kapsam için kiracı adınız> için verilen ibaresinin göründüğünü doğrulayın.

9. Yapılandırılmış izinler listesinden ToDoList.Read ve ToDoList.ReadWrite izinlerini birer birer seçin ve ardından daha sonra kullanmak üzere iznin tam URI'sini kopyalayın. Tam izin URI'si, api://{clientId}/{ToDoList.Read} veya api://{clientId}/{ToDoList.ReadWrite}benzer bir görünüme sahiptir.

Örnek web uygulaması ve web API'sini kopyalama veya indirme

Örnek uygulamayı edinmek için GitHub'dan kopyalayabilir veya .zip dosyası olarak indirebilirsiniz.

• Örneği kopyalamak için bir komut istemi açın ve projeyi oluşturmak istediğiniz yere gidin ve aşağıdaki komutu girin:

  git clone https://github.com/Azure-Samples/ms-identity-ciam-javascript-tutorial.git
  

• .zip dosyasınıindirin. Onu, adın uzunluğu 260 karakterden az olan bir dosya yoluna ayıklayın.

Proje bağımlılıklarını yükleme

1. Bir konsol penceresi açın ve Node.js/Express örnek uygulamasını içeren dizine geçin:

   cd 2-Authorization\4-call-api-express\App
   

2. Web uygulaması bağımlılıklarını yüklemek için aşağıdaki komutları çalıştırın:

   npm install && npm update
   

Örnek web uygulamasını ve API'yi yapılandırma

İstemci web uygulaması örneğinde uygulama kaydınızı kullanmak için:

1. Kod düzenleyicinizde App\authConfig.js dosyasını açın.

2. Yer tutucuyu bulun:

   • Enter_the_Application_Id_Here ve daha önce kaydettiğiniz istemci uygulamasının Uygulama (istemci) ID'siyle değiştirin. İstemci uygulaması, önkoşullarda kaydettiğiniz söz konusu uygulamadır.
   • Enter_the_Tenant_Subdomain_Here ile dizin (kiracı) alt etki alanını değiştirin. Örneğin, kiracınızın birincil alan adı contoso.onmicrosoft.comise, contosokullanın. Kiracı adınızı bilmiyorsanız, kiracı ayrıntılarınızı nasıl okuyacağınızı öğrenin.
   • Enter_the_Client_Secret_Here ve daha önce kopyaladığınız uygulama gizli değeriyle değiştirin.
   • Enter_the_Web_Api_Application_Id_Here ve bunu önkoşulların bir parçası olarak daha önce kopyaladığınız web API'sinin Uygulama (istemci) kimliğiyle değiştirin.

Web API örneğinde uygulama kaydınızı kullanmak için:

1. Kod düzenleyicinizde API\ToDoListAPI\appsettings.json dosyasını açın.

2. Yer tutucuyu bulun:

   • Enter_the_Application_Id_Here ve kopyaladığınız web API'sinin Uygulama (istemci) kimliğiyle değiştirin. Önkoşulların bir parçası olarak daha önce kaydettiğiniz Web API uygulaması.
   • Enter_the_Tenant_Id_Here'ı daha önce kopyaladığınız Dizin (kiracı) kimliğiyle değiştirin.
   • Enter_the_Tenant_Subdomain_Here ile dizin (kiracı) alt etki alanını değiştirin. Örneğin, kiracınızın birincil alan adı contoso.onmicrosoft.comise, contosokullanın. Kiracı adınızı bilmiyorsanız, kiracı ayrıntılarınızı nasıl okuyacağınızı öğrenin.

Örnek web uygulamasını ve API'sini çalıştırma ve test edin

1. Bir konsol penceresi açın ve aşağıdaki komutları kullanarak web API'sini çalıştırın:

   cd 2-Authorization\4-call-api-express\API\ToDoListAPI
   dotnet run
   

2. Aşağıdaki komutları kullanarak web uygulaması istemcisini çalıştırın:

   cd 2-Authorization\4-call-api-express\App
   npm install
   npm start
   

3. Tarayıcınızı açın, ardından http://localhost:3000. adresine gidin.

4. Oturum Aç düğmesini seçin. Oturum açmanız istenir.

   

5. Oturum açma sayfasında, E-posta adresiniziyazın, İleri seçin, Parolayazın ve Oturum açöğesini seçin. tr-TR: Hesabınız yoksa Hesap yok mu? Bir tane oluşturun bağlantısını seçin, böylece kayıt süreci başlar.

6. Kaydolma seçeneğini belirlerseniz, e-postanızı, tek seferlik geçiş kodunu, yeni parolayı ve diğer hesap ayrıntılarını doldurduktan sonra tüm kayıt akışını tamamlarsınız. Aşağıdaki ekran görüntüsüne benzer bir sayfa görürsünüz. Oturum açma seçeneğini belirlerseniz benzer bir sayfa görürsünüz.

   

API Çağır

1. API'yi çağırmak için Todolist'inizi görüntüleyin bağlantısını seçin. Aşağıdaki ekran görüntüsüne benzer bir sayfa görürsünüz.

   

2. Öğeleri oluşturup kaldırarak to-do listesini işleyin.

Nasıl çalışır?

Bir görevi her görüntülediğinizde, eklediğinizde veya kaldırdığınızda bir API çağrısı tetiklersiniz. Bir API çağrısını her tetiklediğinizde, istemci web uygulaması bir API uç noktasını çağırmak için gerekli izinlere (kapsamlara) sahip bir erişim belirteci alır. Örneğin, bir görevi okumak için istemci web uygulamasının ToDoList.Read iznine/kapsamına sahip bir erişim belirteci alması gerekir.

Web API'sinin uç noktasının, istemci uygulaması tarafından sağlanan erişim belirtecindeki izinlerin veya kapsamların geçerli olup olmadığını denetlemesi gerekir. Erişim belirteci geçerliyse uç nokta HTTP isteğine yanıt verir, aksi takdirde 401 Unauthorized bir HTTP hatasıyla yanıt verir.

İlgili içerik

• Öğretici: Dış Kiracıda Kayıtlı Bir ASP.NET Core Web API'sini Güvence Altına Alma.