Möchte jemand über APIs Informationen aus den Microsoft 365 Diensten lesen oder bearbeiten ist eine Azure App Registration und ein Authentication-Token erforderlich. Eine Anleitung um Daten in Microsoft Graph abzufragen.
Microsoft bietet neben Graph noch weitere APIs wie SharePoint / OneDrive REST API, Management API und mehr. Für den Zugriff auf die APIs benötigt es im Azure Tenant 4 Anforderungen.
- Azure App Registration
- Client Secret oder Zertifikat
- API Berechtigungen (Delegated oder Application)
- Authentication Token für den Bezug von Informationen über die APIs
Eine Anleitung die Informationen über die APIs zu beziehen. Ist der Lesevorgang mit dem Token erfolgreich wird es mit Schreibvorgängen ebenfalls möglich sein. Im Beispiel die Microsoft Graph API. Andere APIs sind ähnlich bzw. unterscheiden sich nur Berechtigungen und der Zugangspunkt.
Azure App Registration erstellen
In der Standardkonfiguration kann jeder Account im Tenant eine Azure App Registration erstellen.
- Öffne Azure AD > App registrations.
- Erstelle eine neue Registrierung.
- Vergib einen sinnvollen, kurzen Namen der den Einsatz der App bestmöglich beschreibt.
- Wähle Single Tenant App.
- Planst du eine App mit Delegated Permissions zu erstellen benötigst du eine Redirect URI, bei Application Permissions nicht. Du könntest es später ergänzen, oder für lokale Apps zum Beispiel http://localhost/myapp/ vermerken.
- Delegated Permissions
Mit der App können Anwender Informationen in ihrem Namen abfragen und erhalten Daten auf die sie bereits berechtigt sind. - Application Permissions
Die App kann Informationen von allen Accounts abfragen, unabhängig ob der ausführende Account Berechtigungen auf die Daten hat. Ein Administrator muss diesen Berechtigungen vorab zustimmen.
- Delegated Permissions
- In meinem Beispiel möchte ich Daten von Planner Plänen abfragen.
- Nachdem die App Registration erstellt wurde zeigt es eine Application ID an. Für den Einsatz der App ist die Application ID immer erforderlich.
Client Secret oder Zertifikat erstellen
Da die Registrierung erstellt wurde ist ein Client Secret oder Zertifikat erforderlich. Es ist eine Kombination von beidem möglich, eines würde aber ausreichen. Der einfachere Weg ist Client Secret. Es gibt jedoch Aktionen die explizit eine Anmeldung via Zertifikat fordern. In solchen Fällen treten Fehler wie “Unsupported app only token” auf.
- Wähle in der App Registration im Menü “Certificate & Secrets”.
- Hier kannst du im Browser ein Zertifikat hochladen oder einen neuen Client Secret erstellen. Ein selbstsigniertes Zertifikat wäre dafür ausreichend. Wie man so ein Zertifikat manuell, oder einen Client Secret via PowerShell erstellt beschreibe ich hier. Kopiere und speichere den Wert von Client Secret. Der Wert wird einmal angezeigt und danach verschleiert.
- Für mein Beispiel nutze ich beide Optionen. Ich fügte ein Zertifikat und einen Client Secret hinzu.
Berechtigungen für die API
Im nächsten Schritt muss der App Registration mitgeteilt werden welche Daten die App im Tenant abfragen darf. Dies erfolgt über die Angabe auf was die App berechtigt ist. Zur Erinnerung, es gibt Delegated und Application Permissions.
Delegated Permissions
Mit der App können Anwender Informationen in ihrem Namen abfragen und erhalten Daten auf die sie bereits berechtigt sind.
Application Permissions
Die App kann Informationen von allen Accounts abfragen, unabhängig ob der ausführende Account Berechtigungen auf die Daten hat. Ein Administrator muss diesen Berechtigungen vorab zustimmen.
- In meinem Beispiel möchte ich Daten über Planner Pläne auslesen. Ich konsultiere die Dokumentation von Microsoft Graph, suche mir die API für “Tasks and plans” und werde “List tasks” finden. Damit kann ich Aufgaben von Planner Plänen abrufen.
- In der Dokumentation sind die notwendigen Berechtigungen vermerkt. Bei Planner ist die Situation es werden bisher nur Delegated Permissions unterstützt.
- Mit der Information kann ich in meiner App Registration im Menü “API Permissions” wählen und eine neue Berechtigungen hinzufügen.
- Im ersten Schritt lässt es wählen um welche API es geht. In meinem Fall wähle ich die erste API Microsoft Graph und dann Delegated Permissions.
- Im Suchfeld kann nach den in der Hilfe erwähnten Berechtigungen gesucht werden. Möchte man beim Dienst keine Daten verändern sind Leseberechtigungen ausreichend. Von Bedeutung ist hier noch der Hinweis “Admin consent required”. Ist dort Ja vermerkt muss der Zugriff auf die Berechtigung(en) jeweils einmalig durch einen Global Admin freigegeben werden.
Bei “Group.Read.All” sollte bedacht werden es schränkt nicht nur auf Planner ein. Selbst wenn der Einsatz nur für Planner gedacht ist lässt sich mit Group.Read.All alles was mit Gruppen zu tun hat auslesen. Über die Wahl von Delegated Permissions hätte die Person jedoch nur Zugriff auf Gruppen wo sie/er bereits Mitglied ist.
- Durch den Vermerk “Admin consent required” wird bei der Berechtigung nun ein oranger Status vermerkt sein der signalisiert ein Admin consent fehlt noch. Ein Global Admin muss sich anmelden, die App Registration öffnen und über “Grant admin consent for…” die Berechtigung erteilen. Danach wird der orange Status zu einem grünen Status. Erst mit dem Schritt wurde die Berechtigung definitiv erteilt.
Authentication Token beziehen
Als letzter Schritt fehlt der Authentication Token um über die Graph API Informationen für Planner Pläne abzurufen. Je nachdem ob Client Secret oder Zertifikat für die Authentifizierung gewählt wurde unterscheidet es sich. Ich hab dafür eine Funktion geschrieben mit der es für Client Secret und/oder Zertifikat und Delegated oder Application Permissions einen Token liefert.
- In meinem GitHub PowerShell Repository kann das Command Get-TAMSAuthToken bzw. mein Module TAMPowerShell geladen werden.
- Mit dem Command ist es einfacher und schneller möglich den Token zu beziehen. Der Token ist standardmässig 60 Minuten gültig. Ist er abgelaufen holt man sich einen neuen Token.
Beispiel über Zertifikat:
$AuthHeader = Get-TAMSAuthToken -CertThumbprint "FACA5D7AC51DC668D3E730E44B70C0AA501BB2C5" -Tenantname "[Tenantname]" -AppId "14782a87-8be3-4b7d-9b5d-f63a566bc361" -API Graph -PermissionType Delegated -AppRedirectUri "http://localhost/myapp/" -ReturnAuthHeaderBeispiel über Client Secret:
$AuthHeader = Get-TAMSAuthToken -ClientSecret "[ClientSecretKey]" -Tenantname "[Tenantname]" -AppId "14782a87-8be3-4b7d-9b5d-f63a566bc361" -API Graph -PermissionType Delegated -AppRedirectUri "http://localhost/myapp/" -ReturnAuthHeader- In beiden Beispielen liefert das Command einen Authentication Header mit der den Token enthält und für weitere Anfragen erforderlich ist.
- Über den Authentication Header ist es einfach die Graph API abzufragen. In der Hilfe von List tasks ist vermerkt die Abfrage möchte die ID des Planner Plans.
Das bedeutet die Abfrage muss in 3 Schritten erfolgen:
Schritt 1: Alle M365 Gruppen über Graph auslesen
Schritt 2: Alle Pläne der gewünschten Gruppe auslesen
Schritt 3: Alle Aufgaben des gewünschten Plans auslesen
Da der Authentication Header vorhanden ist können die Abfragen gebildet und gestellt werden. In der Dokumentation von Graph ist es beschrieben wie die Abfrage zu bilden ist. Über Get-TAMSAuthToken hat man den AuthHeader.
Wichtig ist hier vorab anzumerken. Da Planner aktuell nur Delegated Permissions unterstützt muss der ausführende Account Mitglied der Gruppe sein. Andernfalls wird es ihm mangels Berechtigungen die Daten nicht liefern.
- Schritt 1, ID der M365 Gruppe abfragen.
$RestUrl = "https://graph.microsoft.com/v1.0/groups"
$Result = Invoke-RestMethod -Method GET -uri $RestUrl -Headers $AuthHeader
$Group = $Result.value | where displayName -eq "TA-Demo"
$GroupID = $Group.id
- Schritt 2, Pläne der Gruppe abfragen.
$RestUrl = "https://graph.microsoft.com/v1.0/groups/$GroupID/planner/plans"
$Result = Invoke-RestMethod -Method GET -uri $RestUrl -Headers $AuthHeader
- Schritt 3, Aufgaben von Plan Matterhorn abfragen.
$RestUrl = "https://graph.microsoft.com/v1.0/planner/plans/ayNi-qoUOEqjSpbMbJC1lJgAFCFy/tasks"
$Result = Invoke-RestMethod -Method GET -uri $RestUrl -Headers $AuthHeaderIn meinem Beispiel ist eine Aufgabe in dem Plan vorhanden.
- Bei weiteren Microsoft Diensten und APIs ist es ähnlich und einfach weitere Abfragen über die Azure App Registration auszuführen, sofern die Berechtigungen korrekt sind.
Beachten solltest du bei Abfragen mit mehr als 100 Ergebnissen das Paging. Graph gibt standardmässig nur die ersten 100 Einträge zurück und die nächste Page für weitere Abfragen.
Ergänzung für Schreibvorgänge:
Im Beispiel waren es nur lesende Abfragen und keine Schreibvorgänge. Sofern die Berechtigungen korrekt sind ist über den Token auch ein Schreibvorgang möglich. Für Schreibvorgänge ist es eine POST, PATCH oder DELETE Methode. Am Beispiel zur Verlängerung einer M365 Gruppe beschreibt es die Dokumentation.
POST https://graph.microsoft.com/v1.0/groups/{id}/renewMit dem AuthHeader ist das erforderliche Command einfach absetzbar:
$RestUrl = "https://graph.microsoft.com/v1.0/groups/374767f3-111e-47c4-8ac8-0ccda91779fb/renew"
$Result = Invoke-RestMethod -Method POST -uri $RestUrl -Headers $AuthHeaderIn vielen Fällen ist bei Schreibvorgängen noch ein Body erforderlich der die Werte für die Anpassung inkludiert.
