Introduction
Azure Sentinel is a nested resource on top of a Log Analytics workspace, which introduces some complexity in managing the Azure Sentinel resource on its own. Up until now, onboarding to Azure Sentinel required performing multiple API calls to multiple endpoints. When done by the UI the complexity is hidden from end user but for API users, this created complexities.
To overcome this, we introduce a dedicated endpoint called “OnboardingStates”. This endpoint allows managing the Azure Sentinel instance seamlessly on a workspace through the API. The endpoint provides a single source of truth for performing the different operations required for a complete creation/deletion (aka onboarding/offboarding) of Azure Sentinel on a workspace.
How to use the new API
This new API, now in public preview, is documented in our preview API documentation:
https://github.com/Azure/azure-rest-api-specs/blob/master/specification/securityinsights/resource-ma...
Some examples on how to use this new API can be found here:
https://github.com/Azure/azure-rest-api-specs/tree/master/specification/securityinsights/resource-ma...
Migration to the new model
During the public preview stage both the previous API method and the new API method will work seamlessly. No existing usage will be broken, and customers can expect all current flows to work as expected. The UI component itself has already been changed to use the new API call.
Once this API goes to general availability (GA), we will deprecate the current API. We will communicate beforehand to customers regularly using the old method, but customers are expected to start using the new method no later than September 10th 2021.
Note on the SecurityInsights solution
As part of onboarding to Azure Sentinel, the SecurityInsights solution is installed on the Log Analytics workspace. If you had the chance to manage your Azure Sentinel resource(s) using the API in the past, you might have manually installed/removed the SecurityInsights solution on/from the workspace. As part of introducing the new OnboardingStates API, this manual management of the solution will no longer be supported. Hence, you should neither install nor remove the SecurityInsights solution directly. Instead, either use the Azure Portal or the OnboardingStates endpoints to manage Azure Sentinel on a workspace.
The statement above also applies to the current methods to install the SecurityInsights solution via ARM template (using Microsoft.OperationsManagement/solutions resource type) or PowerShell (using New-AzMonitorLogAnalyticsSolution cmdlet). The new OnboardingStates endpoint is already available to be used in ARM templates (see a sample here) and we expect to add PowerShell support soon as part of the Az.SecurityInsights module.
Additional resources
