Örnek Node.js web uygulamasında kullanıcılarda oturum açma ve web API'lerini çağırma

Bu kılavuz, bir Node.js web uygulamasında kimlik doğrulaması ve yetkilendirme eklemeyi gösteren bir kod örneği kullanır. Örnek uygulama, kullanıcıları bir Node.js web uygulamasında oturum açar ve ardından .NET API'sini çağırır. Dış kiracı ayrıntılarınızı kullanarak kimlik doğrulamasını ve yetkilendirmeyi etkinleştirirsiniz. Örnek web uygulaması, kimlik doğrulamasını işlemek için Node için Microsoft Kimlik Doğrulama Kitaplığı'nı (MSAL) kullanır.

Bu makalede aşağıdaki görevleri tamamlaacaksınız:

• Microsoft Entra yönetim merkezinde bir web API'sini kaydedin ve yapılandırın.

• Dış kiracı ayrıntılarınızı kullanmak için örnek bir Node web uygulamasını güncelleştirin ve web API'sini ASP.NET.

• Örnek web uygulamasını ve API'yi çalıştırın ve test edin.

Önkoşullar

• Örnek Node.js web uygulaması makalesinde Kullanıcıları oturum açma ve API çağırma makalesindeki adımları tamamlayın. Bu makalede, örnek bir Node.js web uygulaması kullanarak kullanıcıların nasıl oturum açabileceğiniz gösterilmektedir.
• Visual Studio Code veya başka bir kod düzenleyicisi.
• Node.js.
• .NET 7.0 veya üzeri.
• Dış kiracı. Oluşturmak için aşağıdaki yöntemlerden birini seçin:
  • (Önerilen) Doğrudan Visual Studio Code'da dış kiracı ayarlamak için Microsoft Entra Dış Kimlik uzantısını kullanın.
  • Microsoft Entra yönetim merkezinde yeni bir dış kiracı oluşturun.

Web API’si kaydetme

Bu adımda web ve web API'sinin uygulama kayıtlarını oluşturur ve web API'nizin kapsamlarını belirtirsiniz.

Web API'si uygulaması kaydetme

1. Microsoft Entra yönetim merkezinde en azından Uygulama Geliştiricisi olarak oturum açın.

2. Birden çok kiracıya erişiminiz varsa, Dizinler + abonelikler menüsünden dış kiracınıza geçmek için üst menüdeki Ayarlar simgesini kullanın.

3. Kimlik>Uygulamaları'na> göz atın Uygulama kayıtları.

4. + Yeni kayıt'ı seçin.

5. Görüntülenen Uygulamayı kaydet sayfasında, uygulamanızın kayıt bilgilerini girin:

   1. Ad bölümünde, uygulamanın kullanıcılarına görüntülenecek anlamlı bir uygulama adı girin, örneğin ciam-ToDoList-api.

   2. Desteklenen hesap türleri'nin altında Yalnızca bu kuruluş dizinindeki Hesaplar'ı seçin.

6. Uygulamayı kaydetmek için Kaydet'i seçin.

7. Kayıt tamamlandığında uygulamanın Genel Bakış bölmesi görüntülenir. Uygulama kaynak kodunuzda kullanılacak Dizin (kiracı) kimliğini ve Uygulama (istemci) kimliğini kaydedin.

API kapsamlarını yapılandırma

Bu API'nin, bir istemcinin API'yi çağırmak için alması gereken izinleri kullanıma sunması gerekir:

İstemci uygulamalarının bir kullanıcı için erişim belirtecini başarıyla alabilmesi için api'nin Temsilci İzni olarak da adlandırılan en az bir kapsam yayımlaması gerekir. Kapsam yayımlamak 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önet'in altında API'yi kullanıma sunma'yı seçin.

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

4. gibi api://{clientId}önerilen Uygulama Kimliği URI'sini kabul edin ve Kaydet'i 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ımlanan kapsamlar'ın altında Kapsam ekle'yi seçin.

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

   Özellik	Değer
   Kapsam adı	ToDoList.Read
   Kimler onaylayabilir	Yalnızca yöneticiler
   Yönetici onayı görünen adı	'TodoListApi' kullanarak kullanıcıların ToDo listesini okuma
   Yönetici onayı açıklaması	Uygulamanın 'TodoListApi' kullanarak kullanıcının ToDo listesini okumasına izin verin.
   State	Etkin

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

   Özellik	Değer
   Kapsam adı	ToDoList.ReadWrite
   Kimler onaylayabilir	Yalnızca yöneticiler
   Yönetici onayı görünen adı	'ToDoListApi' kullanarak kullanıcıların ToDo listesini okuma ve yazma
   Yönetici onayı açıklaması	Uygulamanın 'ToDoListApi' kullanarak kullanıcının ToDo listesini okumasına ve yazmasına izin ver
   State	Etkin

8. Yönet'in altında Bildirim'i seçerek API bildirim düzenleyicisini açın.

9. özelliğini olarak 2ayarlayınaccessTokenAcceptedVersion.

10. Kaydet'i seçin.

Web API'sinin izinlerini 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 alabilmesi için uygulamalar için Uygulama İzni olarak da adlandırılan en az bir uygulama rolü yayımlaması gerekir. Uygulama izinleri, istemci uygulamalarının kendi kimliklerini başarıyla doğrulayıp oturum açması gerekmediğinde 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 gibi) seçerek Genel Bakış sayfasını açın.

2. Yönet'in altında Uygulama rolleri'ne tıklayın.

3. Uygulama rolü oluştur'u seçin, ardından aşağıdaki değerleri girin ve ardından Uygula'yı seçerek değişikliklerinizi kaydedin:

   Özellik	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

4. Uygulama rolü oluştur'u 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'yı seçin:

   Özellik	Değer
   Görünen ad	ToDoList.ReadWrite.All
   İzin verilen üye türleri	Uygulamalar
   Değer	ToDoList.ReadWrite.All
   Açıklama	Uygulamanın 'ToDoListApi' kullanarak her kullanıcının ToDo listesini okumasına ve yazmasına izin ver

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

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

Erişim belirtecine idtyp talebi eklemek için İsteğe bağlı talepleri yapılandırma makalesindeki adımları kullanın:

• Belirteç türü için Access'i seçin.
• İsteğe bağlı talepler listesinden idtyp'yi 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 gibi) seçerek Genel Bakış sayfasını açın.

2. Yönet'in altında API izinleri'ne tıklayın.

3. Yapılandırılan izinler'in altında İzin ekle'yi seçin.

4. Kuruluşumun kullandığı API'ler sekmesini seçin.

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

6. Temsilci izinleri seçeneğini belirleyin.

7. İzinler listesinden ToDoList.Read, ToDoList.ReadWrite öğesini 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. Kiracı adınız> için <Yönetici onayı ver'i ve ardından Evet'i seçin.

   2. Yenile'yi seçin, ardından her iki kapsam için de Durum altında Kiracı adınız> için <Verildi ifadesinin gösterildiğini doğrulayın.

9. Yapılandırılan izinler listesinden ToDoList.Read ve ToDoList.ReadWrite izinlerini birer birer seçin ve daha sonra kullanmak üzere iznin tam URI'sini kopyalayın. Tam izin URI'si veya api://{clientId}/{ToDoList.ReadWrite}gibi api://{clientId}/{ToDoList.Read} görünür.

Ö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. 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 dosyayı açın App\authConfig.js .

2. Yer tutucuyu bulun:

   • Enter_the_Application_Id_Here ve daha önce kaydettiğiniz uygulamanın Uygulama (istemci) kimliğiyle değiştirin.
   • Enter_the_Tenant_Subdomain_Here ve bunu Dizin (kiracı) alt etki alanıyla değiştirin. Örneğin, kiracı birincil etki alanınız ise contoso.onmicrosoft.comkullanın contoso. Kiracı adınız yoksa kiracınızın ayrıntılarını nasıl okuyacağınızı öğrenin.
   • Enter_the_Client_Secret_Here ve değerini daha önce kopyaladığınız uygulama gizli dizisi değeriyle değiştirin.
   • Enter_the_Web_Api_Application_Id_Here ve 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 dosyayı açın API\ToDoListAPI\appsettings.json .

2. Yer tutucuyu bulun:

   • Enter_the_Application_Id_Here ve bunu kopyaladığınız web API'sinin Uygulama (istemci) kimliğiyle değiştirin.
   • Enter_the_Tenant_Id_Here ve daha önce kopyaladığınız Dizin (kiracı) kimliğiyle değiştirin.
   • Enter_the_Tenant_Subdomain_Here ve bunu Dizin (kiracı) alt etki alanıyla değiştirin. Örneğin, kiracı birincil etki alanınız ise contoso.onmicrosoft.comkullanın contoso. Kiracı adınız yoksa kiracınızın ayrıntılarını 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 start
   

3. Tarayıcınızı açın ve http://localhost:3000.

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

   

5. Oturum açma sayfasında, E-posta adresinizi yazın, İleri'yi seçin, Parolanızı yazın ve ardından Oturum aç'ı seçin. Hesabınız yoksa Hesap yok mu? seçeneğini belirleyin . Kayıt akışını başlatan bir bağlantı oluşturun.

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’yi çağırma

1. API'yi çağırmak için Yapılacaklar listenizi 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 yapılacaklar 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 izin/kapsam içeren ToDoList.Read 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 bir 401 Unauthorized HTTP hatasıyla yanıt verir.

İlgili içerik

• Kullanıcılarda oturum açın ve kendi Node.js web uygulamanızda bir API'yi çağırun.
• Parola sıfırlamayı etkinleştirin.
• Varsayılan markayı özelleştirin.
• Google ile oturum açmayı yapılandırın.