Aracılığıyla paylaş

Örnek bir Node.js daemon uygulamasında API çağırma

  • Makale

Bu kılavuz, bir daemon uygulamasının web API'sini çağırmak için nasıl belirteç aldığını göstermek için örnek bir Node.js daemon uygulaması kullanır. Microsoft Entra, Web API'sini korur.

Bir daemon uygulaması kendisi adına bir belirteç alır (kullanıcı adına değil). Kullanıcılar kendi kimliğini gerektirdiğinden bir daemon uygulamasıyla etkileşim kuramaz. Bu uygulama türü, uygulama kimliğini kullanarak ve uygulama kimliğini, kimlik bilgilerini (parola veya sertifika) ve uygulama kimliği URI'sini Dış Kimliğe sunarak erişim belirteci ister.

Bir daemon uygulaması standart OAuth 2.0 istemci kimlik bilgileri verme işlevini kullanır. Belirteci alma işlemini basitleştirmek için bu makalede kullandığımız örnekte Düğüm için Microsoft Kimlik Doğrulama Kitaplığı (MSAL Düğümü) kullanılmaktadır.

Önkoşullar

Daemon uygulaması ve web API'si kaydetme

Bu adımda, daemon ve web API 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 simgesinikullanı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.

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.

Daemon uygulamasını kaydetme

Uygulamanızın Microsoft Entra ile kullanıcılarla oturum açmasını sağlamak için Microsoft Entra Dış Kimlik oluşturduğunuz uygulama hakkında bilgi edinilmesi gerekir. Uygulama kaydı, uygulama ile Microsoft Entra arasında bir güven ilişkisi kurar. Bir uygulamayı kaydettiğinizde, Dış Kimlik, kimlik doğrulama istekleri oluştururken uygulamanızı tanımlamak için kullanılan bir değer olan Uygulama (istemci) kimliği olarak bilinen benzersiz bir tanımlayıcı oluşturur.

Aşağıdaki adımlar, uygulamanızı Microsoft Entra yönetim merkezine nasıl kaydedeceğini gösterir:

  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 simgesinikullanı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;

    1. Uygulamanın kullanıcılarına gösterilen anlamlı bir uygulama Adı girin, örneğin ciam-client-app.
    2. Desteklenen hesap türleri'nin altında Yalnızca bu kuruluş dizinindeki Hesaplar'ı seçin.

  6. Kaydet'i seçin.

  7. Başarılı bir kayıtta uygulamanın Genel Bakış bölmesi görüntülenir. Uygulama kaynak kodunuzda kullanılacak Uygulama (istemci) kimliğini kaydedin.

İstemci gizli dizisi oluşturma

Kayıtlı uygulama için bir istemci gizli dizisi oluşturun. Uygulama, belirteç istediğinde kimliğini kanıtlamak için istemci gizli dizisini kullanır.

  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 Sertifikalar ve gizli diziler'i seçin.
  3. Yeni gizli anahtar'ı seçin.
  4. Açıklama kutusuna istemci gizli dizisi için bir açıklama girin (örneğin, ciam uygulama istemci gizli dizisi).
  5. Süre Sonu'nun altında gizli dizinin geçerli olduğu bir süre seçin (kuruluşunuzun güvenlik kurallarına göre) ve ardından Ekle'yi seçin.
  6. Gizli dizinin Değerini kaydedin. Bu değeri sonraki bir adımda yapılandırma için kullanacaksınız. Gizli dizi değeri yeniden görüntülenmez ve Sertifikalar ve gizli dizilerden uzaklaştıktan sonra herhangi bir yolla alınamaz. Kaydettiğinizden emin olun.

Daemon uygulamasına API izinleri verme

  1. Uygulama kayıtları sayfasında, oluşturduğunuz uygulamayı (ciam-client-app gibi) seçin.

  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. Uygulama izinleri seçeneğini belirleyin. Bu seçeneği, uygulama kullanıcı olarak değil, kendisi olarak oturum açtığında seçeriz.

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

  8. İzin ekle düğmesini seçin.

  9. Bu noktada izinleri doğru atamış olursunuz. Ancak, daemon uygulaması kullanıcıların bu uygulamayla etkileşim kurmasına izin vermediğinden, 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 Kiracı adınız> için <Verildi seçeneğinin her iki izin için de Durum altında göründüğünü doğrulayın.

Örnek daemon uygulamasını 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 örnek uygulamasını içeren dizine geçin:

    cd 2-Authorization\3-call-api-node-daemon\App

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

    npm install && npm update

Örnek daemon uygulamasını ve API'sini 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 daemon uygulamasını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 daha önce kopyaladığınız daemon 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 daemon 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\3-call-api-node-daemon\API\ToDoListAPI
dotnet run

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

    2-Authorization\3-call-api-node-daemon\App
node . --op getToDos

  • Daemon uygulamanız ve web API'niz başarıyla çalıştırılırsa konsol pencerenizde aşağıdaki JSON dizisine benzer bir şey görmeniz gerekir

    {
    "id": 1,
    "owner": "3e8....-db63-43a2-a767-5d7db...",
    "description": "Pick up grocery"
},
{
    "id": 2,
    "owner": "c3cc....-c4ec-4531-a197-cb919ed.....",
    "description": "Finish invoice report"
},
{
    "id": 3,
    "owner": "a35e....-3b8a-4632-8c4f-ffb840d.....",
    "description": "Water plants"
}

Nasıl çalışır?

Node.js uygulaması, kullanıcı için değil kendisine erişim belirteci almak için OAuth 2.0 istemci kimlik bilgileri verme işlevini kullanır. Uygulamanın istediği erişim belirteci, rol olarak temsil edilen izinleri içerir. İstemci kimlik bilgisi akışı, uygulama belirteçleri için kullanıcı kapsamları yerine bu izin kümesini kullanır. Bu uygulama izinlerini daha önce web API'sinde kullanıma seçip daemon uygulamasına vermişsinizdir.

API tarafında, web API'sinin erişim belirtecinin gerekli izinlere (uygulama izinleri) sahip olduğunu doğrulaması gerekir. Web API'si gerekli izinlere sahip olmayan bir erişim belirtecini kabul etmez.

Veri erişimi

Web API'si uç noktası, hem kullanıcılardan hem de uygulamalardan gelen çağrıları kabul etmeye hazır olmalıdır. Bu nedenle, her isteğe uygun olarak yanıt vermenin bir yolu olmalıdır. Örneğin, temsilci izinleri/kapsamları aracılığıyla bir kullanıcıdan yapılan bir çağrı kullanıcının veri yapılacaklar listesini alır. Öte yandan, uygulama izinleri/rolleri aracılığıyla bir uygulamadan yapılan çağrı yapılacaklar listesinin tamamını alabilir. Ancak bu makalede yalnızca bir uygulama çağrısı yapıyoruz, bu nedenle temsilci izinlerini/kapsamlarını yapılandırmamız gerekmiyordu.

İlgili içerik