Microsoft 365 to rozwiązanie SaaS, będące często pierwszym wyborem dla wielu firm pod względem organizacji pracy zdalnej i zaawansowanych opcji bezpieczeństwa dostępu do danych. Wykorzystuje architekturę opartą na chmurze, zapewniając dostęp z jednego miejsca do ulubionych aplikacji i narzędzi, takich jak pakiet Office.
Kluczem do sukcesu jest integracja i synchronizacja między różnymi aplikacjami. Jak możemy sobie wyobrazić, firma Microsoft zapewnia synchronizację i integrację swoich narzędzi, ale co z integracją z aplikacjami innych dostawców?
Wyobraźmy sobie, że w naszej organizacji mamy dedykowaną aplikację typu CRM taką jak Salesforce, Dynamic CRM czy Bullhorn, która wspomaga zarządzanie danymi naszych klientów oraz wewnętrznych pracowników. Takie aplikacje zazwyczaj przechowują wiele danych pracowników, wliczając w to także dane wrażliwe takiej jak adres lub pensja. Z uwagi na charakter danych, dostęp do aplikacji jest ograniczony do wąskiego grona osób. Jednak ze względu na to, że wspomniana lista jest na bieżąco aktualizowana, chcielibyśmy udostępnić zasoby naszej firmy w jednej z usług platformy Microsoft 365. Mowa o liście dostępnej dla każdego pracownika, zawierającej jedynie informacje publiczne. Aplikacja innej firmy, której używamy, zapewnia już interfejs API do dostępu do danych, zatem potrzebujemy jedynie integracji, która opublikuje ją w witrynie SharePoint.
Nasza integracja będzie obejmować wiele usług platformy Microsoft 365, takich jak: Teams, Planner czy OneDrive. Zacznijmy jednak od stworzenia możliwości synchronizacji z SharePoint’em. Celem jest utworzenie osobistej przestrzeni w witrynie lub dołączenie nowego pracownika do prywatnych grup. Na potrzeby publikacji załóżmy, że chcemy dodać informacje do określonej listy SharePoint.
Jednym z pierwszych wyników, jakie uzyskamy po wpisaniu w Google hasła dotyczącego integracji z SharePoint, jest SharePoint REST API v1. Mowa o głównym interfejsie REST API firmy Microsoft, dedykowanym dla narzędzia SharePoint. Pozwala on na interakcję z danymi SharePoint przy użyciu dowolnej technologii, obsługującej żądania webowe REST. Nasza aplikacja kliencka może wykonywać operacje CRUD przy użyciu technologii Web REST, w połączeniu ze składnią OData. Co więcej, istnieje biblioteka klienta SharePoint – CSOM, z której możemy skorzystać, kiedy nie chcemy samodzielnie tworzyć żądań HTTP. Zatem spróbujmy.
Pierwszą rzeczą, którą musimy zrobić jest zarejestrowanie aplikacji w usłudze Azure AD. W tym celu należy przejść do sekcji Azure Active Directory, App registrations section oraz wybrać opcję „registration”. Po pomyślnym dokonaniu rejestracji, aplikacja otrzyma swój unikalny identyfikator aplikacji oraz identyfikator katalogu. Są one kluczowe w dalszym procesie uwierzytelniania.
Następnie musimy skonfigurować uprawnienia API. Aby tego dokonać, należy dodać delegowane uprawnienia do zarządzania wszystkimi witrynami SharePoint. Cały proces krok po kroku, znajdziemy pod tym linkiem. Typ uprawnienia delegowanego oznacza, że aplikacja musi uzyskiwać dostęp do interfejsu API jako zalogowany użytkownik. Nieco później przyjrzymy się bliżej innym typom uprawnień.
Aby uzyskać dostęp do witryny SharePoint, musimy ją uwierzytelnić. Próbując pobrać niektóre dane SharePoint za pomocą biblioteki klienta, w rzeczywistości wysyłamy żądania http do SharePoint REST API. Oznacza to po prostu, że musimy uzyskać token dostępu i zastosować go do każdego żądania, wysyłanego przez CSOM. Microsoft zaleca użycie ich przykładowej klasy AuthenticationManager do uwierzytelniania CSOM. Przyjrzyjmy się jej najważniejszym częściom:
Metoda GetContext zwraca obiekt specyficzny dla danego klienta. Posiada on metodę wywoływaną podczas obsługi zdarzenia typu “żądanie HTTP”. Jej działanie polega na dodaniu tokenu dostępu do nagłówków tego żądania. Poniższa fragment kodu przedstawia sposób na ostateczne wysłanie żądania typu POST do punktu końcowego Microsoft OAuth 2.0.
Ponieważ skonfigurowaliśmy naszą aplikację do korzystania z typu uprawnień delegowanych, musimy użyć danych uwierzytelniających właściciela zasobów OAuth jako protokołu uwierzytelniania. Wymaga to podania następujących informacji w treści żądania:
- client_id – nasz identyfikator aplikacji, który wygenerowaliśmy podczas rejestracji aplikacji
- grant_type – musi być ustawione na „password”,
- username – adres e-mail użytkownika,
- password – hasło użytkownika,
- resource- adres URL naszej witryny SharePoint.
Po udanym uwierzytelnieniu możemy spróbować uzyskać dostęp do witryny SharePoint i jej głównych podmiotów. Na potrzeby artykułu stworzyliśmy stronę SharePoint, z listą o nazwie „Employees”, która ma cztery kolumny: Tytuł, Imię, Nazwisko i Stanowisko oraz ręcznie dodaliśmy jedną pozycję listy. W tworzonym API zdefiniowałem serwis, który implementuje następujący interfejs do podstawowych operacji ze stroną i jej listami:
Poniższy kod obrazuje jak uzyskać określoną listę przy wykorzystaniu biblioteki CSOM oraz jak utworzyć nową pozycję listy.
Udało się! Teraz możemy dokonać uwierzytelnienia w usłudze Azure AD. Przekazując nasze poświadczenia, możemy pobierać encje takie jak lista, a także manipulować jej danymi za pomocą naszej usługi integracji.
Ale co z innymi integracjami? Czy musimy używać dedykowanego SDK dla każdej usługi z MS 365, z której chcemy skorzystać? Zadając sobie to pytanie natrafiłem na niesamowitą alternatywę – Microsoft Graph API
Microsoft Graph oferuje dostęp do ogromnej ilości danych, takich jak SharePoint, Excel, Microsoft Teams, OneDrive lub Outlook, za pośrednictwem pojedynczego, wspólnego punktu dostępu: https://graph.microsoft.com.
Możemy użyć REST API lub SDK, w celu łatwego dostępu do różnych pojedynczych, wspólnych punktów dostępu, bez konieczności tworzenia dedykowanej obsługi uwierzytelniania. Zachęcam Cię do poeksperymentowania z Graph API korzystając z Graph Explorer – narzędzia, które obsługuje proces uwierzytelniania i dostarcza szeroki wachlarz przykładowych zapytań HTTP z ich odpowiedziami. Jestem pod dużym wrażeniem jak bardzo przemyślany i kompaktowy jest Graph API, a samo budowanie zapytań- intuicyjne i przejrzyste. Przykładem może być proste żądanie:
https://graph.microsoft.com/v1.0/sites/root/lists/d7689e2b-941a-4cd3-bb24-55cddee54294/items/6
które pobiera określony element zdefiniowanej listy.
Graph API daje mnóstwo nowych możliwości. W naszym przypadku może to być na przykład wysłanie powitalnej wiadomości e-mail lub zorganizowanie spotkania z przełożonym. Brzmi bardzo obiecująco, zatem sprawdźmy to w praktyce.
Spróbujmy zrealizować kontrakt z interfejsem, który stworzyliśmy dla dostawców danych SharePoint. Po zainstalowaniu pakietów NuGet, musimy wybrać sposób uwierzytelnienia. Tym razem nie musimy tworzyć manualnie dedykowanej obsługi uwierzytelniania, ponieważ SDK obsługuje już dostawców uwierzytelniania dla różnych protokołów OAuth 2.0. Poniższy kod pokazuje, jak zainicjować klienta SDK, przy użyciu nazwy użytkownika/hasła.
Wystarczy tylko znać swój app ID oraz tenant ID, zakładając, że znasz już swoją nazwę użytkownika i hasło. 😊
Mamy klienta Graph API, który jest gotowy do uwierzytelnienia, więc pobierzmy listę pracowników, a następnie utwórzmy nowy element listy.
Jak możemy zauważyć, klient SDK jest łatwy w obsłudze i co najmniej tak intuicyjny, jak oryginalne REST API. Powyższy kod pobiera określoną listę, na której możemy znaleźć odpowiadający jej identyfikator, a następnie pomyślnie utworzyć nowy element.
Do tej pory pracowaliśmy z delegowanymi uprawnieniami, logując się w imieniu rzeczywistego, istniejącego użytkownika oraz jego adresu e-mail i hasła. Może to zdać egzaminu w przypadku aplikacji webowych, w których przekierowujemy użytkownika do punktu logowania i prosimy go o ręczne zalogowanie się. W przypadku web API, przechowywanie czyichś poświadczeń nie wydaje się najlepszą możliwą opcją. W tym przypadku wolelibyśmy przypisać interfejsowi API jego indywidualną tożsamość i pozwolić mu wziąć odpowiedzialność za wszystkie wykonywane czynności. W sekcji Uprawnienia interfejsu API można dodać uprawnienia aplikacji, zamiast tych delegowanych.
Następnie, w podobny sposób wybieramy API – w tym przypadku Sites – i wybieramy jedną z dostępnych opcji, na przykład Sites.Manage.All. Następnie przejdźmy do sekcji Certificates & secrets w lewym okienku, gdzie możemy wygenerować poświadczenia dla swojej poufnej aplikacji. Istnieją na to dwa sposoby:
- przesłanie certyfikatu
- wygenerowanie klucza klienta.
Dla większego poziomu bezpieczeństwa Microsoft zaleca używanie certyfikatu, ale w tym przypadku użyjmy klucza klienta.
Ta wartość powinna być przechowywana w bezpiecznym miejscu, takim jak KeyVault, ponieważ teraz wystarczy znać jedynie klucz klienta i identyfikator aplikacji (który jest publiczny), aby móc zarządzać wszystkimi witrynami SharePoint. Jeśli nasza aplikacja ma uzyskiwać dostęp tylko do określonej strony, rozsądnym będzie ograniczenie jej uprawnień tylko do wybranych witryn, wybierając opcję Sites.Selected. Warto wspomnieć, że ta funkcja została niedawno dodana do Graph API przez firmę Microsoft, po wielu prośbach użytkowników. W przeszłości można było przyznać dostęp tylko do wszystkich witryn SharePoint, co było sprzeczne z zasadą najmniejszego możliwego dostępu – aplikacja stawała się wręcz wszechmogąca w kontekście dostępu do Sharepoint’a.
Ostatnią, ale niemniej ważną rzeczą do zrobienia jest zmiana dostawcy uwierzytelniania, którego używamy do tworzenia instancji klienta Graph.
Jak widać powyżej, zastąpiliśmy uwierzytelnianie typu nazwa użytkownika / hasło, nowym wykorzystującym klucz klienta.
Usługi platformy Microsoft 365 są otwarte na integrację i dają dużą przestrzeń na dostosowanie ich do indywidualnych potrzeb. Wszystkie powiązane ze sobą funkcje Graph API, Azure AD i Azure Security sprawiają, że cała platforma jest nie tylko rozszerzalna, ale także bezpieczna.
Na początku tej publikacji określiliśmy synchronizację i integrację „kluczem do sukcesu” i jesteśmy pewni, że rozwiązania chmurowe, oferowane przez firmę Microsoft odzwierciedlają to w najlepszy możliwy sposób.
Jeżeli macie jakiekolwiek pytania dotyczące możliwości integracji z platformą Microsoft 365 lub podobnych zagadnień, zapraszamy do kontaktu!
Autor: Przemysław Wąs, Full Stack Developer
