Microsoft Graph API Device Management

Microsoft Graph API Device Management provides tools for managing and securing devices via the Microsoft Graph API.

Microsoft Graph API Device Management provides a comprehensive interface for managing Intune devices and retrieving BitLocker recovery keys. This integration allows Swimlane Turbine users to seamlessly automate device management tasks, such as listing managed devices and retrieving critical recovery keys, enhancing operational efficiency and security posture. By leveraging this connector, users can streamline device management processes and ensure quick access to essential device information, all within the Swimlane Turbine platform.

Prerequisites

Before you can use the Microsoft Graph API Device Management connector for Turbine, you'll need access to the Microsoft Graph API. This requires the following:

Delegated flow authentication using the following parameters:

URL: The endpoint for Microsoft Graph API.

Tenant ID: The directory tenant identifier.

Username: The username for authentication.

Password: The password for authentication.

Client ID: The application client identifier.

Client Secret: The application client secret.

OAuth2 refresh token authentication using the following parameters:

URL: The endpoint for Microsoft Graph API.

Client ID: The application client identifier.

Client Secret: The application client secret.

OAuth2 client credentials authentication using the following parameters:

URL: The endpoint for Microsoft Graph API.

Client ID: The application client identifier.

Client Secret: The application client secret. ... and so on

Capabilities

This Connector provides the following capabilities:

List Managed Devices

List Managed Devices For Detected App

List Managed Devices For User Detected App

Get BitLocker Recovery Key

Limitations

The Get BitLocker Recovery Key endpoint only supports delegated permissions; the application permission flow is not supported by Microsoft Graph for this resource.

The key property of the recovery key is only returned when the request explicitly selects it via the $select=key query parameter; auditing is generated each time the key value is read.

Microsoft Graph paginates large result sets via @odata.nextLink; iterate the List Managed Devices action using $top and $skip (or follow @odata.nextLink) to retrieve all devices.

Asset Setup

Create a new asset of type OAuth 2.0 Delegated Flow Authentication and provide:

URL – Base URL for Microsoft Graph (defaults to https://graph.microsoft.com).

Login URL – Microsoft identity platform login URL (defaults to https://login.microsoftonline.com).

Tenant ID – Directory (tenant) ID of the Entra ID tenant.

Username / Password – Credentials of the delegated user account that has the required Intune and BitLocker permissions.

Client ID / Client Secret – Application (client) ID and client secret of the registered Entra ID application.

Scopes – Defaults to https://graph.microsoft.com/.default, which honors the delegated permissions configured on the application registration.

If the test connection fails, double-check that admin consent has been granted for the DeviceManagementManagedDevices.Read.All and BitLockerKey.Read.All delegated permissions and that the user account is licensed for Intune.

Tasks Setup

List Managed Devices – Calls GET /deviceManagement/managedDevices. No path or query parameters are required; do not supply a request body.

List Managed Devices For Detected App – Calls GET /deviceManagement/detectedApps/{detectedAppId}/managedDevices. Requires the detectedAppId path parameter; do not supply a request body.

List Managed Devices For User Detected App – Calls GET /deviceManagement/detectedApps/{detectedAppId}/managedDevices/{managedDeviceId}/users/{userId}/managedDevices. Requires detectedAppId, managedDeviceId, and userId path parameters; do not supply a request body.

Get BitLocker Recovery Key – Requires the bitlockerRecoveryKeyId path parameter and a User-Agent header value supplied by the caller (for example, Dsreg/10.0 (Windows 10.0.19043.1466)). The optional ocp-client-name and ocp-client-version headers may also be supplied for debugging purposes. Set the $select query parameter to key to return the actual recovery key value; doing so triggers a Microsoft Entra audit log entry under the KeyManagement category.

Notes

Microsoft Graph List ManagedDevices reference: https://learn.microsoft.com/en-us/graph/api/intune-devices-manageddevice-list?view=graph-rest-1.0

Microsoft Graph Get bitlockerRecoveryKey reference: https://learn.microsoft.com/en-us/graph/api/bitlockerrecoverykey-get?view=graph-rest-1.0

Configurations

Password Grant (Delegated Authentication)

Authenticates on behalf of a user using oauth 2.0 credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
login_url		string	Optional
tenant_id		string	Required
oauth_un	The username for authentication	string	Required
oauth_pwd	The password for authentication	string	Required
oauth_cl_id	The client ID	string	Required
oauth_cl_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token_url	Must start with https://login.microsoftonline.com/ and then continue with the tenant_id, and then be prepended with /oauth2/v2.0/token	string	Required
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	List of permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

MS Graph OpenID Connect Refresh Token Grant

Authenticates using refresh token.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
cl_id	The client ID.	string	Required
cl_secret	The client secret.	string	Required
refresh_token	Refresh Token.	string	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Get BitLocker Recovery Key

Retrieve a BitLocker recovery key using its identifier from Microsoft Graph API Device Management. Requires the bitlockerRecoveryKeyId as a path parameter.

Endpoint

URL: v1.0/informationProtection/bitlocker/recoveryKeys/{{bitlockerRecoveryKeyId}}

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.bitlockerRecoveryKeyId	string	Required	Unique identifier of the BitLocker recovery key.
parameters.$select	string	Optional	Set to key to include the recovery key value.

Input Example

{"path_parameters":{"bitlockerRecoveryKeyId":"string"},"parameters":{"$select":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code returned by the Graph API call.
reason	string	HTTP reason phrase associated with the response status.
headers	object	HTTP response headers returned by the Graph API.
@odata.context	string	OData metadata reference URL for the response.
value	object	BitLocker recovery key object returned by Microsoft Graph.
[email protected]	string	OData type identifier for the BitLocker recovery key.
value.id	string	Unique identifier of the BitLocker recovery key.
value.createdDateTime	string	Timestamp when the BitLocker recovery key was created.
value.volumeType	string	Volume type associated with the BitLocker recovery key.
value.deviceId	string	Identifier of the device associated with the key.
value.key	string	BitLocker recovery key value, returned when select is used.

Output Example

{"@odata.context":"string","value":{"@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","volumeType":"string","deviceId":"string","key":"string"}}

List Managed Devices

List properties and relationships of Intune managed device objects in Microsoft Graph API Device Management.

Endpoint

URL: v1.0/deviceManagement/managedDevices

Method: GET

Output

Parameter	Type	Description
status_code	number	HTTP status code returned by the Graph API call.
reason	string	HTTP reason phrase associated with the response status.
headers	object	HTTP response headers returned by the Graph API.
@odata.context	string	OData metadata reference URL for the response.
@odata.count	number	Total number of items matching the query.
@odata.nextLink	string	URL used to retrieve the next page of results.
value	array	Collection of managed device objects returned by Intune.
[email protected]	string	OData type identifier for the managed device resource.
value.id	string	Unique identifier of the managed device record.
value.userId	string	Identifier of the user assigned to the device.
value.deviceName	string	Display name configured for the managed device.
value.managedDeviceOwnerType	string	Ownership type of the device, company or personal.
value.deviceActionResults	array	Results of recent remote actions issued on the device.
[email protected]	string	OData type identifier for the device action result.
value.deviceActionResults.actionName	string	Name of the action issued on the device.
value.deviceActionResults.actionState	string	Current state of the issued device action.
value.deviceActionResults.startDateTime	string	Timestamp when the device action was initiated.
value.deviceActionResults.lastUpdatedDateTime	string	Timestamp when the device action status last changed.
value.managementState	string	Current management state reported by Intune.
value.enrolledDateTime	string	Timestamp when the device was enrolled in Intune.
value.lastSyncDateTime	string	Timestamp of the last successful Intune sync.
value.operatingSystem	string	Operating system installed on the managed device.
value.complianceState	string	Compliance status of the device against assigned policies.
value.jailBroken	string	Indicates whether the device has been jailbroken.
value.managementAgent	string	Management channel currently controlling the device.

Output Example

{"@odata.context":"string","@odata.count":123,"@odata.nextLink":"string","value":[{"@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","userId":"string","deviceName":"Example Name","managedDeviceOwnerType":"string","deviceActionResults":[],"managementState":"string","enrolledDateTime":"string","lastSyncDateTime":"string","operatingSystem":"string","complianceState":"string","jailBroken":"string","managementAgent":"string","osVersion":"string","easActivated":true}]}

List Managed Devices For Detected App

List managed devices with a specific detected app installed in Microsoft Graph API Device Management. Requires the detectedAppId as a path parameter.

Endpoint

URL: v1.0/deviceManagement/detectedApps/{{detectedAppId}}/managedDevices

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.detectedAppId	string	Required	Identifier of the detected application in Intune.

Input Example

{"path_parameters":{"detectedAppId":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code returned by the Graph API call.
reason	string	HTTP reason phrase associated with the response status.
headers	object	HTTP response headers returned by the Graph API.
@odata.context	string	OData metadata reference URL for the response.
@odata.count	number	Total number of items matching the query.
@odata.nextLink	string	URL used to retrieve the next page of results.
value	array	Collection of managed device objects returned by Intune.
[email protected]	string	OData type identifier for the managed device resource.
value.id	string	Unique identifier of the managed device record.
value.userId	string	Identifier of the user assigned to the device.
value.deviceName	string	Display name configured for the managed device.
value.managedDeviceOwnerType	string	Ownership type of the device, company or personal.
value.deviceActionResults	array	Results of recent remote actions issued on the device.
[email protected]	string	OData type identifier for the device action result.
value.deviceActionResults.actionName	string	Name of the action issued on the device.
value.deviceActionResults.actionState	string	Current state of the issued device action.
value.deviceActionResults.startDateTime	string	Timestamp when the device action was initiated.
value.deviceActionResults.lastUpdatedDateTime	string	Timestamp when the device action status last changed.
value.managementState	string	Current management state reported by Intune.
value.enrolledDateTime	string	Timestamp when the device was enrolled in Intune.
value.lastSyncDateTime	string	Timestamp of the last successful Intune sync.
value.operatingSystem	string	Operating system installed on the managed device.
value.complianceState	string	Compliance status of the device against assigned policies.
value.jailBroken	string	Indicates whether the device has been jailbroken.
value.managementAgent	string	Management channel currently controlling the device.

Output Example

List Managed Devices For User Detected App

List managed devices for a user related to a detected app in Microsoft Graph API Device Management. Requires path parameters: detectedAppId, managedDeviceId, and userId.

Endpoint

URL: v1.0/deviceManagement/detectedApps/{{detectedAppId}}/managedDevices/{{managedDeviceId}}/users/{{userId}}/managedDevices

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.detectedAppId	string	Required	Identifier of the detected application in Intune.
path_parameters.managedDeviceId	string	Required	Identifier of the managed device used as scope.
path_parameters.userId	string	Required	Identifier of the user related to the device.

Input Example

{"path_parameters":{"detectedAppId":"string","managedDeviceId":"string","userId":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code returned by the Graph API call.
reason	string	HTTP reason phrase associated with the response status.
headers	object	HTTP response headers returned by the Graph API.
@odata.context	string	OData metadata reference URL for the response.
@odata.count	number	Total number of items matching the query.
@odata.nextLink	string	URL used to retrieve the next page of results.
value	array	Collection of managed device objects returned by Intune.
[email protected]	string	OData type identifier for the managed device resource.
value.id	string	Unique identifier of the managed device record.
value.userId	string	Identifier of the user assigned to the device.
value.deviceName	string	Display name configured for the managed device.
value.managedDeviceOwnerType	string	Ownership type of the device, company or personal.
value.deviceActionResults	array	Results of recent remote actions issued on the device.
[email protected]	string	OData type identifier for the device action result.
value.deviceActionResults.actionName	string	Name of the action issued on the device.
value.deviceActionResults.actionState	string	Current state of the issued device action.
value.deviceActionResults.startDateTime	string	Timestamp when the device action was initiated.
value.deviceActionResults.lastUpdatedDateTime	string	Timestamp when the device action status last changed.
value.managementState	string	Current management state reported by Intune.
value.enrolledDateTime	string	Timestamp when the device was enrolled in Intune.
value.lastSyncDateTime	string	Timestamp of the last successful Intune sync.
value.operatingSystem	string	Operating system installed on the managed device.
value.complianceState	string	Compliance status of the device against assigned policies.
value.jailBroken	string	Indicates whether the device has been jailbroken.
value.managementAgent	string	Management channel currently controlling the device.

Output Example

Response Headers

Header	Description	Example
Content-Type	The media type of the resource	application/json
Date	The date and time at which the message was originated	Thu, 01 Jan 2024 00:00:00 GMT