Aracılığıyla paylaş


Hızlı Başlangıç: Örnek bir daemon uygulamasında web API'sini çağırma

Şunlar için geçerlidir: Beyaz onay işareti simgesine sahip yeşil daire. İş gücü kiracıları Beyaz onay işareti simgesiyle yeşil daire. Dış kiracılar (daha fazla bilgi edinin)

Bu hızlı başlangıçta, Microsoft Authentication Library (MSAL)kullanarak erişim belirteci almak ve korumalı bir web API'sini çağırmak için örnek bir daemon uygulaması kullanacaksınız.

Başlamadan önce, kiracı türünü seçmek için bu sayfanın üst kısmındaki Kiracı türü seçici'yi kullanın. Microsoft Entra ID, iş gücü ve dışolmak üzere iki kiracı yapılandırması sağlar. İş gücü kiracı yapılandırması çalışanlarınıza, iç uygulamalarınıza ve diğer kuruluş kaynaklarınıza yöneliktir. Dış kiracı, müşteriye yönelik uygulamalarınız içindir.

Bu hızlı başlangıçta kullandığınız örnek uygulama, Microsoft Graph API'sini çağırmak için bir erişim belirteci alır.

Önkoşullar

  • Etkin aboneliği olan bir Azure hesabı. Henüz bir hesabınız yoksa ücretsiz hesap oluşturun.
  • Bu Azure hesabının uygulamaları yönetme izinleri olmalıdır. Aşağıdaki Microsoft Entra rollerinden herhangi biri gerekli izinleri içerir:
    • Uygulama Yöneticisi
    • Uygulama Geliştirici
    • Bulut Uygulaması Yöneticisi
  • Çalışan kiracı. Varsayılan Dizininizi kullanabilir veya yeni bir kiracı oluşturabilirsiniz.
  • 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
  • Uygulama kaydınıza bir istemci gizli anahtarı ekleyin. Üretim uygulamalarında istemci sırlarını kullanmayın. Bunun yerine sertifikaları veya federasyon kimlik bilgilerini kullanın. Daha fazla bilgi için bkz. Uygulamanıza kimlik bilgileri ekleme.

Daemon uygulamasına API izinleri verme

Daemon uygulamasının Microsoft Graph API'sindeki verilere erişmesi için gereken izinleri verirsiniz. Daemon uygulamasının uygulama türü izinleri gerekir. Kullanıcılar bir daemon uygulamasıyla etkileşim kuramaz, bu nedenle kiracı yöneticisinin bu izinleri onaylaması gerekir. İzinleri vermek ve onay vermek için aşağıdaki adımları kullanın:

.NET daemon uygulaması için herhangi bir izin vermeniz ve onay vermeniz gerekmez. Bu daemon uygulaması kendi uygulama kayıt bilgilerini okur, böylece uygulama izinleri verilmeden bunu yapabilir.

Örnek uygulamayı 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-docs-code-dotnet.git
  • .zip dosyasınıindirin. Adın uzunluğu 260 karakterden az olan bir dosya yoluna ayıklayın.

Projeyi yapılandırma

İstemci daemon uygulaması örneğinde uygulama kaydı ayrıntılarınızı kullanmak için aşağıdaki adımları kullanın:

  1. Bir konsol penceresi açın ve ms-identity-docs-code-dotnet/console-daemon dizinine gidin:

    cd ms-identity-docs-code-dotnet/console-daemon
    
  2. Program.cs açın ve dosya içeriğini aşağıdaki kod parçacığıyla değiştirin;

     // Full directory URL, in the form of https://login.microsoftonline.com/<tenant_id>
     Authority = " https://login.microsoftonline.com/Enter_the_tenant_ID_obtained_from_the_Microsoft_Entra_admin_center",
     // 'Enter the client ID obtained from the Microsoft Entra admin center
     ClientId = "Enter the client ID obtained from the Microsoft Entra admin center",
     // Client secret 'Value' (not its ID) from 'Client secrets' in the Microsoft Entra admin center
     ClientSecret = "Enter the client secret value obtained from the Microsoft Entra admin center",
     // Client 'Object ID' of app registration in Microsoft Entra admin center - this value is a GUID
     ClientObjectId = "Enter the client Object ID obtained from the Microsoft Entra admin center"
    
    • Authority - Yetkilendirme sunucusu, MSAL'nin token isteyebileceği bir dizini gösteren bir URL'dir. Microsoft_Entra_yönetici_merkezinden_alınan_kiracı_kimliğini_girin ifadesini, daha önce kaydedilmiş olan Dizin (kiracı) kimliği değeri ile değiştirin.
    • ClientId - İstemci olarak da adlandırılan uygulamanın tanımlayıcısı. Tırnak içindeki metni, kayıtlı uygulamanın genel bakış sayfasından daha önce kaydedilen Application (client) ID değeriyle değiştirin.
    • ClientSecret - Microsoft Entra yönetim merkezinde uygulama için oluşturulan istemci gizli anahtarı. İstemci gizli anahtarının değerini girin.
    • ClientObjectId - İstemci uygulamasının nesne kimliği. Tırnak içindeki metni, kayıtlı uygulamanın genel bakış sayfasında önceden kaydettiğiniz Object ID değeriyle değiştirin.

Uygulamayı çalıştırma ve test edin

Örnek uygulamanızı yapılandırdınız. Çalıştırmaya ve test etmeye devam edebilirsiniz.

Konsol pencerenizden aşağıdaki komutu çalıştırarak uygulamayı derleyin ve çalıştırın:

dotnet run

Uygulama başarıyla çalıştırıldıktan sonra aşağıdaki kod parçacığına benzer bir yanıt görüntüler (kısaltma için kısaltılır):

{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#applications/$entity",
"id": "00001111-aaaa-2222-bbbb-3333cccc4444",
"deletedDateTime": null,
"appId": "00001111-aaaa-2222-bbbb-3333cccc4444",
"applicationTemplateId": null,
"disabledByMicrosoftStatus": null,
"createdDateTime": "2021-01-17T15:30:55Z",
"displayName": "identity-dotnet-console-app",
"description": null,
"groupMembershipClaims": null,
...
}

Nasıl çalışır?

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 tür bir uygulama, uygulama kimliğini, kimlik bilgilerini (gizli dizi veya sertifika) ve uygulama kimliği URI'sini sunarak erişim belirteci istemek için kullanır. Daemon uygulaması, erişim belirteci almak için standart OAuth 2.0 istemci kimlik bilgileri verme akışı kullanır.

Uygulama, Microsoft kimlik platformundan bir erişim belirteci alır. Erişim belirtecinin kapsamı Microsoft Graph API'sine yöneliktir. Ardından uygulama, Microsoft Graph API'sinden kendi uygulama kayıt ayrıntılarını istemek için erişim belirtecini kullanır. Erişim belirtecinin doğru izinleri olduğu sürece uygulama Microsoft Graph API'sinden herhangi bir kaynak isteyebilir.

Örnek, katılımsız bir işin veya Windows hizmetinin kullanıcı kimliği yerine uygulama kimliğiyle nasıl çalışabileceğini gösterir.

Önkoşullar

İstemci gizli anahtarı oluşturma

Kayıtlı uygulama için bir istemci sırrı oluşturun. Uygulama, jeton talebinde bulunduğunda kimliğini kanıtlamak için istemci sırrını kullanır.

  1. Uygulama kayıtları sayfasından, oluşturduğunuz uygulamayı (örneğin web uygulaması istemci gizli anahtarı) seçin ve Genel Bakış sayfasını açın.
  2. Yönetaltında, Sertifikalar & gizli dizileri>İstemci gizlileri>Yeni istemci gizliseçin.
  3. Açıklama kutusuna, müşteri gizli anahtarı için bir açıklama girin (örneğin, web uygulaması müşteri gizli anahtarı).
  4. Süre sonualtında gizli dizinin geçerli olduğu süreyi seçin (kuruluşunuzun güvenlik kurallarına göre) ve ardından Ekleöğesini seçin.
  5. Gizli anahtarın Değerinikaydedin. Bu değeri sonraki bir adımda yapılandırma için kullanacaksınız. Sertifikalar ve gizli dizilersayfadan ayrıldıktan sonra gizli değer bir daha görüntülenmez ve hiçbir şekilde geri alınamaz. Kaydettiğinizden emin olun.

Gizli bir istemci uygulaması için kimlik bilgileri oluşturduğunuzda:

  • Microsoft, uygulamayı üretim ortamına taşımadan önce istemci gizli dizisi yerine sertifika kullanmanızı önerir. Sertifika kullanma hakkında daha fazla bilgi için Microsoft kimlik platformu uygulama kimlik doğrulama sertifikası kimlik bilgileriyönergelerine bakın.

  • Test amacıyla otomatik olarak imzalanan bir sertifika oluşturabilir ve uygulamalarınızı bu sertifikayla kimlik doğrulaması yapmak üzere yapılandırabilirsiniz. Ancak, üretim 'da, iyi bilinen bir sertifika yetkilisi tarafından imzalanan bir sertifika satın almalı ve ardından sertifika erişimini ve ömrünü yönetmek için Azure Key Vault kullanmalısınız.

Daemon uygulamasına API izinleri verme

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

  2. Yönetaltında API izinlerini seçin.

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

  4. API'lerini kullanan kuruluşumun sekmesini seç.

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

  6. Uygulama izinleri seçeneğini belirleyin. Uygulama kendi adıyla oturum açtığında ancak kullanıcı adına oturum açmadığı için bu seçeneği seçeriz.

  7. İzin listesinden TodoList.Read.All, ToDoList.ReadWrite.All 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. Önce kiracı adınız<>için yönetici onayı ver'iseçin, ardından Evet seçin.
    2. Yenile'yiseçin, ardından kiracı adınızın <için Verildi> her iki izin için Durum altında göründüğünü doğrulayın.

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ın kullanıcıları oturum açmadan ve doğrudan kendileri olarak kimlik doğrulaması yapabilmelerini sağlamak amacıyla 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önetsekmesinde 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 GörevListesi.Oku.Hepsi
    İzin verilen üye türleri Uygulamaları
    Değer GörevListesi.Oku.Hepsi
    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 belirteci olduğunda bu talebin değeri uygulama olur.

Ö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
    
  • Alternatif olarak, .zip dosyasınıindirin ve ardından 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

uygulama kayıt ayrıntılarınızı istemci web uygulaması örneğinde kullanmak için aşağıdaki adımları kullanın:

  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 daemon uygulamasının Uygulama (istemci) kimliğiyle değiştirin.

    • Enter_the_Tenant_Subdomain_Here dizin (kiracı) altalan adı ile değiştirin. Örneğin, eğer kiracı birincil etki alanınız contoso.onmicrosoft.comise, contoso'i kullanın. Kiracı adınızı bilmiyorsanız, kiracı ayrıntılarınızı nasıl okuyacağınızıöğrenin.

    • Enter_the_Client_Secret_Here ile daemon uygulamasının daha önce kopyaladığınız gizli anahtar değerini 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 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.

    • Enter_the_Tenant_Id_Here ve daha önce kopyaladığınız Dizin (kiracı) kimliğiyle değiştirin.

    • Enter_the_Tenant_Subdomain_Here dizin (kiracı) altalan adı ile değiştirin. Örneğin, eğer kiracı birincil etki alanınız contoso.onmicrosoft.comise, contoso'i kullanın. Kiracı adınızı bilmiyorsanız, kiracı ayrıntılarınızı nasıl okuyacağınızıöğrenin.

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

Örnek uygulamanızı yapılandırdınız. Çalıştırmaya ve test etmeye devam edebilirsiniz.

  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 akışı 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 açığa çıkardınız ve ardından daemon uygulamasınaverdiniz.

API tarafında, örnek bir .NET web API'sinde, API erişim belirtecinin gerekli izinlere (uygulama izinleri) sahip olduğunu doğrulamalıdır. Web API'si gerekli izinlere sahip olmayan bir erişim belirtecini kabul etmez.

Verilere erişim

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 kullanıcının yaptığı bir çağrı, kullanıcının veri to-do listesini alır. Öte yandan, uygulama izinleri/rolleri aracılığıyla bir uygulamadan yapılan çağrı to-do 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.