Domain Scoped Roles - Early Access

Today, Cloudflare is making it easier for enterprise account owners to manage their team’s access to Cloudflare by allowing user access to be scoped to sets of domains. Ensuring users have exactly the access they need and no more is critical, and Domain Scoped Roles provide a significant step forward. Additionally, with the introduction of Domain Groups, account owners can grant users access to domains by group instead of individually. Domains can be added or removed from these groups to automatically update the access of those who have access to the group. This reduces toil in managing user access.

One of the most common uses we have seen for Domain Scoped Roles is to limit access to production domains to a small set of team members, while still allowing development and pre-production domains to be open to the rest of the team. That way, someone can’t make changes to a production domain unless they are given access.

If you are an enterprise customer please talk with your CSM to get you and your team enrolled. Note that you must have Super Administrator privileges to be able to modify account memberships.

Once the beta has been enabled for you, here is how to start using it:

• Log in to dash.cloudflare.com, select your account, and navigate to the members page.

  • From here, you can either invite a new member with a Domain Scoped Role or modify an existing user’s permissions. In this case, we will invite a new user.

• When inviting new members there are three things to provide:

  • Which users to invite.

  • The scope of which resource they will have access to:

    • Selecting “All Domains” will allow you to select legacy roles.

  • The role(s) which will decide what permissions are granted.

• Before sending the invite, you will be able to confirm the users, scope, and roles.

In addition to manually creating inclusion or exclusion lists per user, account owners can also create Domain Groups to allow granting one or more users to a group of domains. Domain Groups can be created from the member invite flow or directly from Account Configurations -> Lists. When creating a domain group, the user selects the domains to include and, from that point on, the group can be used when inviting a user to the account.

Domain Group Creation Screen

Domain Group selection during member invite

Domain Scoped Roles is possible because of a new permission system called Bach. Bach provides a policy based system for defining authorization to Cloudflare’s control plane. Authorization defines what someone can do in a system. Bach has been powering API Tokens, but going forward all authorization will use Bach. This gives customers the ability to define more granular permissions and resource scoping. Resources can be any object a user interacts with whether that be accounts, zones, worker environments, or DNS records to name a few.. Whereas before Cloudflare’s RBAC system relied on assigning a set of roles in which each role defined broad permissions that applied to an entire account, Bach’s policies allow for deeper permission grants that can be scoped to sets of resources.

Let’s take a look at the legacy system and how it compares to what Bach supports. Typically, user’s permissions are defined by the ‘roles’ that they are assigned to. These included: ‘Super Administrator’, ‘Administrator’, ‘Cloudflare for Teams’, and ‘Cloudflare Workers Admin’ to name a few. In the legacy system, each of these maps to an explicit set of simple permissions like ‘workers:read’, ‘workers:edit’ or ‘zones:edit’. When requests get made either via the Cloudflare API or the Cloudflare dashboard, Cloudflare’s API Gateway would check to see if, for the endpoint requested, an actor had the correct permissions to perform the action. In order to change a zone setting, the actor would need to have the ‘zone:edit’ permission – which could be granted from one of many roles. Below is what a user with only ‘DNS’ permissions is granted in the legacy system:

Legacy DNS User Role Permissions

Permission

Edit

Read

dns_records

✔

✔

legal

✔

account

✔

subscription

✔

zone

✔

zone_settings

✔

While straightforward, this had many drawbacks. First, this meant the inability to define limits on the resources the permissions applied to, whether that be a set of resources or attributes of resources. Second, permissions for a given ‘resource’ were simply read or edit, where edit included creating and deleting. These don’t fully capture the needs that may exist – for example, limiting deletions while allowing edits.

With Bach we have an expanded capability to define granular permissions for authorization. An example policy defining the aforementioned ‘DNS’ member’s access would look like this:

(slightly modified for readability)

#Legacy DNS Role - applies to all zones
  policies:
  - id: 186f95f3bda1443c986aeb78b05eb60b
    permission_groups:
    - id: 49ce85367bae433b9f0717ed4fea5c74
      name: DNS
      meta:
        description: Can edit DNS records.
        editable: 'false'
        label: dns_admin
        scopes: com.cloudflare.api.account
      permissions:
      - key: com.cloudflare.registrar.domain.read
      - key: com.cloudflare.registrar.domain.list
      - key: com.cloudflare.registrar.contact.read
      - key: com.cloudflare.registrar.contact.list
      - key: com.cloudflare.api.account.secondary-dns.update
      - key: com.cloudflare.api.account.secondary-dns.read
      - key: com.cloudflare.api.account.secondary-dns.delete
      - key: com.cloudflare.api.account.secondary-dns.create
      - key: com.cloudflare.api.account.zone.secondary-dns.update
      - key: com.cloudflare.api.account.zone.secondary-dns.read
      - key: com.cloudflare.api.account.zone.secondary-dns.delete
      - key: com.cloudflare.api.account.zone.secondary-dns.create
      - key: com.cloudflare.api.account.notification.*
      - key: com.cloudflare.api.account.custom-ns.update
      - key: com.cloudflare.api.account.custom-ns.list
      - key: com.cloudflare.api.account.custom-ns.*
      - key: com.cloudflare.edge.spectrum.app.list
      - key: com.cloudflare.edge.spectrum.app.read
      - key: com.cloudflare.api.account.zone.custom-page.read
      - key: com.cloudflare.api.account.zone.custom-page.list
      - key: com.cloudflare.api.account.zone.setting.read
      - key: com.cloudflare.api.account.zone.setting.list
      - key: com.cloudflare.api.account.zone.dnssec.update
      - key: com.cloudflare.api.account.zone.dnssec.read
      - key: com.cloudflare.api.account.dns-firewall.cluster.delete
      - key: com.cloudflare.api.account.dns-firewall.cluster.update
      - key: com.cloudflare.api.account.dns-firewall.cluster.read
      - key: com.cloudflare.api.account.dns-firewall.cluster.create
      - key: com.cloudflare.api.account.dns-firewall.cluster.list
      - key: com.cloudflare.api.account.zone.dns-record.delete
      - key: com.cloudflare.api.account.zone.dns-record.update
      - key: com.cloudflare.api.account.zone.dns-record.read
      - key: com.cloudflare.api.account.zone.dns-record.create
      - key: com.cloudflare.api.account.zone.dns-record.list
      - key: com.cloudflare.api.account.zone.page-rule.read
      - key: com.cloudflare.api.account.zone.page-rule.list
      - key: com.cloudflare.api.account.zone.railgun-connection.read
      - key: com.cloudflare.api.account.zone.railgun-connection.list
      - key: com.cloudflare.api.account.zone.subscription.read
      - key: com.cloudflare.api.account.zone.aml.read
      - key: com.cloudflare.api.account.zone.read
      - key: com.cloudflare.api.account.zone.list
      - key: com.cloudflare.api.account.audit-log.read
      - key: com.cloudflare.api.account.custom-page.read
      - key: com.cloudflare.api.account.custom-page.list
      - key: com.cloudflare.api.account.railgun.read
      - key: com.cloudflare.api.account.railgun.list
      - key: com.cloudflare.api.account.dpa.read
      - key: com.cloudflare.api.account.subscription.read
      - key: com.cloudflare.api.account.subscription.list
      - key: com.cloudflare.api.account.read
      - key: com.cloudflare.api.account.list
    resource_groups:
    - id: 2fe938e0a5824128bdc8c42f9339b127
      name: com.cloudflare.api.account.a67e14daa5f8dceeb91fe5449ba496eb
      meta:
        editable: 'false'
      scope:
        key: com.cloudflare.api.account.a67e14daa5f8dceeb91fe5449ba496eb
        objects:
        - key: "*"
    access: allow

You can see a greater granularity in the permissions that are defined. In both cases, the user can perform the same actions, but the granularity means we are more explicit about what can be done. Here for DNS records (under com.cloudflare.api.account.zone.dns-record) there are explicit create, read, update, delete and list permissions. In the resource group section, we can see that the scope section defines an account. Any objects like domains in that account will match to the “*” value under ‘objects’. This means that these permissions apply throughout the entire account. Now, let’s modify this user’s permissions to be scoped to a single domain and see how the policy changes.

(slightly modified for readability)

# Zone Scoped DNS role - scoped to 1 zone
policies:
- id: 80b25dd735b040708155c85d0ed8a508
  permission_groups:
  - id: 132c52e7e6654b999c183cfcbafd37d7
    name: Zone DNS
    meta:
      description: Grants access to edit DNS settings for zones in an account.
      editable: 'false'
      label: zone_dns_admin
      scopes: com.cloudflare.api.account.zone
    permissions:
    - key: com.cloudflare.api.account.zone.secondary-dns.*
    - key: com.cloudflare.api.account.zone.dnssec.*
    - key: com.cloudflare.api.account.zone.dns-record.*
    - key: com.cloudflare.api.account.zone.analytics.dns-report.*
    - key: com.cloudflare.api.account.zone.analytics.dns-bytime.*
    - key: com.cloudflare.api.account.zone.setting.read
    - key: com.cloudflare.api.account.zone.setting.list
    - key: com.cloudflare.api.account.zone.rate-plan.read
    - key: com.cloudflare.api.account.zone.subscription.read
    - key: com.cloudflare.api.account.zone.read
    - key: com.cloudflare.api.account.subscription.read
    - key: com.cloudflare.api.account.subscription.list
    - key: com.cloudflare.api.account.read
  resource_groups:
  - scope:
      key: com.cloudflare.api.account.a67e14daa5f8dceeb91fe5449ba496eb
      objects:
      - key: com.cloudflare.api.account.zone.b1fbb152bbde3bd28919a7f4bdca841f
  access: allow

Once we scope the user’s permissions to only include one explicit zone, we see two main differences. First, there is a large reduction in permissions. This is because we do not grant the user access to read or list many account level resources that the legacy account scoped roles grant. The only account level permissions granted are account.read, subscriptions.read, and subscriptions.list. These permissions are necessary for a user to be able to use the dashboard.  When viewing the account in the dashboard the only account level product that will be shown is domains. Other products like Cloudflare Workers, Zero Trust, etc will be hidden.

Second, in the resource groups scope section, we see an explicit mention of a zone (line X: com.cloudflare.api.account.zone.b1fbb152bbde3bd28919a7f4bdca841f). This means that the zone permissions outlined in the policy only apply to that specific zone. Any attempt to access other features of that zone or to modify DNS for any other zones will be rejected by Cloudflare.

If you are an enterprise customer and interested in getting started with Domain Scoped Roles, please contact your CSM to get enabled for the Early Access period. This announcement represents a significant milestone in our migration to Bach, an authorization system built for Coudflare’s scale. This will allow us to expand these same capabilities to more products in the future and to create an authorization system that puts customers more in control of their team’s access across all of Cloudflare’s services. Stay tuned as we are just getting started!