Databricks Service Principals for Practice and Exams: Machine Accounts, Automation, Delegated Permissions

Are your production jobs and CI/CD pipelines still authenticating with "somebody's personal account"? When that engineer leaves, their token is revoked and every pipeline depending on it grinds to a halt — this is a real incident that happens at many organizations.Service Principals solve this problem by acting as machine-only identities. They are used by applications, automation processes, and CI/CD tools — not humans — to call the Databricks API.

This article walks through everything you need from both practical and exam perspectives (Data Engineer Associate / Professional): creating Service Principals, OAuth M2M authentication, granting Unity Catalog permissions, CI/CD integration, and how they compare to PATs.

What is a Service Principal?

A Service Principal is a non-human security principal managed at the Databricks account level. Just like a human user, it can be granted permissions via Unity Catalog GRANT/REVOKE, and its operations are recorded in the audit logs. The main differences from human users are:

• No interactive login (UI/SSO). Authenticates only via API.
• Identified by an Application ID, not a personal email address.
• Not affected by people leaving or moving teams. Eliminates the risk of pipelines stopping due to HR changes.
• Makes it easy to apply the principle of least privilege — scope permissions only to the tables and jobs that are actually needed.

How to Create a Service Principal

There are three ways to create a Service Principal. Choose based on the size of your environment and operational policy.

Method 1: Databricks UI (Admin Console)

Account Console → User Management → Service Principals → Add service principal. Best suited for small environments and initial validation. You can also assign the SP to workspaces from the UI.

Method 2: SCIM API (Programmatic)

# Create a Service Principal via the SCIM API
curl -X POST "https://accounts.cloud.databricks.com/api/2.0/accounts/<account_id>/scim/v2/ServicePrincipals" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "cicd-pipeline-sp",
    "entitlements": [
      { "value": "workspace-access" }
    ]
  }'

# Extract applicationId from the response
# → "applicationId": "12345678-abcd-efgh-ijkl-123456789012"

Method 3: Terraform (IaC-Managed)

resource "databricks_service_principal" "cicd_sp" {
  display_name = "cicd-pipeline-sp"
}

resource "databricks_service_principal_role" "cicd_sp_role" {
  service_principal_id = databricks_service_principal.cicd_sp.id
  role                 = "roles/workspace.user"
}

# Assign the SP to a workspace
resource "databricks_mws_permission_assignment" "cicd_ws" {
  workspace_id = var.workspace_id
  principal_id = databricks_service_principal.cicd_sp.id
  permissions  = ["USER"]
}

Terraform is the most recommended approach for managing Service Principals in production. Creation, permission grants, and workspace assignment are all managed as code, with full change history tracked in Git.

OAuth M2M Token Acquisition Flow

For Service Principals calling the Databricks API, OAuth Machine-to-Machine (M2M) is the recommended authentication method. It is based on the OAuth 2.0 Client Credentials Grant flow.

# Step 1: Generate a secret for the Service Principal (Account Console or API)
# → Client ID: <application_id>
# → Client Secret: <generated_secret>

# Step 2: Request a token from the OAuth token endpoint
curl -X POST "https://<workspace_url>/oidc/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<application_id>" \
  -d "client_secret=<generated_secret>" \
  -d "scope=all-apis"

# Step 3: Use the access_token from the response for API calls
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIs...",
#   "token_type": "Bearer",
#   "expires_in": 3600
# }

# Step 4: Call the API with the acquired token
curl -X GET "https://<workspace_url>/api/2.0/clusters/list" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."

OAuth M2M tokens have a built-in expiration (1 hour by default) and must be re-acquired when they expire. This avoids the risk of holding long-lived tokens like PATs and provides a significant security advantage.

Granting Unity Catalog Permissions

Granting Unity Catalog permissions to a Service Principal uses the same GRANT statements as for human users. Following the principle of least privilege, grant SELECT/MODIFY only on the tables the job actually accesses.

-- Grant least-privilege permissions to an ETL job SP
GRANT USAGE ON CATALOG production TO `cicd-pipeline-sp`;
GRANT USAGE ON SCHEMA production.sales TO `cicd-pipeline-sp`;
GRANT SELECT ON TABLE production.sales.raw_orders TO `cicd-pipeline-sp`;
GRANT MODIFY ON TABLE production.sales.cleaned_orders TO `cicd-pipeline-sp`;

-- Permission to create new tables in the schema
GRANT CREATE TABLE ON SCHEMA production.sales TO `cicd-pipeline-sp`;

-- Verify granted permissions
SHOW GRANTS TO `cicd-pipeline-sp`;

CI/CD Integration (GitHub Actions Example)

An example of triggering a Databricks job from GitHub Actions. Store the Service Principal's Client ID and Client Secret in GitHub Secrets, and acquire an OAuth token inside the workflow.

# .github/workflows/deploy-databricks-job.yml
name: Deploy Databricks Job
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Databricks CLI
        run: pip install databricks-cli
      - name: Configure Databricks Auth
        env:
          DATABRICKS_HOST: ${{ secrets.DATABRICKS_HOST }}
          DATABRICKS_CLIENT_ID: ${{ secrets.SP_CLIENT_ID }}
          DATABRICKS_CLIENT_SECRET: ${{ secrets.SP_CLIENT_SECRET }}
        run: |
          databricks configure --host $DATABRICKS_HOST \
            --client-id $DATABRICKS_CLIENT_ID \
            --client-secret $DATABRICKS_CLIENT_SECRET
      - name: Deploy Job
        run: databricks jobs create --json @job-definition.json

PAT vs OAuth M2M Comparison

Least-Privilege Design Best Practices

• Separate Service Principals by purpose: create dedicated SPs for ETL, model serving, CI/CD, etc., and grant each only the minimum permissions it needs.
• Do not use ALL PRIVILEGES: granting ALL PRIVILEGES for convenience dramatically widens the blast radius if the SP's credentials are ever leaked.
• Do not use PATs for production automation: restrict PATs to personal development and debugging, and use OAuth M2M for automation.
• Store Client Secrets in a secret store: store them in Databricks Secret Scope or a cloud secret manager (AWS Secrets Manager / Azure Key Vault). Never hard-code them in source or CI/CD configuration.
• Periodic review: periodically review Service Principals and their permissions, and disable any SPs that are no longer in use.

Exam Focus Areas

Service Principals are an important topic on both Data Engineer Associate and Professional exams. Lock in these patterns:

• "How do you securely call the Databricks API from a CI/CD pipeline?" → Service Principal + OAuth M2M
• "How do you prevent jobs from breaking when an engineer leaves?" → Use a Service Principal instead of a PAT
• "Which principal is specified for a job cluster in Single User mode?" → The job owner or a Service Principal
• "How do you allow a Service Principal to access a table?" → GRANT USAGE + GRANT SELECT

Check Your Understanding

Frequently Asked Questions