React Authorization Library

Declarative authorization API for the UI. Allows declarative description of what should and should not be displayed based on the user's role(s), or an authorization function result.

Usage

<IfGranted expected='ROLE_ADMIN' actual={user.getRoles()}>
    <div className="panel">
        Child with restricted access.
    </div>
</IfGranted>

Displays the child div only if the user.getRoles() result contains the role ROLE_ADMIN.

<IfAllGranted expected={['ROLE_USER', 'ROLE_ADMIN']} actual={user.getRoles()} unauthorized={<h3>You shall not pass!</h3>}>
    <div className="panel">
        Child with restricted access.
    </div>
</IfAllGranted>

Displays the child div only if the user.getRoles() contains both ROLE_USER and ROLE_ADMIN. If not, a heading saying You shall not pass! is displayed. Specifying the node to display when expected roles are not met is optional ( see the API section).

<IfAuthorized isAuthorized={() => user.getRoles().indexOf('ROLE_ADMIN') !== -1}>
    <div className="panel">
        Child with restricted access.
    </div>
</IfAuthorized>

Displays the child div only if the specified authorization function returns a truthy value.

<IfAuthorized isAuthorized={hasAccess(AccessLevel.WRITE, AccessLevel.READ)}>
    <div className="panel">
        Child with restricted access.
    </div>
</IfAuthorized>

Displays the child div if the hasAccess function (first parameter being required access level, second the actual granted) returned true. This is basically equivalent to doing

{hasAccess(AccessLevel.WRITE, AccessLevel.READ) && <div className="panel">
  Child with restricted access.
</div>}

You be the judge of which is nicer.

Rendering

The library is using React Fragments to render the children directly without any wrapper element. For example:

<IfAnyGranted expected={['ROLE_USER', 'ROLE_ADMIN']} actual={user.getRoles()}>
    <div className="panel">
        Child with restricted access.
    </div>
    <div>
        And another one.
    </div>
</IfAnyGranted>

Will be rendered directly:

<div class="panel">
    Child with restricted access.
</div>
<div>
    And another one.
</div>

Versions prior to 0.1.0 used a wrapper element (a div by default, but could be overridden).

API

Supported components:

• IfAllGranted - requires all of the expected roles to be granted,
• IfAnyGranted - requires at least one of the expected roles to be granted,
• IfGranted - shorthand for expecting one role only - corresponds to using IfAnyGranted with exactly one role expected,
• IfNoneGranted - requires that none of the expected roles is granted (e.g., role guest must not be set for editing access),
• IfAuthorized - invokes the specified authorization function and renders children only if it returns a truthy value ( since 0.3.0).

API of the respective components is described below.

IfAllGranted

Displays the children if and only if all of the expected roles are granted.

| Property | Type | Required | Default value | Explanation | | -------- | ----- | -------- | ------------- | ----------- | | expected | Array | true | | An array of roles required to display the children. | | actual | String/Array | false | [] | An array of actually granted roles, or a single role (shorthand for an array with one element). | | unauthorized | Node | false | null | Node to display when the actual roles do not meet the expectations. Defaults to null, which displays nothing. |

IfAnyGranted

Displays the children if at least one of the expected roles is granted.

| Property | Type | Required | Default value | Explanation | | -------- | ----- | -------- | ------------- | ----------- | | expected | Array | true | | An array of roles required to display the children. | | actual | String/Array | false | [] | An array of actually granted roles, or a single role (shorthand for an array with one element). | | unauthorized | Node | false | null | Node to display when the actual roles do not meet the expectations. Defaults to null, which displays nothing. |

IfGranted

Displays the children if the expected role is granted.

| Property | Type | Required | Default value | Explanation | | -------- | ----- | -------- | ------------- | ----------- | | expected | String | true | | The role required to display the children. | | actual | String/Array | false | [] | An array of actually granted roles, or a single role (shorthand for an array with one element). | | unauthorized | Node | false | null | Node to display when the actual roles do not meet the expectations. Defaults to null, which displays nothing. |

IfNoneGranted

Displays the children if none of the expected roles is granted. Useful, for example, to prevent display of editing components to guests or otherwise restricted users.

| Property | Type | Required | Default value | Explanation | | -------- | ----- | -------- | ------------- | ----------- | | expected | String/Array | true | | An array of roles (or a single role) which must not be present to display children. | | actual | String/Array | false | [] | An array of actually granted roles, or a single role (shorthand for an array with one element). | | unauthorized | Node | false | null | Node to display when the actual roles do not meet the expectations. Defaults to null, which displays nothing. |

IfAuthorized

Displays the children if the provided authorization function returns a truthy value or if the provided boolean value is true. Useful for more complex authorization logic which should still be declaratively used.

| Property | Type | Required | Default value | Explanation | | -------- | ----- | -------- | ------------- | ----------- | | isAuthorized | Function/boolean | false | | An authorization function with signature () => boolean or a boolean. Defaults to undefined, which is equivalent to false. | | unauthorized | Node | false | null | Node to display when the authorization function returns a falsy value. Defaults to null, which displays nothing. |

Installation

Install with npm using

npm install --save react-authorization

License

MIT