react-abac

Attribute Based Access Control and Role Based Access Control for React.

Installing

npm install react-abac

Example

An example implementation can be found on codesandbox.io.

Tutorial

A short tutorial video is available.

Usage

import * as React from "react";
import { AbacProvider, AllowedTo } from "react-abac";

interface User {
    uuid: string;
    roles: Role[];
    permissions: permissions[];
}

interface Post {
    owner: string; // user uuid
}

// an object with all permissions
enum permissions {
    EDIT_POST = "EDIT_POST",
}

enum Role {
    ADMIN = "ADMIN",
    USER = "USER",
}

// rules describing what roles have what permissions
const rules = {
    [Role.ADMIN]: {
        [permissions.EDIT_POST]: true,
    },
    [Role.USER]: {
        // an abac rule
        // user can only edit the post if it is the owner of it
        [permissions.EDIT_POST]: (post, user) => post.owner === user.uuid,
    },
};

interface Props {
    user: User;
    post: Post;
}

const App = (props: Props) => (
    // Add an AbacProvider somewhere near the root of your component tree
    // where you have access to the logged in user
    <AbacProvider
        user={props.user}
        roles={props.user.roles}
        rules={rules}
        permissions={props.user.permissions}
    >
        <EditPost post={props.post} />
    </AbacProvider>
);

const EditPost = (props: { post: { owner: string } }) => (
    // restrict parts of the application using the AllowedTo component
    <AllowedTo
        // can be an array too, in which case the user must have all permissions
        perform={permissions.EDIT_POST}
        // optional, data to pass to abac rules as first argument
        data={props.post}
        // both no and yes props are optional
        no={() => <span>Not allowed to edit post</span>}
        //yes={() => <span>Allowed to edit post</span>}
    >
        {/* the yes prop will default to rendering the children */}
        <span>Allowed to edit post</span>
    </AllowedTo>
);

See the ./example directory for a full example. This example is deployed here.

API reference

Functions

create

The create function allows you to create a new instance of the library, this allows you to run multiple instances completely separated from each other within the same application.

This is especially useful when developing a library that uses react-abac internally but you want consuming applications to use their own react-abac configuration.

Example usage

export const {
    AllowedTo,
    secured,
    NotAllowedTo,
    AbacContextDefaults,
    AbacProvider,
    AbacContext,
    useAbac,
} = create<Role, Permission, User>();

Components

AbacProvider

The AbacProvider is used to provide the AllowedTo component and the useAbac hook with access to the logged in user and the permission rules.

Props

name	type	required	description
rules	`object`	yes	An object describing the permission rules, see the Rules section.
user	`object`	no	The logged in user.
roles	`string[]`	no	The roles of the logged in user.
permissions	`string[]`	no	The permissions of the logged in user.

Example usage

interface Props {
    user: User;
    post: Post;
}

const App = (props: Props) => (
    // Add an AbacProvider somewhere near the root of your component tree
    // where you have access to the logged in user
    <AbacProvider
        user={props.user}
        roles={props.user.roles}
        rules={rules}
        permissions={props.user.permissions}
    >
        <EditPost post={props.post} />
    </AbacProvider>
);

AllowedTo

The AllowedTo component is used to restrict certain component trees based on whether the logged in user is allowed access.

Props

name	type	required	description
perform	`string` or `string[]`	yes	A single permission or a list of permissions, if a list is provided all permissions are required.
yes	`React.ComponentType`	no	The jsx element to render if permission is granted.
no	`React.ComponentType`	no	The jsx element to render if permission is not granted.
data	`any`	no	Data to pass to abac rules as first argument. E.g. When editing a post you might want to pass the post model as data so the abac rule can check if the post is owned by the logged in user.

Example usage

const EditPost = (props: { post: { owner: string } }) => (
    // restrict parts of the application using the AllowedTo component
    <AllowedTo
        // can be an array too, in which case the user must have all permissions
        perform={permissions.EDIT_POST}
        // optional, data to pass to abac rules as first argument
        data={props.post}
        // both no and yes props are optional
        no={() => <span>Not allowed to edit post</span>}
        //yes={() => <span>Allowed to edit post</span>}
    >
        {/* the yes prop will default to rendering the children */}
        <span>Allowed to edit post</span>
    </AllowedTo>
);

NotAllowedTo

The NotAllowedTo component is used to restrict certain component trees based on whether the logged in user is not allowed access.

The same as the AllowedTo component but with the no and yes props switched.

See AllowedTo.

Hooks

useAbac

Properties

name	type	description
userHasPermissions	`(permissions: string \| string[], data?: any) => boolean`	Checks if the logged in user has one or more permissions.

Example usage

const EditPost = (props: { post: { owner: string } }) => {
    const { userHasPermissions } = useAbac();

    if (!userHasPermissions(permissions.EDIT_POST, props.post)) {
        return <span>Not allowed to edit post</span>;
    }

    return <span>Allowed to edit post</span>;
};

Decorators/Higher Order Components

secured

A decorator/hoc that can be used to allow or deny access to a component.

Options

| name | type | description | | --- | --- | --- | --- | | permissions | string or string[] | yes | A single permission or a list of permissions, if a list is provided all permissions are required. | | mapPropsToData | (props: Props) => Data | Maps the props provided to the component to data passed to abac rules (like the data prop on the AllowedTo component) | | noAccess | React.ComponentType<Props> | Component that should be rendered if no permission is granted |

Example usage

const EditPost = (props: { post: Post }) => {
    return <span>Allowed to edit post</span>;
};

secured({
    permissions: permissions.EDIT_POST,
    mapPropsToData: (props) => props.post,
    noAccess: () => <div>You are not allowed to edit this post</div>,
})(EditPost);

@secured({
    permissions: permissions.EDIT_POST,
    mapPropsToData: (props) => props.post,
    noAccess: () => <div>You are not allowed to edit this post</div>,
})
class EditPost extends React.Component<{ post: Post }> {
    render() {
        return <span>Allowed to edit post</span>;
    }
}

Concepts

Roles

A role describes what purpose (role) a user has within the system on a very high level. A user can have multiple roles.

It is recommended when using typescript to define the roles as an enum like so:

enum Role {
    ADMIN = "ADMIN",
    USER = "USER",
}

When using javascript a regular object can be used.

const Role = {
    ADMIN: "ADMIN",
    USER: "USER",
};

Permissions

A permission describes an action you might want to restrict, such as editing a post.

Permissions can be attached to a role (e.g. ADMIN role has DELETE_POST permission) or directly to a user.

Feel free to use whatever naming conventions you find appropriate, e.g. EDIT_POST or post:edit.

It is recommended when using typescript to define the permissions as an enum like so:

enum Permission {
    EDIT_POST = "EDIT_POST",
}

When using javascript a regular object can be used.

const Permission = {
    EDIT_POST: "EDIT_POST",
};

Rules

A rule describes the relationship between a Role and a Permission.

A rule can be:

a boolean
- rbac, role either has permission or doesn't
a function
- abac, user has permission based on user attributes and other data

Rules are described in an object like this:

const rules = {
    [Role.USER]: {
        // only allow editing if post is owned by user
        [Permission.EDIT_POST]: (post, user) => post.owner === user.uuid,
    },
    [Role.ADMIN]: {
        // always allow editing
        [Permission.EDIT_POST]: true,
    },
};

gourav-singhal / react-abac Goto Github PK

react-abac's Introduction

react-abac

Installing

Example

Tutorial

Usage

API reference

Functions

create

Example usage

Components

AbacProvider

Props

Example usage

AllowedTo

Props

Example usage

NotAllowedTo

Hooks

useAbac

Properties

Example usage

Decorators/Higher Order Components

secured

Options

Example usage

Concepts

Roles

Permissions

Rules

react-abac's People

Contributors

Stargazers

Recommend Projects

Recommend Topics

Recommend Org