Skip to main content

Azure Service Principal

Kostavo connects to Azure Databricks workspaces using a Microsoft Entra ID (Azure AD) service principal. This guide covers the exact permissions required and the setup steps.

Required Permissions​

Create a custom role in Azure that grants these two permissions:

PermissionPurpose
Microsoft.Databricks/workspaces/readRead workspace metadata and discover workspaces
Microsoft.Databricks/workspaces/assignWorkspaceAdmin/actionGrant the service principal workspace-admin access to monitor and manage resources

These are the minimum permissions Kostavo needs. The service principal does not need Contributor, Owner, or any other built-in Azure role.

Step 1: Create an App Registration​

  1. Go to the Azure Portal → Microsoft Entra ID → App registrations
  2. Click New registration
  3. Name it (e.g., kostavo-service-principal)
  4. Leave the default settings and click Register
  5. Copy the Application (client) ID and Directory (tenant) ID; you'll need both

Step 2: Create a Client Secret​

  1. In the App Registration, go to Certificates & secrets
  2. Click New client secret
  3. Set a description and expiry
  4. Click Add
  5. Copy the secret Value immediately; it's only shown once. Do not copy the Secret ID.

Step 3: Create the Custom Role​

  1. Go to Subscriptions → select your subscription → Access control (IAM)
  2. Click Add → Add custom role
  3. Name it (e.g., Kostavo Databricks Access)
  4. Switch to the JSON tab and add these permissions:
{
  "permissions": [
    {
      "actions": [
        "Microsoft.Databricks/workspaces/read",
        "Microsoft.Databricks/workspaces/assignWorkspaceAdmin/action"
      ],
      "notActions": [],
      "dataActions": [],
      "notDataActions": []
    }
  ]
}
  1. Set the assignable scope to the subscription or resource group containing your Databricks workspaces
  2. Click Review + create

Step 4: Assign the Role​

Assign the custom role to your service principal at the appropriate scope:

Subscription level (recommended; enables auto-discovery of all workspaces):

  1. Go to Subscriptions → select your subscription → Access control (IAM)
  2. Click Add → Add role assignment
  3. Select your custom role (Kostavo Databricks Access)
  4. Under Members, select User, group, or service principal
  5. Search for your App Registration name and select it
  6. Click Review + assign

Resource group level (limits scope to workspaces in that resource group):

Same steps, but navigate to the specific resource group instead of the subscription.

Step 5: Add to Kostavo​

In the Kostavo onboarding wizard or the Credentials page, create a new Azure credential with:

FieldValue
Client IDApplication (client) ID from Step 1
Tenant IDDirectory (tenant) ID from Step 1
Client SecretSecret value from Step 2

The new credential form filled with Azure service principal details

After saving, the credential is ready to use. The first real test is workspace enrollment: with a correct role assignment, auto-discovery lists the workspaces the service principal can read. If discovery comes up empty, see Troubleshooting.

Scope and Discovery​

Assignment ScopeAuto-DiscoveryWorkspace Access
SubscriptionAll workspaces in subscriptionAll workspaces in subscription
Resource GroupWorkspaces in that resource groupWorkspaces in that resource group
Individual WorkspaceNo discoveryOnly the assigned workspace

For most setups, subscription-level assignment is recommended: it allows Kostavo to discover new workspaces automatically as they're created.

Secret Rotation​

When the client secret approaches expiry:

  1. Create a new secret in the Azure App Registration
  2. Update the credential in Kostavo with the new secret value
  3. Delete the old secret from Azure once Kostavo is using the new one

See Managing credentials for the in-app rotation flow.