Access to Forge apps for unlicensed Jira Service Management users

Introduction

If the product module you’re using supports unlicensed access, you can optionally allow one or more types of these unlicensed users to run your Forge app. This is done by adding permissions in your app’s manifest.yml file.

By default, only licensed, authenticated users of the product within which an app runs, can use that app. For Jira Service Management, these licensed users include agents, project administrators, and collaborators. This means that Forge apps won’t work for unlicensed users in portals/views, such as the Jira Service Management portal, that support unlicensed use cases unless you configure your app to allow it.

Overview of Forge unlicensed access

Before configuring unlicensed access, make sure you understand the different types of unlicensed users. Jira Service Management has three unlicensed user types, reflecting different levels of the user’s relationship with the site:

Unlicensed access is currently supported for the following Jira Service Management modules:

Supported functionality

Authenticated product API calls

Unlicensed users won't be able to make asUser API calls because the user is unauthorized and won't have full access to the Jira Service Management project. However, apps with the necessary permissions will be able to make asApp API calls.

AccountType property in app contexts

You can use the AccountType property in the Forge UI context and the Resolver context to customize your app's behavior. For more information on this, see How to customize app behavior for unlicensed users below.

Storage API

The app can use storage APIs to store and retrieve values from Forge storage using the Forge storage API while invoking modules for unlicensed users.

For example:

1
2
const secretKey = await storage.getSecret(`github-secret:${context.accountId}`)

For anonymous users ${context.accountId} === 'unidentified'

Because all anonymous have the same accountId, unidentified, and this developer has keyed storage on the accountId, they are sharing the same data across all anonymous users.

See Storage API to learn more.

Forge tunnel

You can tunnel development app invocations from customer and anonymous account types.

Opt in to unlicensed access

By default, Forge modules don’t allow unlicensed user access. You can opt in for unlicensed access via the manifest using the unlicensedAccess property on supported modules. This is an optional property and its absence means that the module does not allow unlicensed users.

The unlicensedAccess property in the manifest expects an array of user types. For example, the sample manifest.yml file section below defines an app module that uses the jiraServiceManagement:portalFooter product module.

1
2
modules:
  jiraServiceManagement:portalFooter:
    - key: hello-world-panel
      resource: main
      resolver:
        function: resolver
      viewportSize: medium
      unlicensedAccess:
        - anonymous
        - customer

This app allows anonymous and customer users to interact with the hello-world-panel module. Hence, when an anonymous or customer user visits the portal page, this app module will be run. However, since this app doesn't allow unlicensed users, this app module won't be available and won't be run if an unlicensed user visits the portal page.

Customize app behavior for different types of users

You can customize app behavior for different user types by fetching the current user's account type from the accountType property. This property can have one of the following possible values, three of which are the unlicensed user types mentioned previously:

UI Kit

UI Kit apps can fetch accountType from the useProductContext hook as follows:

1
2
import ForgeUI, { useProductContext, Text, Macro, render } from '@forge/ui';
    
const App = () => {
  const context = useProductContext();
  return <Text>Account type: {context.accountType}</Text>;
};
 
export const run = render(<Macro app={<App />} />);

Custom UI

Custom UI apps can call a resolver if they need accountType. The resolver can access the accountType property in the context and simply return its value back to the view:

1
2
resolver.define('getAccountType', (req) => {
  return req.context.accountType;
});

Understand manifest validation errors for unlicensed access via the Forge CLI

Unlicensed access is only supported in certain Jira Service Management modules, as mentioned above. The Forge CLI has been updated to validate your manifest when running and prevent you from incorrectly configuring modules as follows:

• forge lint displays an error message if unlicensed access is configured incorrectly.
• forge deploy displays an error message and does not deploy your app if unlicensed access is configured incorrectly.

There are two types of errors you might encounter in the Forge CLI:

• Module does not support unlicensed access by any users.
• Module does not support unlicensed access by a specific unlicensed user type.

Example: Unlicensed access is not supported by the product module

If you try to add unlicensed access to modules that don’t support it, Forge displays an error in this format:

1
2
${module} does not support the following Forge properties - 'unlicensedAccess'

Consider the following manifest that defines unlicensedAccess for the hello-world-panel app module using the jiraServiceManagement:queuePage product module.

1
2
modules:
  jiraServiceManagement:queuePage:
    - key: hello-world-panel
      resource: main
      resolver:
        function: resolver
      viewportSize: medium
      unlicensedAccess:
        - anonymous
        - customer

As mentioned above, the jiraServiceManagement:queuePage module is not open for unlicensed access. You will get the following error when you try to deploy this app:

1
2
$ forge deploy
error    jiraServiceManagement:queuePage does not support the following Forge properties - 'unlicensedAccess'  valid-document-required

Notice that the error message references the product module. This indicates that the module does not support any unlicensed access.

Example: Unlicensed access is not supported by the product module for a particular user type

If you try to add a user type that is not supported by a module, Forge displays an error in this format:

1
2
Property "unlicensedAccess" in ${moduleKey} must be an array of one or more of the
following values: [unlicensed, customer, anonymous]

Consider the following manifest that defines unlicensedAccess for anonymous and customer user types to hello-world-panel for jiraServiceManagement:portalUserMenuAction.

1
2
modules:
  jiraServiceManagement:portalUserMenuAction:
    - key: hello-world-panel
      resource: main
      resolver:
        function: resolver
      viewportSize: medium
      unlicensedAccess:
        - anonymous
        - customer

As mentioned above, although the jiraServiceManagement:portalUserMenuAction module is open for unlicensed access but it only allows unlicensed and customer accounts to have access. Therefore you will get the following error when you try to deploy this app:

1
2
$ forge deploy --verbose
  Upload URL is valid
  Found manifest file
  Manifest is a valid YAML
  Property "unlicensedAccess" in hello-world-panel-portal-user must be an array of one or more of the following values: [unlicensed, customer]

Error: Deployment failed

Notice that in this case, the error message references your app key. This indicates that the issue is that the product module does support some types of unlicensed access, but does not support one or more of the user types you specified for your app.