Skip to main content
Last updated on

Change default workspace access to Consumer access

Preview

This feature is in Public Preview.

This page explains how workspace admins can change the default workspace access for new users to Consumer access by using group cloning. This feature helps you streamline consumer onboarding at scale while maintaining appropriate access levels for users who need authoring privileges.

Overview​

By default, every user added to a workspace becomes a member of the system users group. This group typically has Workspace access or Databricks SQL access entitlements, which are authoring entitlements that allow users to create and modify workspace objects.

To provide users with a view-only Consumer experience, the users group must have only Consumer entitlement. Entitlements are additive, so Consumer access provides the simplified view-only experience only when it's the sole entitlement assigned to a user. Group cloning lets you make this change without disrupting existing users who need authoring privileges. It creates a new group for existing users and updates the default users group for new users.

For more information about Consumer access and its capabilities, see What is consumer access?. To learn more about entitlements, see Manage entitlements.

When to use this feature​

Use this feature when:

  • You want new workspace users to default to Consumer access only.
  • You need to separate users who need authoring privileges (Workspace or Databricks SQL access) from view-only consumers.
  • You want to streamline consumer onboarding at scale.

How group cloning works​

The system users group is automatically managed by Databricks and includes all workspace users. This group can't be deleted. To learn more about system groups, see Group sources.

When you clone the users group:

  1. A new group is created with the same entitlements that the users group currently has.
  2. All existing workspace users are automatically moved to the cloned group, ensuring they retain their current access levels.
  3. The users group is updated to have only Consumer entitlement.
  4. Future users who are added to the workspace automatically become members of the users group and receive only Consumer entitlement.

When the users group contains nested groups that are too deeply nested (groups that are members of other groups), you can choose how to handle them:

  • Add all group members directly (Recommended): Adds all members of the nested group directly to the cloned group. This simplifies the group structure.
  • Exclude: Skips the nested group entirely. Members of the excluded nested group aren't added to the cloned group.

Requirements​

To change the default workspace access, you must be a workspace admin.

Change default workspace access using the UI​

To change the default workspace access to Consumer access:

  1. As a workspace admin, log in to the Databricks workspace.

  2. Click your username in the top bar of the Databricks workspace and select Settings.

  3. Click the Advanced tab.

  4. Under Access control, next to Change default workspace access to consumer access, click Open.

  5. In the dialog, enter a name for the cloned group. This group will contain all existing users who need to retain their current entitlements.

    Change default access to consumer access.

  6. Click Create and clone group.

    The system creates the new group and begins the cloning process. Do not close the modal while cloning is in process.

  7. If the users group contains nested groups that are too deeply nested, you're prompted to handle them.

    • Select Add all group members directly (Recommended) to flatten the group by adding all members of the nested group directly to the cloned group.
    • Select Exclude this group to skip this nested group.
    • Optionally, select Apply this decision to all future groups that exceed the nesting depth limit to use your choice for all future nested groups during this operation.

  8. In Final step: move authoring permissions and change default access, click Finish.

    The system updates the users group to have only Consumer entitlement and assigns the original entitlements to the cloned group.

  9. Review the summary and click Done.

    Change default access to consumer access.

Verify the changes​

After completing the process, verify that the changes were applied correctly:

  1. As a workspace admin, log in to the Databricks workspace.
  2. Click your username in the top bar and select Settings.
  3. Click the Identity and access tab.
  4. Next to Groups, click Manage.
  5. Verify the following:
    • The cloned group exists and has the same number of users as the original users group.
    • The users group now has only the Consumer entitlement.

Considerations and best practices​

Consider the following when changing default workspace access:

  • Impact on new users: After you change the default access, all new users added to the workspace receive only Consumer entitlement. They can view and interact with dashboards, Genie spaces, and Databricks Apps shared with them, but can't create new workspace objects. Their default Databricks landing page is the Databricks One page. For more information, see What is consumer access? and What is Databricks One?.

  • Granting authoring privileges: When you need to grant higher privileges to new users, you must manually add them to the cloned group or assign additional entitlements individually. For instructions on managing group membership, see Manage groups.

  • Reverting the changes: If you need to revert this configuration, grant Workspace access and Databricks SQL access entitlements back to the users group. New users then receive these entitlements by default. You can keep or delete the cloned group depending on whether you still need it for organizing users.

  • Coordination with identity providers: If you use SCIM provisioning or automatic identity management to sync users and groups, coordinate this change with your identity management processes. See Sync users and groups from your identity provider using SCIM.

Automate group cloning using the SDK​

For bulk operations or automation across multiple workspaces, you can use the Databricks SDK for Python to automate the group cloning process. This method is useful when you need to apply the same configuration across multiple workspaces or integrate group cloning into infrastructure-as-code workflows.

The following Python script automates duplicating the users group and assigns appropriate entitlements. It uses the Databricks SDK for Python and requires a service principal with administrator privileges for both the account and the workspace, authenticated using OAuth. See Authorize user access to Databricks with OAuth.

Prerequisites​

  • Service principal with admin rights
  • Environment variables set:
    • DATABRICKS_ACCOUNT_ID (UUID from account console URL)
    • DATABRICKS_WORKSPACE_ID (numerical ID from workspace URL)
    • DATABRICKS_CLIENT_ID (service principal client ID)
    • DATABRICKS_CLIENT_SECRET (service principal client secret)

Example script​

Python

import os
import databricks.sdk as dbx
from databricks.sdk.service import iam

# Set the Databricks account host URL for your account's cloud
DATABRICKS_HOST = "https://accounts.gcp.databricks.com"

# Fetch credentials from environment variables
DATABRICKS_ACCOUNT_ID = os.getenv("DATABRICKS_ACCOUNT_ID")
DATABRICKS_WORKSPACE_ID = os.getenv("DATABRICKS_WORKSPACE_ID")
DATABRICKS_CLIENT_ID = os.getenv("DATABRICKS_CLIENT_ID")
DATABRICKS_CLIENT_SECRET = os.getenv("DATABRICKS_CLIENT_SECRET")

# Initialize Databricks account client
account_client = dbx.AccountClient(
    host=DATABRICKS_HOST,
    account_id=DATABRICKS_ACCOUNT_ID,
    client_id=DATABRICKS_CLIENT_ID,
    client_secret=DATABRICKS_CLIENT_SECRET,
)

print(f"Authenticated to Databricks account {DATABRICKS_ACCOUNT_ID}")

# Get workspace and initialize workspace client
workspace = account_client.workspaces.get(workspace_id=DATABRICKS_WORKSPACE_ID)
workspace_name = workspace.workspace_name
workspace_client = account_client.get_workspace_client(workspace)

print(f"Authenticated to Databricks workspace {DATABRICKS_WORKSPACE_ID}, '{workspace_name}'")

def get_workspace_group(group_name):
    """
    Fetches the workspace group with the given name.
    """
    group = list(workspace_client.groups.list(filter=f"displayName eq '{group_name}'"))[0]
    print(f"Found workspace group: {group.display_name}")
    print(f"Workspace {group.display_name} has {len(group.members)} members")
    return group

def clone_workspace_group_to_account(workspace_group_name, new_account_group_name):
    workspace_group = get_workspace_group(workspace_group_name)
    group = account_client.groups.create(
        display_name=new_account_group_name, members=workspace_group.members
    )
    print(f"Created account group: {new_account_group_name}")
    print(f"Cloned workspace group {workspace_group.display_name} to account group {group.display_name}")
    print(f"Account {group.display_name} has {len(group.members)} members")
    return group

def add_account_group_to_workspace(account_group, workspace):
    permissions = account_client.workspace_assignment.update(
        workspace_id=workspace.workspace_id,
        principal_id=account_group.id,
        permissions=[iam.WorkspacePermission.USER],
    )
    print(f"Added account group {account_group.display_name} to workspace {workspace.workspace_id}, {workspace.workspace_name}")
    return permissions

# Clone workspace 'users' group to new account group '{workspace_name}-contributors'
account_group = clone_workspace_group_to_account(
    "users", f"{workspace_name}-contributors"
)

# Add account group '{workspace_name}-contributors' to the workspace
permissions = add_account_group_to_workspace(account_group, workspace)

After you run the script to duplicate your existing groups and reassign permissions, grant Consumer access to the users group so that new users are automatically granted that access.

note

Adjust group names and entitlements for your organization's policies and naming conventions. Always test changes in a non-production environment before applying them broadly.

What's next​

After changing the default workspace access, you might want to: