React Admin Access Control Lists (RA-ACL)

Introduction

React Admin permission management made easy. This library is heavily inspired by ra-auth-acl.

RA-ACL aims to:

• Make managing role-based permissions a breeze
• Provide declarative components to keep your code clean/maintanable

Getting Started

Initial Set up

Install with yarn add ra-access-control-lists

You'll need to create your own permissions object with the following structure

const permissions = {
  [role1]: {
    [resource1]: {
      [permission1]: boolean;
      [permission2]: boolean;
    },
    [resource2]: {
      [permission1]: boolean;
      [permission2]: boolean;
    }
  },
  [role2]: {
    [resource1]: {
      [permission1]: boolean;
      [permission2]: boolean;
    },
    [resource2]: {
      [permission1]: boolean;
      [permission2]: boolean;
    } 
  }
}

You'll then need to add the following to your authProvider.ts

import permissions from './permissions';

const authProvider = {
  // other methods
  getPermissions: () => {
    // this should be saved to local storage during login()
    const role = localStorage.getItem('role');

    const rolePermissions = permissions[role];

    return Promise.resolve(rolePermissions)
  }
}

The above is necessary to get the useACL hook working since it uses usePermissions under the hood.

With that out of the way, you're able to start using RA-ACL!

Using RA-ACL

RA-ACL exports a handy useACL function, as well as a handful of declarative components that do the heavy lifting

useACL

Scenario: You have a Posts resource. Both a user and admin can view a post, but only an admin can edit a post.

In this scenario:

• user and admin are the roles
• post is the resource
• view and edit are permissions.

With this information our permissions object will look like this:

const permissions = {
  user: {
    post: {
      view: true,
      edit: false,
    }
  },
  admin: {
    post: {
      view: true,
      edit: true,
    }
  }
}

In this scenario, we'll want to hide/show the edit button in the post's action bar based on the user's permission.

The ShowPost component will look like this:

import { Actions } from './Actions';
import { Show } from 'react-admin';

export function PostShow() {
  return (
    <Show {...props} actions={<Actions />}>
      {/* Your Show fields */}
    </Show>
  )
}

and your Action component will look like this:

import { useACL } from 'ra-access-control-lists';

export function Actions({
  resource = '',
  basePath,
  data,
}) {
  const { edit: canEdit } = useACL(resource);
  
  return (
    <TopToolbar>
      {canEdit && <EditButton basePath={basePath} record={data} />}
    </TopToolbar>
  )
}

If you're logged in as an admin, you'll see the edit button no-problemo. If you're logged in as a user, you won't see the edit button. You can run the example to see this in action. Details here

WithPermission Components

RA-ACL also exports a handful of out-of-the-box components that handle the useACL logic.

These are:

• FieldWithPermission
• ResourceWithPermission
• TabWithPermission

FieldWithPermission

A generic wrapper over any field component, that will hide/show that field based on the specified resource and permission.

Scenario: You have a date field that you only want to display to people with post edit (for some reason).

In your PostShow component, add the following with the rest of your fields

<FieldWithPermission
  options={{
    resource: 'posts',
    permission: 'edit',
  }}
  Input={DateField}
  inputProps={{
    showTime: true,
  }}
  label="Date"
  source="attributes.createdAt"
/>

FieldWithPermission takes all of the props that FieldProps does, as well as a few additions. These additional props are:

type FieldWithPermissionProps<T> = {
  options: {
    resource: string;
    permission: PermissionKey;
  };
  inputProps: T;
  Input: (props: FieldProps & T) => JSX.Element;
};

In our example, the Input prop is the React component DateField. And inputProps takes DateField's props.

ResourceWithPermission

A generic wrapper over React Admin's Resource component. This will hide/show resources in the side Menu based on the specified resource and permission.

Scenario: You have a users resource that only an admin can access

After setting up your permissions accordingly, you can add the following to your Admin component at the root of your React Admin tree.

<ResourceWithPermission
  name="users"
  list={UserShow}
/>

You can also supply some options in the event that you want to target manage permissions where the resource name is different to the name property. This can be achieved by doing:

<ResourceWithPermission
  name="users"
  list={UserShow}
  options={{
    resource: "admin",
  }}
/>

TabWithPermission

A wrapper over React Admin's Tab component, and behaves exactly like the FieldWithPermission component.

Example

To run the example you need to:

cd example yarn yarn start

which will run the repo on localhost:1234

This is a pared down version of RA's simple example.

Points of interest

• useAcl is used in ShowActions to hide/show the EditButton
• TabWithPermission is used in PostShow to hide/show the comments tab
• ResourceWithPermission is used in the index file to hide/show resources in the Menu.
• FieldWithPermission is used in PostList to hide/show the EditButton.
• FieldWithPermission is used in PostList to hide/show the EditButton.
• FieldWithPermission is used in the PostShow to hide/show the SelectField