MSAL.NET kullanarak istemci uygulamalarını başlatma

Bu makalede, .NET (MSAL.NET) için Microsoft Authentication Library kullanarak genel istemci ve gizli istemci uygulamalarını başlatma işlemi açıklanmaktadır. İstemci uygulama türleri hakkında daha fazla bilgi edinmek için bkz. Genel istemci ve gizli istemci uygulamaları.

MSAL.NET 3.x ile, bir uygulamanın örneğini oluşturmanın önerilen yolu uygulama oluşturucularını kullanmaktır: PublicClientApplicationBuilder ve ConfidentialClientApplicationBuilder. Uygulamayı koddan, yapılandırma dosyasından ve hatta her iki yaklaşımı da karıştırarak yapılandırmak için güçlü bir mekanizma sunar.

Prerequisites

Bir uygulamayı başlatmadan önce, uygulamanızın Microsoft kimlik platformu ile tümleştirilebilmesi için önce uygulamanızı kaydetmeniz gerekir. Daha fazla bilgi için Hızlı Başlangıç: Uygulamayı Microsoft kimlik platformu kaydetme bölümüne bakın. Kayıt işleminden sonra, Microsoft Entra yönetim merkezi uygulama kaydı sayfasında bulunabilecek aşağıdaki bilgilere ihtiyacınız olacaktır.

Uygulama (istemci) kimliği - Bu, GUID'yi temsil eden bir dizedir.
Dizin (kiracı) kimliği - Kuruluşunuz tarafından kullanılan uygulamalara ve kaynaklara kimlik ve erişim yönetimi (IAM) özellikleri sağlar. Yalnızca kuruluşunuz için bir iş uygulaması (tek kiracılı uygulama olarak da adlandırılır) yazıp yazmadığınızı belirtebilir.
Kimlik sağlayıcısı URL'si ( örnek olarak adlandırılır) ve uygulamanızın oturum açma hedef kitlesi. Bu iki parametre birlikte otorite olarak adlandırılır.
İstemci kimlik bilgileri - gizli istemci uygulaması olması durumunda, uygulama gizli anahtarı (istemci gizli dizesi) veya X509Certificate2 türünde bir sertifika biçiminde olabilir.
Web uygulamaları ve bazen genel istemci uygulamaları için (özellikle uygulamanızın bir aracı kullanması gerektiğinde), kimlik sağlayıcısının güvenlik belirteçleriyle uygulamanıza geri başvuracağı Yeniden Yönlendirme URI'sini ayarlamanız gerekir.

Uygulamaları başlatma

İstemci uygulamalarının örneğini oluşturmanın birçok farklı yolu vardır.

Ortak istemci uygulamasını koddan başlatma

Aşağıdaki kod, kullanıcıların iş, okul veya kişisel Microsoft hesaplarıyla Microsoft Azure genel bulutunda oturum açmasını sağlayan bir genel istemci uygulamasının örneğini oluşturur.

IPublicClientApplication app = PublicClientApplicationBuilder.Create(clientId)
    .Build();

Gizli istemci uygulamasını koddan başlatma

Aynı şekilde, aşağıdaki kod, Microsoft Azure genel bulutunda iş ve okul hesaplarını veya kişisel Microsoft hesaplarını kullanan kullanıcıların belirteçlerini işleyen gizli bir uygulamanın (https://myapp.azurewebsites.net konumunda bulunan bir web uygulaması) örneğini oluşturur. Uygulama, istemci gizli dizisini paylaşarak kimlik sağlayıcısı nezdinde tanımlanır:

string redirectUri = "https://myapp.azurewebsites.net";
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithClientSecret(clientSecret)
    .WithRedirectUri(redirectUri )
    .Build();

Ancak üretim ortamında, sertifikalar istemci gizli anahtarlarından daha güvenli oldukları için önerilir. Bunlar oluşturulabilir ve Microsoft Entra yönetim merkezi yüklenebilir. Kod aşağıdaki gibi olacaktır:

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(clientId)
    .WithCertificate(certificate)
    .WithRedirectUri(redirectUri )
    .Build();

Genel istemci uygulamasını yapılandırma seçeneklerinden başlatma

Aşağıdaki kod, program aracılığıyla doldurulabilen veya bir yapılandırma dosyasından okunabilen bir yapılandırma nesnesinden genel istemci uygulamasının örneğini oluşturur:

PublicClientApplicationOptions options = GetOptions(); // your own method
IPublicClientApplication app = PublicClientApplicationBuilder.CreateWithApplicationOptions(options)
    .Build();

Yapılandırma seçeneklerinden gizli bir istemci uygulaması başlatma

Gizli istemci uygulamaları için de aynı tür desen geçerlidir. Değiştiricileri kullanarak .WithXXX başka parametreler de ekleyebilirsiniz. Bu örnekte .WithCertificate kullanılmıştır.

ConfidentialClientApplicationOptions options = GetOptions(); // your own method
IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.CreateWithApplicationOptions(options)
    .WithCertificate(certificate)
    .Build();

Oluşturucu değiştiricileri

Uygulama oluşturucuları kullanan kod parçacıklarında, birçok .With yöntem değiştirici olarak uygulanabilir (örneğin, .WithCertificate ve .WithRedirectUri).

Ortak ve gizli istemci uygulamalarında ortak olan değiştiriciler

Genel istemcide veya gizli istemci uygulama oluşturucusunda ayarlayabileceğiniz değiştiriciler sınıfında AbstractApplicationBuilder<T> bulunabilir. Farklı yöntemler .NET belgeleri için Azure SDK bulunabilir.

Xamarin.iOS uygulamalarına özgü değiştiriciler

Xamarin.iOS'ta genel istemci uygulama oluşturucusunun üzerinde ayarlayabileceğiniz değiştiriciler şunlardır:

Değiştirici	Description
`.WithIosKeychainSecurityGroup()`	Yalnızca Xamarin.iOS: iOS anahtar zinciri güvenlik grubunu ayarlar (önbellek kalıcılığı için).

Gizli istemci uygulamalarına özgü değiştiriciler

Gizli bir istemci uygulama oluşturucusunun özel değiştiricileri sınıfında ConfidentialClientApplicationBuilder bulunabilir. Farklı yöntemler .NET belgeleri için Azure SDK bulunabilir.

.WithCertificate(X509Certificate2 certificate) ve .WithClientSecret(string clientSecret) gibi değiştiriciler birbirini dışlar. Her ikisini de sağlarsanız, MSAL anlamlı bir özel durum oluşturur.

Değiştirici kullanımı örneği

Uygulamanızın yalnızca kuruluşunuza yönelik bir iş kolu uygulaması olduğunu varsayalım. Ardından şunu yazabilirsiniz:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzurePublic, tenantId)
        .Build();

Ulusal bulutlar için programlama basitleştirildi, dolayısıyla uygulamanızın ulusal bir bulutta çok kiracılı bir uygulama olmasını istiyorsanız, örneğin:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAuthority(AzureCloudInstance.AzureUsGovernment, AadAuthorityAudience.AzureAdMultipleOrgs)
        .Build();

ADFS için de bir geçersiz kılma vardır (MSAL.NET yalnızca ADFS 2019 veya sonraki sürümleri destekler):

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithAdfsAuthority("https://consoso.com/adfs")
        .Build();

Son olarak, Azure AD B2C geliştiricisiyseniz kiracınızı şu şekilde belirtebilirsiniz:

IPublicClientApplication app;
app = PublicClientApplicationBuilder.Create(clientId)
        .WithB2CAuthority("https://fabrikamb2c.b2clogin.com/tfp/{tenant}/{PolicySignInSignUp}")
        .Build();