The release of ContraForce V2.0.0 includes multiple service principals that need to be consented by users of ContraForce. This article will cover how to consent each of the service principals.
Overview
ContraForce has service principals dedicated to the various features of the ContraForce Platform. The use of multiple service principals follows Microsoft Entra ID best practices and defense-in-depth measures. Additionally it gives ContraForce users very granular control over what ContraForce has access to in your environment.
How to Consent
Global admin users can consent to the new ContraForce service principals from the ContraForce Portal Settings -> Permissions page. This page can be accessed from clicking the Settings icon outlined with a rounded yellow box below. From there, navigate to the Permissions tab highlighted with a yellow oval below as well.
The Portal Permissions page displays a listing of the new ContraForce service principals - many of which will display two buttons, one for consenting to delegated permissions and the other for consenting to application permissions.
Which button should I click?
For tenants whose incidents and/or Gamebooks are managed by a service provider, click on the Partner Consent button to grant application permissions. Otherwise, click the Consent button.
What happens when I click Consent?
When the appropriate consent button is clicked, you will be directed through a Microsoft Entra (formerly Azure Active Directory) Admin consent flow. You will be asked to select the Microsoft Work account through which you would like to grant consent, and then you will be prompted with a dialog asking if you will grant consent for the service principal and its needed permissions - in this example, ContraForce Sentinel Hunting.
Once you have consented to that service principal and its requested permissions, you will be directed back to the Portal, and will briefly see a spinning progress indicator as we process the result
After a few moments, you may be redirected back to a Microsoft Entra admin consent flow that requests permission for two applications: the ContraForce API and the new service principal. This is because now that a new service principal has been provisioned, the ContraForce API is requesting permission to call the new service principal's APIs.
After this consent has been granted, the Consent button you clicked from the Permissions page should no longer be clickable.
What service principals should I consent to?
-
All existing users should have a global admin consent to ContraForce Sentinel Hunting and ContraForce User Management.
-
If you currently use the Endpoints page, please also consent to ContraForce for MDE.
-
If you use Gamebooks, please consent to the ContraForce Gamebooks for Identity and ContraForce Gamebooks for MDE service principals.
New Service Principal Descriptions
ContraForce services use the ContraForce API service principal whenever we call another API service, such as the Microsoft Graph or Azure Resource Manager. The ContraForce API calls other ContraForce service principals and occasionally direct resource endpoints (such as when calling the Azure Resource Manager endpoints with the user_impersonation scope during onboarding).
This service principal requires three admin Read-Only Microsoft Graph scopes to validate the presence of ContraForce service principals in a Microsoft Entra tenant and to validate appropriate role assignment for each.
Note that the ContraForce API and Portal have been components of ContraForce pre V2.0.0 and have been previously consented.
The ContraForce Portal service principal is used to facilitate a small web client that integrates with the Microsoft identity platform’s implementation of OpenID Connect for signing in a tenant’s users and reading basic profile information about the signed-in user. Other API actions, even when initiated in the ContraForce Portal, are handled by the ContraForce API service principal.
ContraForce Sentinel Hunting (New)
The ContraForce Sentinel Hunting service principal is used to call the Log Analytics API with the Data.Read scope. In the delegated, on-behalf-of flow, this allows the ContraForce Sentinel Hunting service principal to send direct queries to a Sentinel Workspace on behalf of the signed in user. We use this for providing deeper incident context via raw event/”evidence” logs, and for running queries from the Advanced Hunting Sentinel page.
The ContraForce for MDE service principal is used to facilitate visibility and management access for Microsoft Defender for Endpoint data. This is used in the Portal Endpoints page, where MDE data is aggregated.
ContraForce User Management (New)
The ContraForce User Management service principal carries out user management functionality features supported from the Portal. These features include adding users to a Microsoft Entra ID security group that will be given access to the onboarded Sentinel’s Workspace; removing users from the security group; and assigning different Portal Roles to them.
ContraForce Gamebooks for Identity (New)
The ContraForce Gamebooks for Identity service principal is used to authorize Gamebook executions that target User entities. Specfically, the service principal requires User.ReadWrite.All and User.AuthenticationMethod.ReadWrite.All scopes. By default, the scopes are requested with a delegated permission type - that is, for use in on-behalf-of flows, which requires a signed-in user to be present. However, the service principal can also be granted application permissions that are able to run without a user present (except for Password Reset, which always requires use of delegated type permissions).
ContraForce Gamebooks for MDE (New)
The ContraForceGamebooks for MDE service principal is used to authorize MDE Gamebook executions that target Endpoint entities. Specifically, quaranting files, scanning devices, and isolating hosts from a network are the supported actions. By default, consent can be granted for this service principal with delegated type permissions; however, application type permissions can be consented as well, which allow for ContraForce services to run these gamebook actions in a customer’s tenant without a service provider’s user having to be present in their customer’s tenant.