Title: Automate Hawk Permissions Configuration – Two Approaches

Feature

Provide two separate methods to automate Hawk’s permissions setup:

1. Goose-Style App Registration – Creating an Azure AD application, service principal, and assigning required Graph/Exchange roles.
2. Custom Azure RBAC Role Script – Creating a JSON-based custom Azure role for Hawk (in addition to any needed Graph/M365 assignments).

What problem would this feature solve?

Currently, setting up Hawk’s permissions requires multiple manual steps:

• Granting Microsoft Graph permissions (admin consent).
• Assigning Exchange Online roles (view-only, etc.).
• Optionally creating an Azure RBAC custom role for resource-level access.
  By introducing these two automation options, we can:

1. Let users quickly generate an application/service principal with the required privileges (like Goose).
2. Or let them create a custom role definition (via JSON template) if they only need Azure RBAC permissions.

Clear description of the current limitation/problem

• Users must handle permissions for Hawk via a piecemeal, manual process in Azure AD, Exchange Admin Center, and Azure Portal.
• There is no out-of-the-box script that either bundles all the app registration + role assignments (Goose approach) or guides them through a custom RBAC role JSON creation.

Proposed Solution

Approach A (Goose-Style):

• Adapt the Goose script approach to Hawk.
  • Create or update an Azure AD App Registration for Hawk.
  • Assign Graph permissions, request admin consent automatically (if run by a Global Admin).
  • Create and assign Exchange Online roles if needed.
  • Optionally assign an Azure subscription role (e.g., Reader) if Hawk needs resource-level read.

Approach B (Custom RBAC Role Script):

• Provide a JSON template that defines a custom Hawk role (e.g., Hawk Reader).
• Include a PowerShell script to deploy this custom role via New-AzRoleDefinition.
• This approach may not cover Graph or Exchange permissions, so the user would still need to grant those permissions manually or via a separate script.

How would you like this to work?

1. Approach A:

   • Run a single PowerShell script (Create_Hawk_SP.ps1 -AppName HawkApp -Create) that sets up the service principal, assigns all Graph/Exchange roles, and outputs the client secret and IDs for Hawk’s config.
   • A -Delete switch to remove the entire registration, roles, etc., if needed.

2. Approach B:

   • User runs a script that references a JSON file (e.g., HawkRole.json) containing an Azure custom role definition.
   • The script applies this custom role at the subscription or resource group scope.
   • The user still must handle Graph and Exchange roles separately.

⚙️ Developer Section (For Hawk Team Members Only)

Technical Requirements

1. Goose-Style Script

   • Must install necessary modules (Az.Resources, Microsoft.Graph, ExchangeOnlineManagement).
   • Must create an App Registration, a Service Principal, assign Graph permissions, optionally Exchange roles, and possibly subscription-level Reader roles.
   • Must output the Tenant ID, App ID, and generated secret for Hawk usage.

2. Custom RBAC Role Script

   • Must include a JSON template for a Hawk Reader role (or specialized minimal set of actions).
   • Must include a PowerShell script calling New-AzRoleDefinition -InputFile .\HawkRole.json.
   • Must validate user input for the subscription scope, role name, etc.

3. Separation of Concerns

   • The Goose-style script (Approach A) is all-in-one for those who want a single approach to set up everything at once.
   • The custom role script (Approach B) focuses solely on Azure role definitions, for users who prefer more granular or existing processes for Graph/Exchange.

Implementation Approach

1. Approach A (Goose-Style):

   • Clone or adapt the existing Goose script logic:
     • Update $permissions hashtable for Hawk’s needed Graph scopes.
     • Update $exchange_roles if Hawk needs Exchange read-only roles.
     • Prompt user for subscription assignment (or skip if only Graph/Exchange is needed).
     • Provide a -Create and -Delete functionality.

2. Approach B (Custom RBAC Role Script):

   • Provide a role definition JSON:

     {
       "Name": "Hawk Investigator",
       "IsCustom": true,
       "Description": "Allows read access to Azure resources for Hawk",
       "Actions": [
         "*/read"
       ],
       "AssignableScopes": [
         "/subscriptions/{SUBSCRIPTION_ID}"
       ]
     }

   • Create a simple .ps1 that takes user input for subscription ID, merges it into the JSON, and executes New-AzRoleDefinition.

Acceptance Criteria

• Approach A:

  • Running Create_Hawk_SP.ps1 -Create successfully sets up an AAD app with Graph permissions, Exchange roles (optional), and an Azure subscription role (optional).
  • Produces a client secret, logs the App ID, and prints final instructions for Hawk usage.
  • Deleting works with -Delete, removing the app registration and roles.

• Approach B:

  • Running the custom RBAC script successfully creates a new “Hawk Investigator” role at the specified subscription or resource group scope.
  • The user can see the custom role in the Azure portal and assign it.
  • Graph and Exchange permissions remain separate.