Anwendungsregistrierung in der Microsoft Cloud
Skalierbarkeit, Flexibilität und Verfügbarkeit sind unter anderem gute Gründe, warum viele Unternehmen aktuell auf Cloud Lösungen setzen. Das Azure Active Directory (AAD) bildet in der Microsoft Cloud den Dreh- und Angelpunkt für die korrekte Absicherung der Onlinedienste von Unternehmen. In diesem Tutorial gehen wir näher auf Anwendungsregistrierungen ein. Diese werden benötigt um Zugriff auf abgesicherte Dienste von Microsoft wie z.B. Dynamics 365 zu erhalten. Um dies anhand eines praktischen Beispiels zu zeigen, werden wir eine Konsolenanwendung schreiben, die alle Kontakte mit dem Anfangsbuchstaben „I“ ermittelt und ausgibt.
Microsoft Azure
Azure Portal
Das Azure Portal ist unter www.portal.azure.com zu erreichen. Über die Startseite oder das Menü auf der linken Seite gelangt man ins Azure Active Directory.
Azure Active Directory
Das AAD bietet eine Vielzahl von Möglichkeiten, um Zugriffsrechte zu verwalten. In unserem Fall klicken wir auf den Reiter „App-Registrierungen“. Mit einem Klick auf „Neue Registrierung“ erstellen wir eine neue Anwendungsregistration.
Anwendungsregistrierung
Neue Anwendungsregistrierung
Bei der Erstellung einer neuen Anwendungsregistrierung geben wir zunächst den Namen der Anwendung an. Dieser Name dient der Wiedererkennung im AAD für spätere Änderungen. Es sollte aber ein Name gewählt werden, anhand dessen erkennbar ist für welche Anwendung diese Registrierung vorgesehen ist. Dies erleichtert es im weiteren Verlauf, die Rechte zu erweitern oder einzuschränken falls nötig. Der zweite Punkt sind die unterstützten Kontotypen. Unsere Konsolenanwendung wird diese Einstellung nicht berücksichtigen, da wir später eine Anmeldung mit Client-Credentials durchführen werden. Wenn Sie aber z.B. eine Website planen, welche ein Login durch den Benutzer vorsieht, müssen Sie hier entscheiden, welche Kontotypen Sie zulassen. Im Regelfall nutzt man für interne Anwendungen Punkt 1 und für Anwendungen die auch fremde Microsoft Konten zulassen Punkt 3. Genauere Details finden Sie mit einem Klick auf „Entscheidungshilfe“. Zuletzt wird noch die optionale Eingabe einer Umleitungs-URI angeboten. Diese kann nachträglich geändert werden. Sollten Sie eine Website mit Anmeldung Planen müssen Sie hier die URI eintragen auf die Benutzer nach der erfolgreichen Anmeldung bei Microsoft umgeleitet werden. Auch eine localhost Adresse kann hier zu Entwicklungszwecken hinterlegt werden. Diese sollte nach der Entwicklung jedoch wieder entfernt werden.
Übersichtsseite
Nach erfolgreicher Registrierung der Anwendung gelangen Sie in die Übersicht der Anwendung. Hier finden Sie wichtige Informationen wie z.B. die Anwendungs-ID. Diese werden wir später benötigen, um unsere Konsolenanwendung zu authentifizieren. Möchten Sie eine Webanwendung mit Anmeldung durch den Benutzer registrieren, so müssen Sie nun auf den Menüpunkt Authentifizierung wechseln.
Authentifizierung
Hier können Sie jederzeit Umleitungs-URI hinzufügen oder entfernen. Auch haben Sie die Möglichkeit, eine Abmelde-URL einzutragen. Sollte ein Benutzer sich von Ihrer Anwendung abmelden ist dies die URL, auf die er umgeleitet wird, sobald die Abmeldung erfolgreich war. Haben Sie beispielsweise eine Angular Singlepage Website, die eine Anmeldung durch einen Benutzer durchführt, benötigen Sie eventuell einen Zugriffstoken oder ID-Token.
- ID-Token: Diese Art von Token wird genutzt, um einen Benutzer zu identifizieren. Er enthält Informationen wie z.B. die E-Mail Adresse und den Namen des Benutzers. Diese Art von Token kann nicht verwendet werden um auf weitere Dienste von Microsoft wie z.B. die Dynamics API zuzugreifen.
- Zugriffstoken: Dieser Token wird genutzt um z.B. per JavaScript Zugriff auf weitere Microsoft Dienste wie die Dynamics API oder die Graph API zu erhalten. Er enthält nur Berechtigungen für Dienste, die unter „API-Berechtigungen“ konfiguriert sind.
Zertifikate und Geheimnisse
Zertifikate und Geheimnisse werden von Client-Anwendungen genutzt, um sich gegenüber den Microsoft Diensten zu authentifizieren, ohne dass ein Benutzer sich explizit anmeldet. Hierdurch arbeitet die Clientanwendung im Kontext der Anwendung selbst anstelle des Benutzers. Dadurch können Zugriffsberechtigungen der Anwendung von denen der Benutzer abweichen. Unsere Konsolenanwendung wird einen geheimen Clientschlüssel (Clientsecret) benutzen um sich als Anwendung zu identifizieren. Hierfür werden nur eine Beschreibung und eine Gültigkeitsdauer angegeben. Wichtig ist, dass man den geheimen Clientschlüssel direkt nach der Generierung an einem sicheren Ort ablegt. Nachträglich kann der Clientschlüssel nicht mehr eingesehen werden.
API Berechtigungen
In diesem Bereich kann man die Berechtigungen für eine Vielzahl von Microsoft APIs konfigurieren. Es ist desweiteren auch möglich, eigene APIs mit Microsoft Zugriffstoken abzusichern. Für unseren Anwendungsfall müssen wir zwei Berechtigungen konfigurieren:
- Microsoft.Graph User.Read Dies ist die Standard Berechtigung, die benötigt wird, um ein Login möglich zu machen.
- Dynamics CRM user_impersonation Dies erlaubt der Anwendung den Zugriff auf Dynamics als Systembenutzer. Welche Zugriffe innerhalb von Dynamics 365 gewährt werden ist dann von dem Systembenutzer in Dynamics abhängig, mit welchem wir Zugreifen. Mehr Details hierzu gibt es im Kapitel „Anwendungsbenutzer“.
Nach der Konfiguration dieser Berechtigungen müssen wir noch den Button „Administratorenzustimmung erteilen“ drücken. Diese Aktion kann nur ein Verzeichnissadministrator (Tenant-Admin) durchführen. Nun ist die Anwendungsregistrierung abgeschlossen. Da wir uns jedoch im Dynamics als Systembenutzer anmelden möchten, sind weitere Schritte erforderlich.
Dynamics 365
Anwendungsbenutzer einrichten
Wie bereits erwähnt erfolgt die Rechteverwaltung innerhalb von Dynamics 365 mithilfe der Sicherheitsrollen an den Systembenutzern. Damit unsere Anwendung sich in Ihrem Kontext anmelden kann, werden wir nun einen Anwendungsbenutzer hinzufügen und anschließend die Sicherheitsrollen zuweisen. Bitte beachten Sie das die Navigation sich je nach System und Einstellung (z.B. Unified Interface oder Classic) unterscheiden kann. Zunächst navigieren wir Innerhalb von Dynamics 365 auf Einstellungen | Sicherheit | Benutzer
Hier ist es wichtig, die Benutzeransicht auf „Anwendungsbenutzer“ zu stellen. Diese Sicht ist eine Standardsicht von Dynamics 365. Sollte diese Sicht nicht verfügbar sein, ist eine Aktivierung der Sicht unter „System anpassen“ oder in der von Ihnen für Benutzersichten genutzten Lösung notwendig.
Nach der Umstellung der Sicht klicken wir auf „Neu“ und gelangen damit in die Anlage eines Anwendungsbenutzers. Sollten Sie an dieser Stelle ein Popup mit dem Hinweis auf die Verwaltung von Office 365 erhalten, vergewissern Sie sich, dass die Suchansicht „Anwendungsbenutzer“ wirklich ausgewählt ist und die Standardansicht von Dynamics 365 ist.
In der Neuanlage des Anwendungsbenutzers sind alle Pflichtfelder auszufüllen. Als Name empfiehlt es sich, einen Namen zu wählen, der die zugreifende Anwendung erkennbar macht. Die Anwendungs-ID haben wir im Kapitel „Anwendungsregistration – Übersichtsseite“ erhalten. Wenn diese hier korrekt eingetragen wurde, werden die restlichen Felder von Dynamics 365 nach dem Speichern ergänzt. Das Ergebnis sollte wie folgt aussehen:
Nun ist der Anwendungsbenutzer eingerichtet. Alle Aktionen, die unsere Anwendung im Dynamics 365 durchführt, werden uns später mit diesem Benutzer angegeben. (z. B. bei Änderungen an einem Datensatz wird „letzte Änderung durch“ angegeben mit „D365 Testanwendung“). [/column_full] [column_full]
Sicherheitsrollen
Als letzter Schritt in Dynamics 365 müssen wir dem Anwendungsbenutzer eine Sicherheitsrolle zuweisen. Die Sicherheitsrolle sollte stets so gewählt werden, dass Sie nur die Rechte abdeckt, die zwingend von der Anwendung benötigt werden. Weil es sich bei unserem System nur um ein Testsystem handelt, welches nur dem Erstellen von Anleitungen dient, vergeben wir an dieser Stelle einfach die Systemadministratoren Rolle. Diese können Sie über den Button „Rollen verwalten“ zuweisen.
Nachdem unser Anwendungsbenutzer nun angelegt ist und eine Sicherheitsrolle hat, kann die App sich erfolgreich gegen Dynamics 365 authentifizieren. Beachten Sie bitte, wenn Sie eine Website mit Zugriffstoken erstellt haben, gelten stets die Berechtigungen des angemeldeten Benutzers. [/column_full] [column_full]
Konsolenanwendung
Nach erfolgreicher Anlage der Anwendungsregistrierung und des Anwendungsbenutzers möchten wir die Authentifizierung mithilfe einer Konsolenanwendung testen. Hierfür erstellen wir zunächst mit Visual Studio 2019 eine neue Konsolenanwendung.
Anschließend fügen wir über die NuGet-Verwaltung das Paket „Microsoft.CrmSdk.XrmTooling.CoreAssembly“ hinzu. Dieses werden wir für den Verbindungsaufbau und den Abruf von Kundendaten nutzen. Beachten Sie bitte, dass Sie hier eine mit Ihrem Dynamics 365 kompatible Version benötigen. In unserem System ist dies 9.1. Hierfür führen wir einen Rechtsklick auf die Solution aus und wählen „Manage NuGet Packages“. Anschliessend geben wir im Browser „Microsoft.CrmSdk.XrmTooling.CoreAssembly“ ein und installieren das Paket über den „Installieren“ Button.
Anschließend ersetzen wir den Code der Program.cs Klasse mit folgendem Code:
1. using Microsoft.Xrm.Sdk;
2. using Microsoft.Xrm.Sdk.Query;
3. using Microsoft.Xrm.Tooling.Connector;
4. using System;
5. using System.Collections.Generic;
6. using System.Linq;
7. using System.Text;
8. using System.Threading.Tasks;
9.
10. namespace Testanwendung
11. {
12. class Program
13. {
14. //Die URL für die Dynamics Instanz auf die zugegriffen werden soll
15. private const string uri = "https://mididev.crm4.dynamics.com";
16. //Die Anwendungs-ID (Client) aus dem Azure Portal
17. private const string CRM_APPID = "XXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
18. //Der Geheime Clientschlüssel aus dem Azure Portal
19. private const string CRM_CLIENTSECRET = "XXXXXXXXXXXXXXXXXXXXX";
20. //Ein Pfad unter dem der Token nach erfolgreicher Anmeldung gecached wird. Null um das caching zu deaktivieren
21. private const string TokenCachePath = @"C:\tmp\testanwendung\token";
22.
23. static void Main(string[] args)
24. {
25. //Initialiseren des CrmServiceClient. Hierdurch wird auch die Authentifizierung durchgeführt.
26. CrmServiceClient service = new CrmServiceClient(new Uri(uri), CRM_APPID, CRM_CLIENTSECRET, true, TokenCachePath);
27. IOrganizationService serviceProxy = service.OrganizationWebProxyClient != null ? service.OrganizationWebProxyClient : (IOrganizationService)service.OrganizationServiceProxy;
28.
29. //Vorbereiten einer Abfrage an das Dynamics System. Hier wird die Entität Kontakt(contact) abgerufen.
30. QueryExpression contactQuery = new QueryExpression()
31. {
32. EntityName = "contact",
33. ColumnSet = new ColumnSet(true),
34. Criteria = new FilterExpression()
35. {
36. //Filterung. Hier werden nur Kontakte gesucht die mit dem Buchstaben I anfangen.
37. Conditions = { new ConditionExpression("fullname", ConditionOperator.Like, "I%") }
38. }
39. };
40. //Abschicken der Anfrage an den Odata von Dynamics.
41. EntityCollection contacts = serviceProxy.RetrieveMultiple(contactQuery);
42.
43. //Ausgabe der Daten über die Konsole.
44. Console.WriteLine($"{contacts.Entities.Count} Kontakte gefunden.");
45. foreach (Entity contact in contacts.Entities)
46. {
47. Console.WriteLine($"Kontakt: {contact.Attributes["fullname"]}");
48. }
49. Console.WriteLine("Drücken Sie eine beliebige Taste um Die Anwendung zu beenden.");
50. Console.ReadKey();
51. }
52. }
53. }
Ersetzen Sie die benötigten Variablen durch die in dieser Anleitung ermittelten Werte. Welche Werte in die jeweilige Variable einzutragen sind entnehmen Sie bitte den Kommentaren im Code. Nun können wir den Code im Debugger ausführen und wir bekommen eine Liste aller Kunden deren Name mit „I“ anfängt. Wenn Sie dieses Tutorial erfolgreich abgeschlossen haben, ist der Grundstein für viele weitere spannende Projekte gelegt, denn Microsoft bietet viele APIs, auf die Sie mit einer Anwendungsregistration zugreifen können. Ein Beispiel dafür ist die PowerBi-API auf die wir demnächst näher eingehen werden.