Permissions

Defining constants

To avoid defining permissions manually, we recommend using one of the following helper functions inside your constants.js file:

• For Custom Applications: entryPointUriPathToPermissionKeys
• For Custom Views: resolveCustomViewResourceAccesses

Custom Applications

The following example shows the use of the entryPointUriPathToPermissionKeys function:

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.

Additional permission groups

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.

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.

Custom Views

The following example shows the use of the resolveCustomViewResourceAccesses function:

import { resolveCustomViewResourceAccesses } from '@commercetools-frontend/application-config';

export const PERMISSIONS = resolveCustomViewResourceAccesses();

The PERMISSIONS variable contains a View and Manage properties:

• PERMISSIONS.View: maps to View.
• PERMISSIONS.Manage: maps to Manage.

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

Additional permission groups

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

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

import { resolveCustomViewResourceAccesses } from '@commercetools-frontend/application-config';

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

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

Applying user permissions

Customizations let you 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 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 hook, as follows:

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 CustomizationRoutes = () => {
  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

You can 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.ManagePromotion],
  });

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

In menu links

In the Custom Application config, the menu links let you define 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.

If you defined the permissions in a constants file, we recommend that you 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.

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

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