React-authorization NPM

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.