Blog Post

Microsoft Sentinel Blog
3 MIN READ

What's new: Azure Sentinel new onboarding/offboarding API

Ely_Abramovitch's avatar
Ely_Abramovitch
Icon for Microsoft rankMicrosoft
Aug 16, 2021

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-manager/Microsoft.SecurityInsights/preview/2021-03-01-preview/OnboardingStates.json 

 

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-manager/Microsoft.SecurityInsights/preview/2021-03-01-preview/examples/onboardingStates 

 

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 

Updated Nov 03, 2021
Version 2.0
microsoft sentinel
  • laithhisham's avatar
    laithhisham
    Icon for Microsoft rankMicrosoft
    Nov 08, 2022

    igorlozalab3 

    The OnboardingStates endpoint does not support managing the SKU directly, however you can still issue a call to the Microsoft.OperationsManagement/solutions to manage the SKU. The important point is that installing the solution on its own will no longer be considered a valid onboarding of a workspace to Sentinel, you will need to also issue a call to Microsoft.SecurityInsights/onboardingStates/default in order to complete the onboarding process. Otherwise, the calls to Sentinel's RP will fail.

    The deprecation will be of the legacy support of reaching Sentinel's RP after having only the solution installed and without defining the OnboardingStates. In that case you will start getting BadRequest (WorkspaceNotOnboarded).

    Hope this clarifies the change.

  • TokeSR's avatar
    TokeSR
    Copper Contributor
    Aug 25, 2021

    Hey Ely_Abramovitch , this solution works fine for me when the subscription is not a new one, but if I want to use it on a virgin subscription I get an internal server error.

    I use ARM template (subscriptionDeploymentTemplate.json) to deploy a resource group, then create a LAW in it and then enable Sentinel on it. When I use the older solution (Microsoft.OperationsManagement/solutions) it works just fine, I can deploy the above-mentioned resources. But if I try to use the new solution (Microsoft.OperationalInsights/workspaces/providers/onboardingStates) then I get this:

     

    {
    "status": "Failed",
    "error": {
    "code": "InternalServerError",
    "message": "Internal server error"
    }
    }

     

    The resource group is still deployed, I can also see the LAW being deployed, but the Sentinel is not enabled because of this error.
    I assume this is not a normal behavior. If needed I can share my code somewhere.

  • laithhisham's avatar
    laithhisham
    Icon for Microsoft rankMicrosoft
    Apr 07, 2022

    TokeSR 

    This is probably due to the missing RP registration for the new subscription. Please make sure to register the subscription for the Microsoft.SecurityInsights Resource Provider before deploying the ARM template of the onboarding.

    There was an issue hiding the indicative error message there but should now be fixed.

     

  • igorlozalab3's avatar
    igorlozalab3
    Copper Contributor
    Nov 08, 2022

    Hey Ely_Abramovitch,

     

    Do you know if the new endpoint supports SKU? We are currently deploying 'solution' through bicep with SKU and are hoping not to lose the functionality of setting Sentinel SKU? 

     

    Also, when you say the you will deprecate the current API after GA, are you referring to: Microsoft.OperationsManagement/solutions for sentinel json/bicep deployments?

     

    Appreciate any assistance with this query.