Application User ile S2S (Server to Server) Entegrasyon ve Dynamics 365 CE Web API Kullanımı
Bu yazı 03 Mayıs 2019 tarihinde Medium/@dynamics365 altında yayınlanmıştır. 15 Mayıs 2020 tarihinde emregulcan.com altında taşınmıştır.
İçerikler, yazının oluşturulduğu tarih için geçerli olup, Microsoft Dynamics 365 CE, Power Platform ve Azure hizmetlerinin sürekli iyileştirme ve güncelleme döngüsünden dolayı paylaşılan bilgilerde değişiklikler meydana gelmiş olabilir.
Merhaba,
Önceki yazılarda Azure Active Directory ‘de Application Tanımlanma ve Dynamics 365 CE (CRM) ‘de Application User Tanımlanma konularını detaylı olarak anlatmıştım.
Bu yazıda ise daha önce oluşturduğumuz Application User ‘ı Dynamics 365 CE (CRM) Web API çağrılarında nasıl kullanabileceğimizi anlatacağım.
Bildiğiniz gibi Dynamics 365 CE (CRM) OrganizationService.svc (2011 Endpoint olarak da bilinmekte), data transferi için SOAP mimarisini kullanmakta ve proxy nesneleri genel olarak .NET Framework için elverişli bir kullanıma sahip. Bu nedenle OrganizationService ‘i web sayfalarında Javascript ile ya da mobil uygulamalarda geliştirme yaparken kullanmak istediğimizde bir takım zorluklar yaşamaktayız. İşte tam bu noktada Microsoft Dynamics 365 CE (CRM) için RESTful mimarisini kullanarak JSON formatlı data transferi sağlayan Web API ‘yi kullanıma sundu.
Bu arada önemli bir nokta olarak, OrganizationService ‘in deprecated olduğunu yani yakın zamanda sonlandırılacağını belirtmekte fayda var.
Detaylı bilgi için https://docs.microsoft.com/en-us/previous-versions/dynamicscrm-2016/developers-guide/dn281891(v=crm.8)#microsoft-dynamics-crm-2011-endpoint adresine bakabilirsiniz.
Dynamics 365 CE (CRM) Web API ‘yi Http istek yapabildiğimiz tüm platformlarda rahatça kullanabiliriz. Web sayfalarında Javascript ile XmlHtpRequest ya da jQuery Ajax Request kullanarak, Postman, cURL gibi araçlarla ya da .NET Framework ‘te HttpClient nesnesini kullanarak (ve diğer dillerde karşılığı olan bir sınıf) ile istek yapabiliriz.
Elbette Dynamics 365 CE (CRM) ‘in güvenlik yapısının gerektirdiği üzere öncelikli olarak Authentication işlemi yapmamız gerekli. Bu işlem OAuth protokolü üzerinden gerçekleştirilmekte ve sonucunda bir Access Token oluşmakta. Sonrasında yapılacak tüm işlemlerde bu Access Token kullanılmakta.
OAuth ‘da birden fazla yöntem ile Authentication işlemini yapabiliriz, fakat bizim asıl konumuz Application User hesabımızı kullanarak Web API isteklerini yapmak olduğu için bu yazıda Client ID ve Client Secret kullanarak Authentication işlemlerini gerçekleştireceğiz. OAuth literatüründe bu işlem Client Credentials Grant olarak adlandırılmakta.
Dynamics 365 CE (CRM) Web API ‘yi kullanmak için aşağıdaki bilgilere ihtiyacımız bulunmakta;
- Authority URI : Azure Active Directory üzerinde kayıtlı olan Application ‘a bağlantı yapabilmemiz için gerekli olan OAuth Endpoint bilgisi
- Single Tenant uygulamalar için https://login.microsoftonline.com/common/oauth2/authorize
- Multiple Tenant uygulamalarda ise https://login.microsoftonline.com/{TENANT_ID_BİLGİSİ}/oauth2/authorize olarak kullanılmaktadır.
- Dynamics 365 CE (CRM) Organization Url : Dynamics 365 CE (CRM) instance url bilgisi
- Client (Application) ID : Azure Active Directory ‘de tanımlı olan Application için Application ID bilgisi
- Client Secret : Active Directory ‘de tanımlı olan Application için eklemiş olduğumuz Client Secret bilgisi
.NET Framework Kullanarak Web API ‘ye Erişim
.NET Framework kullanarak yaptığımız geliştirmelerde Web API erişimi için System.Net.Http namespace altında bulunan HttpClient nesnesini kullanacağız.
Web API ile herhangi bir CRUD işlemi yapmadan önce Authentication işlemini gerçekleştirmeli ve geçerli bir Access Token almalıyız.
Access Token oluşturmak için 2 alternatifimiz bulunmakta;
İlk yöntem Microsoft tarafından sunulan Microsoft.IdentityModel.Clients.ActiveDirectory (ADAL olarak da anılmakta) NuGet paketini kullanmak. Böylece Active Directory üzerinden Authentication işlemlerini rahatça yapabiliriz.
Diğer yöntem ise HttpClient kullanarak OAuth Client Credentials Grant akışı ile gerekli tüm parametreleri Request Body içinde ilettiğimiz Http Request yapısını manuel olarak oluşturmak.
ADAL Kullanarak Authentication İşlemi – Access Token Alma
Bunun için projemize Microsoft.IdentityModel.Clients.ActiveDirectory paketini referans olarak eklemeli. Bu yazıyı hazırlamaya başladığım tarihte (25 Nisan 2019) güncel sürüm bilgisi 4.5.1 . Bu yazıyı emregulcan.com altına taşıdığım tarihte (15 Mayıs 2020) güncel sürüm bilgisi 5.2.7 ‘dir. (Anlatım 4.5.1 sürümü üzerinden devam edecektir, bu nedenle aşağıda anlattığım bazı hatalar yeni sürümlerde düzenlenmiş -bugfix- olabilir.)
Eğer ADAL ‘ın son sürümünü (4.5.1) ve AuthorityURI olarak yukarıda belirttiğim URI bilgilerinden herhangi birini kullanırsanız AADST90002 hatası alacaksınız.
AADSTS90002 : Tenant 'authorize' not found. This may happen if there are no active subscription for tenant. Check with your subscription administrator .
Bu hata mesajı ile ilgili olarak ADAL ‘ın GitHub hesabı ‘nda bir Issue mevcut, https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues/1346 adresinden detaylara ulaşabilirsiniz.
Bu hatayı çözmenin 2 alternatif yolu mevcut;
İlk çözüm 4.5.1 yerine daha eski sürüm olan 3.19.8 sürümünü projeye eklemek ve yukarıda belirttiğim Authority URI bilgilerini kullanmak.
Diğer çözüm ise Microsoft ‘ta Azure AAD Principal SDE olarak çalışan Mark ZUBER ‘in https://github.com/AzureAD/azure-activedirectory-library-for-dotnet/issues/1346#issuecomment-432426513 adresinde belirttiği şekilde Authority URI ‘nin sadece https://login.microsoftonline.com/{TENANT_ID_GUID} olarak kullanılması. Dikkat ederseniz sonunda oauth2/authorize yok.
Ben her iki yöntemi de denedim ve başarılı olarak işlem yaptım, hangi yöntemi kullanacağınız tamamen size kalmış. Fakat ileriye dönük olarak problem yaşamak istemiyorsanız Mark ZUBER ‘in önerdiği yöntem ile devam etmenizde fayda var.
ADAL kullanarak Authetication işlemi yapmak ve Access Token almak için aşağıdaki kodu kullanabilirsiniz;
OAuth Client Credential Grant Kullanarak Authentication İşlemi – Access Token Alma
Bu yöntemde .NET Framework ‘e bağlı olmadan, HTTP istek yapabilen herhangi bir client ile authentication işlemin gerçekleştirip Access Token alabiliriz, fakat ana başlık .NET Framework olduğu için bu örnekte HttpClient kullanacağım.
Access Token alabilmek için, Client (Application) ID ve Client Secret bilgisine sahip olmamız gerekmekte. Bu bilgileri ilgili Authority adresine gönderdiğimizde eğer yetkimiz varsa bir Access Token oluşacak.
Bu işlem Client Crendentials Grant olarak isimlendirilmekte, detaylı bilgi için https://www.oauth.com/oauth2-servers/access-tokens/client-credentials adresine bakabilirsiniz.
.NET Framework kullanarak geliştirdiğiniz projelerde aşağıdaki kodu kullanarak Access Token bilgisini alabilirsiniz.
Burada dikkat edilmesi gereken nokta authorityURI parametresinin https://login.microsoftonline.com/{TENANT_ID_GUID} formatında olması. 7. satırda bu url ‘in sonuna oauth2/token ekleyerek asıl url oluşturulmakta.
Web API ‘ye İstek Yapılması
Access Token ‘ı başarıyla aldıktan sonra artık Web API ‘ye istek yapabiliriz. Dynamics 365 CE (CRM) Web API url bilgisi https://organizasyonadi.crm4.dynamics.com/api/data/v9.1 formatındadır, koyu renkli olarak belirttiğim organizasyonadı, crm4 ve v9.1 kullanmış olduğunuz Instance ‘a göre değişiklik göstermektedir.
Bu bilgiye ulaşmak için Settings (Ayarlar)>Customizations (Özelleştirmeler)>Developer Resources (Geliştirici Kaynakları) adımlarını takip edebilirsiniz, bu sayfada Instance Web API başlığı altında Service Root URL ‘de Web API url bilginiz yazmakta.
Data Okuma
Yukarıdaki kodda dikkat edilmesi gereken birkaç nokta bulunmakta;
Öncelikli olarak 42. satırda HttpClient nesnesine AuthorizationHeader ekleyerek önceki adımda elde etmiş olduğumuz Access Token bilgisini gönderiyoruz. Bu Access Token geçerli olduğu sürece yetkimiz dahilinde tüm dataya erişebiliriz.
Ayrıca FormattedValues yani Lookup alanların Name bilgisini ya da OptionSet alanların Text bilgilerini alabilmek için Headers ‘a Prefer : odata.include-annotations=* ekliyoruz.
Data Oluşturma ve Güncelleme
Eğer Dynamics 365 CE (CRM) üzerinde herhangi bir kayıt oluşturmak istersek HTTP POST, kayıt güncellemek istersek HTTP PATCH metodunu kullanmamız gerekiyor.
Elbette paylaştığım bu kodlar sadece S2S ve Application User kullanımına özel değil, tüm işlemlerinizde kullanabilirsiniz.
Web ve Mobil Projelerden Dynamics 365 CE Web API ‘ye Erişim
Daha önce belirttiğim gibi HTTP istek yapabildiğimiz tüm client ‘lar ile Dynamics 365 CE (CRM) Web API erişimi sağlayabilir ve desteklediği tüm metotları kullanabiliriz.
Microsoft birçok platform için Active Directory Authentication Libraries (ADAL) paketlerini sunmakta, https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-authentication-libraries ve OAuth v2 için https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-v2-libraries adreslerinden bu paketlerin detaylarına ulaşabilirsiniz. Böylece dış uygulamalarınızda Azure Active Directory üzerinden authentication işlemini rahatça yapabilirsiniz.
Mobil uygulamalar bu yazıların kapsamına girmediği için iOS ve Android üzerinden örnek yapmayacağım.
Bu yazının konusu S2S (Server-to-Server) entegrasyonlar olduğu için web projelerinde Javascript ile Web API erişimini farklı bir yazıda detaylı olarak anlatacağım. Fakat belirtmem gereken önemli bir nokta var, Client-side bir geliştirme yapıldığı ve kodlar herkes tarafından erişebilir olduğu için Client Credentials Grant yapısını kullanarak sadece bize ait olan bir Client Secret bilgisini herkese açmak çok mantıklı değil. Web uygulamalarımızda Dynamics 365 CE (CRM) Web API ‘ye bağlanırken ilgili kullanıcı için username ve password bilgisi alacağımız bir ekrana yönlendirme ve kullanıcı için Access Token almamız gerekli.
https://github.com/emregulcan/dynamics365turkiye adresinden tüm örnek kodlara ulaşabilirsiniz. Bu yazının projesi MediumD365.ConnectWebAPI isimli Console Application , sadece Program.cs içinde ilk 4 satırda bulunan değişkenlere kendi değerlerinizi vermeniz yeterli olacaktır.
Umarım faydalı bir yazı olmuştur.
