Merhaba , bu yazımızda Microsoft Graph API üzerinde uygulama geliştirme yazımızın ardından kullanıcı için Token alma işlemlerini göreceğiz ve konu hakkında detayları paylaşacağız.
Microsoft Office 365 üzerinden Office Development olarak adlandırılan ve Add-In geliştirme olarak bilinen uygulamalar için sisteme uygulamamızı yetkilendirmek için daha önceden de diğer sistemler ( Tweeter , Facebook vb API’ler) üzerinde de yetkilendirme için aldığımız Token ( jeton J ) benzeri bir yetki kodu almamız gerekmektedir.
Yukarıda belirttiğimiz bu jetonlama işlemi bir önceki yazımda belirttiğim uygulama kurulumunda belirtilen Azure Ad üzerine kayıtlı kullanıcılar için verilen bir erişimdir ve bu erişim JSON Web Token (JWT) olarak adlandırılır.
Kişi doğrulama ve uygulama doğrulama için Graph ya da Web API’lar tarafından kullanılarak talepte bulunan kişi yada hesapların uygun izinlere sahip olup olmadıklarını kontrol eder. Token istemlerinde mutlaka bir Secure ( güvenli ) Layer üzerinden bilgi gönderilmelidir. Diğer adı ile SSL üzerinden veri gönderimi yapılmalıdır.
Bu belirttiğimiz kurallara uygun olarak Azure Ad üzerinden aldığımız bir Token bilgisi aşağıdaki gibi olacaktır.
Microsoft Graph İzinleri Nedir ?
Microsoft Graph desteklediği ve denetlediği uygulamalar üzerinde birden fazla daha doğrusu oldukça zengin bir dizi izin ayrıcalıkları sunar. Microsoft Graph üzerinde yetkiler diziler olarak ifade edilir ve uygulamalar, kullanıcılar gibi nesneler bu dizileri kullanarak Microsoft Graph üzerinden yetki talep ederler.
Uygulama dizi nesneleri aşağıdaki gibidir.
User.Read Uygulama üzerinde oturum açan kullanıcıya okuma izni verir
User.Write Uygulama üzerinde oturum açan kullanıcıya yazma izni verir
Mail.Send uygulama da oturum açan kullanıcının adı ve mail adresini kullanarak mail gönderilmesine izin verir
Uygulamalarda Graph API üzerinde iki adet izin türü bulunmaktadır;
Delegated Permissions
Bu izin türleri kullanıcı ile birlikte çalışır ve uygulama tarafından kullanılır. Bu izin türünü mutlaka bir kullanıcıya tanımlamak zorundayız. Microsoft Graph üzerindeki uygulamadan kullanıcı giriş yaptığında bu izinler uygulama üzerine devredilir. İzinler kullanıcı tanımlı olabildiği gibi bazı izin nesneleri yönetici onayı gerektirir.
Application Permissions
İzinlerin çalışması için Delegated Permission’lardaki gibi herhangi bir kullanıcıya ihtiyaç duymayan izin türüdür. Bu tür izinlerde tüm verilen izinler yönetici onayından geçmek zorundadır.
Microsoft Graph üzerindeki izinlerin tam listesi ve uygulama izinleri arasındaki farklar için lütfen aşağıdaki adresi ziyaret ediniz.
https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference
Uygulama İzinlerini ve Token’ı nereden alarım ?
Uygulamalar Azure AD üzerinden erişim isteklerini yaptıklarını belirtmiştik. Bu erişimi sağlamak için OAuth 2.0 ve Open ID Connect kullanarak Azure Ad ve https üzerinden istekleri kabul eder.
Uygulamaya erişim için End Point olarak bilimen URI leri çok basit bir şekilde HTTP portoklü üzerinden kullanabilirsiniz.
/authorize ; uygulamanızın Azure AD ile kimlik doğrulaması yapması için kullanıcınızın o uygulamaya ait izinlerinin doğrulanması için gerekli end point’dir. Onay durumunda kullanıcınız bu linkten gelen veriler yardımı ile uygulama izinlerini alır.
/token ; ise kullanıcınızın erişim izni alabilmesi için gerekli end point dir. Bu iki end point Url sini http protokolü üzerinden deneyebilirsiniz.
Ayrıca Azure AD üzerinde v2 tarafından sunulan /authorize ve /token işlemlerine ait url istemleri için end point aşağıdaki gibidir.
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
https://login.microsoftonline.com/common/oauth2/v2.0/token
Azure Ad üzerinden gelen isteklerin hiç biri , Azure Ad V2 den gelen istekler ile değiştirilemez. Eğer bir veri yolu üzerinden devam ediyorsanız aynı yol ve protokol üzerinden isteklerinizi tamamlamanız gerekecektir. Ayrıca Azure AD v2 yeni olduğundan devamlı güncellenmektedir. Methodlarınızın yada uygulamanızın bundan etkilenmemesi için Azure AD V2 release versiyon duyurulana kadar işlemlerinizi test ortamında yapmanız daha doğru olacaktır.
Gerekli token alma işlemlerinden yüzeysel olarak bahsettik. Peki bu aşamadan sonra bizim Graph API ile konuşan uygulamalarımız ne türde olabilir.
Hangi tür uygulamalar kullana bilirim ?
Microsoft Graph ile 5 tip uygulama kullanabilmekteyiz. Bunlardan basitçe bahsetmek gerekirse ;
Native Uygulamalar
Bu tür uygulamalar Masaüstü,tablet,cep telefonu gibi cihazlardan çalışan temel uygulamalardır ve iOS, android , Windows gibi platformlar üzerinde Graph API çağırır
Web Uygulamalar
Herhangi bir sunucu üzerinde çalışan ve oturum açmış bir kullanıcı tarafından API ile konuşan uygulamalardır.
Tek Sayfa Uygulamalar ( Single Page Apps (SPA) )
Sunucular tarafından istemci tarafında kullanılan tek sayfalık web uygulamalarıdır. Ajax veya React gibi istemci taraflı dilleri kullanarak komut gönderir ve API ile bağlantı kuran uygulamalardır.
Arka Plan Servisler
Mevcut bir kullanıcının bulunduğu sunucuda çalışan uygulamalar ve servislerin API ile konuşanlarıdır.
Web API’ler
İstemci tarafında çalışan ve Azure Ad tarafından güvenceye alınmış olan bir sunucu üzerinde çalışan Web API lerdir. İstemci ve Web API aynı kimliğe sahip olması gerekmektedir.
Uygulamalarım Microsoft Graph ile Nasıl entegre Olur ?
Uygulamalarınızın Azure Ad üzerinden Graph ile konuşması için yazımızın başında o uygulamanızın Microsoft Uygulama Portalına ( Microsoft app registration Portal) kayıt olması gerektiğinden bahsetmiştik. Uygulamanızın bu portala kayıt olması demek, uygulamanızın kişisel kimliğinin Azure Ad üzerine portal vasıtası ile bağlanmasını sağlar.
Uygulama kimliği için tanımlayıcılar aşağıdaki gibidir ;
Uygulama Kimliği ( Application ID )
Azure AD tarafından uygulamanıza atanan benzersiz bir uygulama adresidir. Bu adres siz geliştirme yaptığınız süre boyunca ve yayına alma süreçleri de dahil olmak üzere değişmeyecektir.
Redirect URL
Uygulamanızın Azure AD tarafından yönlendirileceği ve uygulamanızın yanıtlarını toplayacağı URL dir. Mobil uygulamalarda bu URL Azure AD tarafından atanır. Uygulamanızın URL sini App Registration portaldan değiştirme olasılığınız bulunur yayına alınmış uygulamalar için risk teşkil edebilir.
Uygulama Gizli Şifresi ( App Secret)
Kimlik doğrulaması yapılabilmesi için Azure AD üzerinde tanımlanan bir özel şifredir.Mobil uygulamalarda bu key gerekli değildir.
Azure AD üzerindeki end-point adreslerini kullanan uygulamalar, Microsoft Graph izinlerini kullanabilmek için öncede yapılandırılmak zorundadırılar. Azure Ad v2 kullanıcıları bu izinleri daha sonrada yapılandırma imkanına sahiptirler.
Aşağıda örnek olarak kullanılan bir http isteğini bulabilirsiniz
POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr…
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOT: Sadece web uygulamaları için gerekli
Temel olarak yukarıda Uygulama Token hizmetleri ile alakalı bilgiler aktarmaya çalıştım. Bu bilgilerde şu an için Azure Ad üzerinde esas olan ve Azure Ad v2 ile beraber işlemlerin ve uyglamaların daha esnek olarak kullanılabilirliği gözlemlenmektedir.
Azure Ad V2 end-pointlerin kullanılması yazı içindede belirttiğimiz gibi şu an tam manası ile oturmadığından yayına alınacak olan uygulamalarınız için ufak sorunlara neden olabilir. Microsoft tarafından Azure Ad v2 end-pointler release olarak duyurulduğunda uygulamalarınızı direk olarak güncelleyerek yeni sistem üzerinden de uygulamalarınızı yayına alabilirsiniz.
Bir sonraki yazımızda kullanıcı ve uygulamalar için token işlemlerinin nasıl alınacağına dair örneklerimiz ve Graph izinlerinin detayları hakkında bilgilenmek üzere.
Faydalı olması dileği ile.