Permissions

As we learned in OAuth Scopes and user permissions, each Custom Application has a unique pair of default user permissions at its disposal: "view" and "manage." Additionally, you can use more granular permission groups to cover strict business requirements.

The values of the user permissions are derived from the application entryPointUriPath.

When developing a Custom Application you might want to enforce these user permissions in some parts of your application. For example, performing certain actions like creating, updating, or deleting a resource should only be possible if the user has "manage" permission.

Defining constants

The user permissions can be computed using the entryPointUriPathToPermissionKeys function, to avoid defining them manually. We recommend to define them in a constants.js file.

constants.jsJavaScript

import { entryPointUriPathToPermissionKeys } from '@commercetools-frontend/application-shell/ssr';

export const entryPointUriPath = 'channels';

export const PERMISSIONS = entryPointUriPathToPermissionKeys(entryPointUriPath);

The PERMISSIONS variable contains a View and Manage properties, with the values being the computed values based on the entryPointUriPath:

PERMISSIONS.View: maps to ViewChannels.
PERMISSIONS.Manage: maps to ManageChannels.

You can then use the PERMISSIONS variable to reference the permission in the application code.

This feature is available from version 21.21.0 onwards.

When using additional permission groups, you must also provide the unique group to the entryPointUriPathToPermissionKeys function to generate the correct permission keys.

The group names can be exported and referenced also in the Custom Application config file.

constants.jsJavaScript

import { entryPointUriPathToPermissionKeys } from '@commercetools-frontend/application-shell/ssr';

export const entryPointUriPath = 'channels';

export const groupNames = {
  delivery: 'delivery',
  promotion: 'promotion',
};

export const PERMISSIONS = entryPointUriPathToPermissionKeys(
  entryPointUriPath,
  ['delivery', 'promotion']
);

In this scenario, the PERMISSIONS variable contains a View, Manage, ViewDelivery, ManageDelivery, ViewPromotion and ManagePromotion properties, with the values being the computed values based on the entryPointUriPath and the provided permission group names:

PERMISSIONS.View: maps to ViewChannels.
PERMISSIONS.Manage: maps to ManageChannels.
PERMISSIONS.ViewDelivery: maps to ViewChannelsDelivery.
PERMISSIONS.ManageDelivery: maps to ManageChannelsDelivery.
PERMISSIONS.ViewPromotion: maps to ViewChannelsPromotion.
PERMISSIONS.ManagePromotion: maps to ManageChannelsPromotion.

Applying user permissions

A Custom Application allows, for example, to check and evaluate if certain user permissions are assigned or not, making it possible to determine whether to render something or not, or to turn off some UI functionalities.

In the Custom Application config, the menu links allow defining the level of required access by providing the name of the requested user permission.

{
  "mainMenuLink": {
    "permissions": ["ViewChannels"]
  },
  "submenuLinks": [
    {
      "permissions": ["ManageChannels"]
    }
  ]
}

This determines which links should be visible or not, depending on the permissions assigned to the user.

Leaving the list of permissions empty makes the menu link always visible (no restrictions are applied).

In case you defined the permissions in a constants file, we recommend to reference them in the Custom Application config as well. To do so, the config file needs to be converted to a JS file (instead of JSON), for example using the .mjs file extension.

custom-application-config.mjsJavaScript

import { entryPointUriPath, PERMISSIONS } from './src/constants';

const config = {
  entryPointUriPath,
  mainMenuLink: {
    permissions: [PERMISSIONS.View]
  },
  // ...
};
export default config;

In routes

In case certain routes should not be accessible without proper user permissions, you can render the route conditionally based on the evaluated permission.

To do so you can use the useIsAuthorized React hook from the @commercetools-frontend/permissions package.

routes.jsJavaScript

import { Switch, Route, useRouteMatch } from 'react-router-dom';
import { useIsAuthorized } from '@commercetools-frontend/permissions';
import { PageUnauthorized } from '@commercetools-frontend/application-components';
import { PERMISSIONS } from './constants';
import ChannelsCreate from './components/channels-create';
import ChannelsList from './components/channels-list';

const ApplicationRoutes = () => {
  const match = useRouteMatch();
  const canManage = useIsAuthorized({
    demandedPermissions: [PERMISSIONS.Manage],
  });

  return (
    <Switch>
      <Route path={`${match.path}/new`}>
        {canManage ? (
          <ChannelsCreate />
        ) : (
          <PageUnauthorized />
        )}
      </Route>
      <Route>
        <ChannelsList>
      </Route>
    </Switch>
  );
};

In components

Similarly, you can also evaluate user permissions in your React components, for example to deactivate a button.

import { useIsAuthorized } from '@commercetools-frontend/permissions';
import PrimaryButton from '@commercetools-uikit/primary-button';
import { PERMISSIONS } from '../constants';

const MyComponent = () => {
  const canManage = useIsAuthorized({
    demandedPermissions: [PERMISSIONS.Manage],
  });

  return (
    <div>
      <PrimaryButton
        label="Create channel"
        isDisabled={!canManage}
      />
    </div>
  )
}