Notable Graph API additions for Summer 2023

As Microsoft continues to expand the functionality of the Graph API, it’s time for another look at some recently released endpoints. In this article, we will examine a set of new “admin” endpoints, as well as few interesting additions on Azure AD’s side of things. Most of these are quite small and don’t deserve their own blog post. Let’s dig in.

On the “admin” front, four new endpoints have been released, as follows:

• Todo – view and set settings for the ToDo app
• Forms –  view and set settings for the Forms app
• AppsAndServices – view and set generic M365 settings, such as access to the Office store or trial subscriptions
• Dynamics – view and set settings for Dynamics 365, currently covers only Customer Voice

Each of the aforementioned endpoints comes with its own “read-only” and “write” scopes, in the form of OrgSettings-blabla.Read.All and OrgSettings-blabla.ReadWrite.All, respectively. Both delegate and application permissions are supported. A GET request will show you the current settings, whereas a PATCH request can be used to update them. Let’s see some examples.

To get the current Forms configuration, one can issue a GET request against  the /admin/forms endpoint:

GET https://graph.microsoft.com/beta/admin/forms

The set of settings currently supported is listed here. As you can see, they closely resemble the settings we can configure via the Microsoft 365 Admin Center (under Settings > Org settings > Microsoft Forms), with only the Allow respondents to edit their responses setting currently missing. To update the value of a given setting, we can use a PATCH request as follows:

PATCH https://graph.microsoft.com/beta/admin/forms

{
    "settings": {
        "isBingImageSearchEnabled": false
    }
}

The rest of the endpoints work in a similar manner, so there is little value in adding additional examples. Refer to the documentation articles linked above if you need more details. As already mentioned, you can also use application permissions and query said endpoints outside of the Graph Explorer tool. Here’s a “raw” PowerShell example:

$uri = "https://graph.microsoft.com/beta/admin/forms"
$Gr = Invoke-WebRequest -Headers $AuthHeader1 -Uri $uri -Verbose -Debug
$Gr.Content

{  "value": {    "@odata.type": "#microsoft.graph.adminTodo",     "id": "9b13e840-31a8-2ed4-57d8-22f42c130334",     "settings": {       "@odata.type": "microsoft.graph.todoSettings",       "isPushNotificationEnabled": true,       "isExternalJoinEnabled": true,       "isExternalShareEnabled": true    }   }

 

Switching gears, a new endpoint has been introduced to provide SLA reporting information, namely /reports/sla. Currently, only the Azure AD SLA info is exposed, via the /reports/sla/azureADAuthentication node, but we might be getting the generic Microsoft 365 SLAs added later on. Anyway, to query the SLA info, you will need the Reports.Read.All scope, with both delegate and application permissions supported. Here’s an example:

GET https://graph.microsoft.com/beta/reports/sla/azureADAuthentication

 

Lastly, some work has been going on under the /reports node in order to bring the Azure AD reports experience in line with the rest of the suite. If you haven’t used those reports for a while, I’d recommend taking a look at the updated documentation. The rework includes the deprecation of the old /reports/credentialUserRegistrationDetails endpoint and its replacement with the /reports/authenticationMethods/userRegistrationDetails one, which you can use both to get the details for a given user (via a /reports/authenticationMethods/userRegistrationDetails/{userId} query) or list them all. In addition, some new properties and better filtering capabilities have been introduced.

Few “curated” views have also been provided, such as the User registered by feature one, which you can get to via the /reports/authenticationMethods/usersRegisteredByFeature endpoint. This report gives you a quick count of users capable of performing MFA, SSPR or passwordless authentication within your tenant. Currently, only delegate permissions are supported on said endpoint, and you will need the AuditLog.Read.All scope.

To get the data, issue a GET request against the /reports/authenticationMethods/usersRegisteredByFeature endpoint (/v1.0 is also supported):

GET https://graph.microsoft.com/v1.0/reports/authenticationMethods/usersRegisteredByFeature

As shown on the screenshot above, the reports gives some stats about the state of MFA/SSPR/passwordless enablement within the organization. In my tenant, 16 out of 66 users have bothered to configure their SSPR details, 12 to set up MFA and only 3 are capable of passwordless authentication. While the report doesn’t give any additional details, those counts can be useful as a quick overview of the tenant’s posture.

Per-method stats can be obtained via the “sister” Users registered by method view, exposed via the /reports/authenticationMethods/usersRegisteredByMethod endpoint. Both these reports expose two additional parameters you can leverage, namely includedUserRoles (with acceptable values of user, admin, privilegedAdmin or All) and includedUserTypes (with acceptable values of member, guest or all). That’s at least according to the official documentation, as in reality only the all value seems to work currently. Nevertheless, here’s how to query the usersRegisteredByMethod report via PowerShell:

$uri = "https://graph.microsoft.com/beta/reports/authenticationMethods/usersRegisteredByMethod(includedUserTypes='all',includedUserRoles='all')"
$Gr = Invoke-WebRequest -Headers $AuthHeader1 -Uri $uri -Verbose -Debug
($Gr.Content | ConvertFrom-Json).userRegistrationMethodCounts

authenticationMethod userCount
-------------------- ---------
password 0
email 2
mobilePhone 8
alternateMobilePhone 0
officePhone 0
microsoftAuthenticatorPush 6
softwareOneTimePasscode 6
hardwareOneTimePasscode 0
microsoftAuthenticatorPasswordless 1
windowsHelloForBusiness 3
fido2SecurityKey 1
temporaryAccessPass 0
securityQuestion 0