Skip to main content

Assign roles by group name
App

Connect docs via MCP

The User Role Sync app maps Atlan group memberships to roles and sub-roles, so each user's Atlan role stays in sync with their group assignments automatically. Use it when group membership is your source of truth for "who should be an admin, member, or guest". For example, the data-admins group should always have the Admin role. The app supports exact matches and regex patterns, plus a role-hierarchy setting that decides which role wins when a user belongs to multiple mapped groups.

Prerequisites​

Before you set up the workflow, make sure:

  • The User Role Sync app is enabled for your tenant. If you don't see it under New workflow, contact Atlan Support and request access. See the reference page for details.
  • You are an admin in Atlan and can configure workflows. See Assign roles.
  • You have a personal API token generated from your Atlan profile. The workflow uses it to authenticate when applying role updates.
  • All the Atlan groups you plan to map exist. See Organize teams in groups.

Set up workflow​

  1. In your Atlan workspace, click Connectors in the left sidebar.

    If you are using the Old UI (Classic), click New Workflow in the top navigation.

  2. Search for User Role Sync, then click Set up workflow on the tile. The workflow configuration screen opens.

  3. In the Workflow name field, enter a descriptive name. For example:

    prod-user-role-sync

  4. In the Authentication section, paste your personal API token. The workflow needs this to authenticate when applying role updates to users.

Define role mapping rules​

After authentication is set, define how group memberships map to roles. This also controls precedence when a user belongs to multiple groups, and lets you optionally assign sub-roles.

  1. Choose a Selection mode:

    • List: Enter exact, comma-separated group names. Use this when you have a known set of groups.

      data-admins,analytics-leads

    • Regex: Enter a regular expression that matches multiple group names. Use this when groups follow a naming convention. The same pattern applies across all role fields. Common patterns:

      PatternMatches
      ^team-.*Any group starting with team-
      .*-admins$Any group ending in -admins (for example, data-admins, cloud-admins)
      ^[a-z]{3}-ops$Exactly three lowercase letters then -ops (for example, eng-ops, dev-ops)
      (?i)^atlan_admin(_.*)?$Case-insensitive match for atlan_admin and any suffix

  2. Choose a Role hierarchy that decides when a user belongs to multiple mapped groups.

    The default Guest → Member → Admin assigns the most restrictive role. For example, if a user is in both guests (mapped to Guest) and data-admins (mapped to Admin), they receive Guest.

    Other orderings are available if you need to prioritize differently. For example, Admin → Member → Guest always assigns the most permissive role. See Role hierarchy for all options.

  3. In the Admin group field, enter the groups whose members should receive the Admin role.

    List example:

    data-admins,analytics-leads

    Regex example:

    .*-admins$
    Watch for regex overlap with sub-role groups

    If your Admin regex is broad (for example, (?i)^atlan_admin(_.*)?$), it may accidentally match sub-role groups like atlan_admin_workflow and assign them the Admin role instead of their intended sub-role. To exclude specific sub-role groups from the Admin match, narrow your regex:

    (?i)^atlan_admin(?!_(workflow|governance))(_.*)?$

  4. To delegate sub-roles, set Admin Sub Role Option to Static. This lets you assign fixed sub-roles to specific groups.

  5. In the Workflow Admin (sub-role) Group field, enter the groups whose members should receive the workflow-admin sub-role:

    engineering-ops-admins

  6. In the Governance Admin (sub-role) Group field, enter the groups whose members should receive the governance-admin sub-role:

    data-governance-leads

  7. In the Admin Sub Role hierarchy field, define sub-role precedence. If a user qualifies for both, the one listed first wins:

    workflow-admin,governance-admin

    To define flexible sub-roles on a per-workflow basis instead of fixed ones, set Admin Sub Role Option to Dynamic and configure up to five custom sub-roles. See the reference for the dynamic configuration fields.

  8. In the Member group field, enter the groups whose members should receive the Member role:

    data-analysts,reporting-team

  9. In the Guest group field, enter the groups whose members should receive the Guest role, typically external viewers or contractors:

    viewers,contractors

  10. Schedule and run the workflow. Run it manually for a one-time backfill, or set a recurring schedule so role assignments stay aligned with group membership over time.

Need help?​

If you run into issues configuring the app, contact Atlan Support for assistance.

See also​