Migrate Terraform identity resources to IAM v2

This page describes how to move Terraform configurations that manage users, groups, service principals, group memberships, entitlements, and workspace assignments from the System for Cross-domain Identity Management (SCIM) resources to the identity and access management (IAM) v2 resources. The migration imports existing identities into the new resources. If the configuration keeps username unchanged, no identity is deleted or re-created.

For scripts that call the SCIM APIs, the SDKs, or the Databricks CLI, see Migrate SCIM API calls to IAM v2.

Requirements

• Databricks Terraform provider 1.141.0 and above.
• Terraform 1.7 and above, for the removed block. The import blocks need Terraform 1.5 and above. With older versions of Terraform, use terraform import and terraform state rm instead.

Resource mapping

Each IAM v2 resource has a workspace-level version, databricks_workspace_iam_*_v2, which uses a provider configured for a workspace, and an account-level version, databricks_account_iam_*_v2, which uses a provider configured for the account. Users, groups, and service principals belong to the account, whichever version you use. A databricks_group that uses a workspace-level provider is a workspace-local group, which the IAM v2 resources don't manage. Keep it as is, or migrate it to an account group first.

SCIM-based resource	IAM v2 resource	Import ID (workspace / account)
databricks_user	databricks_workspace_iam_user_v2, databricks_account_iam_user_v2	users/<id> / accounts/<account-id>/users/<id>
databricks_group	databricks_workspace_iam_group_v2, databricks_account_iam_group_v2	groups/<id> / accounts/<account-id>/groups/<id>
databricks_service_principal	databricks_workspace_iam_service_principal_v2, databricks_account_iam_service_principal_v2	service-principals/<id> / accounts/<account-id>/service-principals/<id>
databricks_group_member	databricks_workspace_iam_direct_group_member_v2, databricks_account_iam_direct_group_member_v2	groups/<group-id>/direct-members/<member-id> / accounts/<account-id>/groups/<group-id>/direct-members/<member-id>
databricks_entitlements and the entitlement arguments on users, groups, and service principals	databricks_workspace_iam_workspace_assignment_v2, databricks_account_iam_workspace_assignment_v2	workspace-assignments/<principal-id> / accounts/<account-id>/workspaces/<workspace-id>/workspace-assignments/<principal-id>
databricks_permission_assignment, databricks_mws_permission_assignment	databricks_workspace_iam_workspace_assignment_v2, databricks_account_iam_workspace_assignment_v2	Same as the previous row
active on a workspace-level databricks_user or databricks_service_principal	databricks_workspace_iam_workspace_identity_detail_v2	principals/<principal-id>/workspace-identity-detail

SCIM-based resource	IAM v2 resource	Import ID (workspace / account)
databricks_user	databricks_workspace_iam_user_v2, databricks_account_iam_user_v2	users/<id> / accounts/<account-id>/users/<id>
databricks_group	databricks_workspace_iam_group_v2, databricks_account_iam_group_v2	groups/<id> / accounts/<account-id>/groups/<id>
databricks_service_principal	databricks_workspace_iam_service_principal_v2, databricks_account_iam_service_principal_v2	service-principals/<id> / accounts/<account-id>/service-principals/<id>
databricks_group_member	databricks_workspace_iam_direct_group_member_v2, databricks_account_iam_direct_group_member_v2	groups/<group-id>/direct-members/<member-id> / accounts/<account-id>/groups/<group-id>/direct-members/<member-id>
databricks_entitlements and the entitlement arguments on users, groups, and service principals	databricks_workspace_iam_workspace_assignment_v2, databricks_account_iam_workspace_assignment_v2	workspace-assignments/<principal-id> / accounts/<account-id>/workspaces/<workspace-id>/workspace-assignments/<principal-id>
databricks_permission_assignment, databricks_mws_permission_assignment	databricks_workspace_iam_workspace_assignment_v2, databricks_account_iam_workspace_assignment_v2	Same as the previous row
active on a workspace-level databricks_user or databricks_service_principal	databricks_workspace_iam_workspace_identity_detail_v2	principals/<principal-id>/workspace-identity-detail

The IDs are the same IDs that the SCIM-based resources store in id, so you can build each import ID from the existing resource. Each import ID is the object's name in the IAM v2 API. For the fields of each object, see the IAM v2 API reference, such as the Workspace User API and the Account User API.

Each resource also has a data source with the same name, which looks up one object by its name, and a plural data source, such as databricks_workspace_iam_users_v2, which lists objects and accepts a filter. To look up a principal from your identity provider by its external ID, use the databricks_*_iam_external_user_v2, databricks_*_iam_external_group_v2, and databricks_*_iam_external_service_principal_v2 data sources.

Attribute mapping

The IAM v2 resources rename some arguments and move entitlements to the workspace assignment.

SCIM-based argument	IAM v2 argument
databricks_user.user_name	username
databricks_user.display_name	full_name = { given_name, family_name }
databricks_user.active, databricks_service_principal.active on the account	account_user_status, account_sp_status (ACTIVE or INACTIVE)
databricks_group.display_name	group_name
databricks_service_principal.display_name	display_name
databricks_service_principal.application_id	Read-only application_id attribute. The server generates it.
external_id	external_id
databricks_group_member.group_id	parent, set to the name attribute of the IAM v2 group
databricks_group_member.member_id	principal_id
workspace_access, workspace_consume, databricks_sql_access, allow_cluster_create, allow_instance_pool_create	entitlements list on the workspace assignment: WORKSPACE_ACCESS, WORKSPACE_CONSUME, DATABRICKS_SQL_ACCESS, ALLOW_CLUSTER_CREATE, ALLOW_INSTANCE_POOL_CREATE
permissions = ["USER"] on a permission assignment	entitlements with the entitlements the principal needs, such as ["WORKSPACE_ACCESS"]
permissions = ["ADMIN"] on a permission assignment	entitlements = ["WORKSPACE_ADMIN"]

SCIM-based argument	IAM v2 argument
databricks_user.user_name	username
databricks_user.display_name	full_name = { given_name, family_name }
databricks_user.active, databricks_service_principal.active on the account	account_user_status, account_sp_status (ACTIVE or INACTIVE)
databricks_group.display_name	group_name
databricks_service_principal.display_name	display_name
databricks_service_principal.application_id	Read-only application_id attribute. The server generates it.
external_id	external_id
databricks_group_member.group_id	parent, set to the name attribute of the IAM v2 group
databricks_group_member.member_id	principal_id
workspace_access, workspace_consume, databricks_sql_access, allow_cluster_create, allow_instance_pool_create	entitlements list on the workspace assignment: WORKSPACE_ACCESS, WORKSPACE_CONSUME, DATABRICKS_SQL_ACCESS, ALLOW_CLUSTER_CREATE, ALLOW_INSTANCE_POOL_CREATE
permissions = ["USER"] on a permission assignment	entitlements with the entitlements the principal needs, such as ["WORKSPACE_ACCESS"]
permissions = ["ADMIN"] on a permission assignment	entitlements = ["WORKSPACE_ADMIN"]

The IAM v2 resources have no equivalent for force, disable_as_user_deletion, home, repos, acl_principal_id, workspace-local groups, or the instance profile and role resources. Keep the SCIM-based resources for those. A SCIM-based resource and an IAM v2 resource, such as databricks_user and databricks_workspace_iam_user_v2, can manage the same identity, so you can keep the SCIM-based resource next to the IAM v2 resource instead of replacing it with a removed block.

Migrate a resource

For each resource, write the IAM v2 resource, import the existing object into it, and remove the SCIM-based resource from state without deleting the object.

Add the IAM v2 resource

Add the IAM v2 resource with the same values as the SCIM-based resource.

Add an import block

Add an import block that points the IAM v2 resource at the existing object.

Replace the SCIM-based resource with a removed block

Replace the SCIM-based resource with a removed block that has destroy = false. If you keep the SCIM-based resource for arguments that IAM v2 doesn't support, skip this step.

Check the plan

Run terraform plan. Check that the plan only imports the IAM v2 resources and forgets the SCIM-based resources. If it plans to change an imported resource, update the arguments to match the existing object, such as the entitlements of a workspace assignment, and run the plan again.

Apply the changes

Run terraform apply.

Remove the import and removed blocks

Remove the import and removed blocks.

After the apply, Terraform manages the identities through the IAM v2 resources, and the identities and their access are unchanged. A new terraform plan shows no changes.

Example: a group, a member, and a workspace assignment

The following configuration uses an account-level provider and SCIM-based resources:

Hcl

resource "databricks_group" "eng" {
  display_name = "data-engineers"
}

resource "databricks_user" "jane" {
  user_name    = "jane.doe@example.com"
  display_name = "Jane Doe"
}

resource "databricks_group_member" "jane_eng" {
  group_id  = databricks_group.eng.id
  member_id = databricks_user.jane.id
}

resource "databricks_mws_permission_assignment" "eng" {
  workspace_id = var.workspace_id
  principal_id = databricks_group.eng.id
  permissions  = ["USER"]
}

To migrate it, replace it with the following configuration. Replace <group-id> and <user-id> with the id values from terraform state show.

Hcl

locals {
  account   = "accounts/${var.account_id}"
  workspace = "accounts/${var.account_id}/workspaces/${var.workspace_id}"
}

resource "databricks_account_iam_group_v2" "eng" {
  parent     = local.account
  group_name = "data-engineers"
}

resource "databricks_account_iam_user_v2" "jane" {
  parent              = local.account
  username            = "jane.doe@example.com"
  account_user_status = "ACTIVE"
  full_name = {
    given_name  = "Jane"
    family_name = "Doe"
  }
}

resource "databricks_account_iam_direct_group_member_v2" "jane_eng" {
  parent       = databricks_account_iam_group_v2.eng.name
  principal_id = databricks_account_iam_user_v2.jane.user_id
}

resource "databricks_account_iam_workspace_assignment_v2" "eng" {
  parent       = local.workspace
  principal_id = databricks_account_iam_group_v2.eng.group_id
  entitlements = ["WORKSPACE_ACCESS"]
}

import {
  to = databricks_account_iam_group_v2.eng
  id = "${local.account}/groups/<group-id>"
}

import {
  to = databricks_account_iam_user_v2.jane
  id = "${local.account}/users/<user-id>"
}

import {
  to = databricks_account_iam_direct_group_member_v2.jane_eng
  id = "${local.account}/groups/<group-id>/direct-members/<user-id>"
}

import {
  to = databricks_account_iam_workspace_assignment_v2.eng
  id = "${local.workspace}/workspace-assignments/<group-id>"
}

removed {
  from = databricks_group.eng
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_user.jane
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_group_member.jane_eng
  lifecycle {
    destroy = false
  }
}

removed {
  from = databricks_mws_permission_assignment.eng
  lifecycle {
    destroy = false
  }
}

For a workspace-level provider, use the databricks_workspace_iam_*_v2 resources, leave out parent on users, groups, service principals, and workspace assignments, and use the workspace-level import IDs from the resource mapping table.

Behavior differences

• Destroy deletes from the account: Destroying a databricks_workspace_iam_*_v2 user, group, or service principal deletes it from the account and every workspace, as described in Migrate SCIM API calls to IAM v2. To remove a principal from one workspace only, destroy its workspace assignment. Changing username replaces the resource, which deletes the identity and creates a new one, so don't change username on a migrated identity.
• Workspace access and identities from your identity provider: A databricks_workspace_iam_*_v2 user, group, or service principal is added to the account only, so add a workspace assignment for each principal that needs workspace access. Identities from your identity provider follow the same rules as in the IAM v2 APIs. See Migrate SCIM API calls to IAM v2.
• Workspace deactivation: databricks_workspace_iam_workspace_identity_detail_v2 already exists for every user and service principal in the workspace, so you import it instead of creating it. Set workspace_identity_status to INACTIVE to deactivate the principal in this workspace only. You can't change the status of the user you're signed in as.

Additional resources

• • Migrate SCIM API calls to IAM v2
  • Move scripts that call the SCIM APIs, the Databricks SDKs, or the Databricks CLI to the IAM v2 APIs.
• • Databricks Terraform provider
  • Manage Databricks workspaces and cloud infrastructure with Terraform.