Understand Permission Set Licenses

Permission set licenses (PSLs) allow you to create tiered licensing models with custom permissions that you can distribute in your packages. The PSLs available for the Go-To-Market (GTM) app extend the Salesforce Permission Set License type. Using PSLs, you can define PSLDs within your packages, provision them to subscribers, and allow subscriber admins to administer package access.

Partner PSLDs are defined in second generation package (2GP) metadata and are surfaced in subscriber orgs upon package install. Subscriber admins assign partner defined PSLs the same way they assign Salesforce PSLs.

Prerequisites and Restrictions

PSLs can be added in net new packages. You can’t publish a package version with permission set license definitions (PSLD) if the previous version does not have PSLs.

The package must be 2GP.
Only US-based subscribers are able to purchase PSLs.
PSLs can be sold to paid production orgs, not sandboxes.

Permission Set License Definition Metadata Type and Usage

For detailed information, see PermissionSetLicenseDefinition.

Example Permission Set License Definitions

The following examples show different approaches to creating PSLDs.

Base.permissionSetLicenseDefinition-meta.xml

Use this example to create a PSL that allows access to the unlicensed components of the package, using <componentAccess>Namespace</componentAccess>. In addition to allowing component access, this PSL allows users to receive read access to the Widget__c custom object, which requires a license to access. You can only assign this PSL to internal users.

1<?xml version="1.0" encoding="UTF-8"?>
2<PermissionSetLicenseDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
3    <customObjects>
4        <name>Widget__c</name>
5        <allowRead>true</allowRead>
6        <allowCreate>false</allowCreate>
7        <allowUpdate>false</allowUpdate>
8        <allowDelete>false</allowDelete>
9    </customObjects>
10    <componentAccess>Namespace</componentAccess>
11    <defaultTrialLicenseCount>10</defaultTrialLicenseCount>
12    <defaultTrialLengthInDays>30</defaultTrialLengthInDays>
13    <label>Base</label>
14    <userLicenseRestrictions>${internal}</userLicenseRestrictions>
15</PermissionSetLicenseDefinition>

Widget.permissionSetLicenseDefintion-meta.xml

Use this PSL to give assigned users full CRUD access to the Widget__c custom object. Since component access is none, it does not allow access to the unlicensed components in the package namespace and requires namespace access to be assigned. The assigned user must have a PSL with component access.

1<?xml version="1.0" encoding="UTF-8"?>
2<PermissionSetLicenseDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
3    <customObjects>
4        <name>Widget__c</name>
5        <allowRead>true</allowRead>
6        <allowCreate>true</allowCreate>
7        <allowUpdate>true</allowUpdate>
8        <allowDelete>true</allowDelete>
9    </customObjects>
10    <componentAccess>None</componentAccess>
11    <defaultTrialLicenseCount>10</defaultTrialLicenseCount>
12    <defaultTrialLengthInDays>30</defaultTrialLengthInDays>
13    <label>Widget</label>
14    <userLicenseRestrictions>${internal}</userLicenseRestrictions>
15</PermissionSetLicenseDefinition>

BikeCard.permissionSetLicenseDefinition-meta.xml

Similar to the Widget PermissionSetLicenseDefinition, this example doesn’t allow full component access to the package. It allows the user to be assigned the ViewBikeCard custom permission.

1<?xml version="1.0" encoding="UTF-8"?>
2<PermissionSetLicenseDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
3    <customPermissions>
4        <name>ViewBikeCard</name>
5    </customPermissions>
6    <componentAccess>None</componentAccess>
7    <defaultTrialLicenseCount>10</defaultTrialLicenseCount>
8    <defaultTrialLengthInDays>30</defaultTrialLengthInDays>
9    <label>BikeCard</label>
10    <userLicenseRestrictions>${internal}</userLicenseRestrictions>
11</PermissionSetLicenseDefinition>

Component Access

Namespace component access works like PackageLicense with a key difference: it allows access to unlicensed components in the entire namespace. In order for users to have any package access or be assigned PSLs in the package the user must have a PSL with component access assigned to them.

For PSL-licensed packages, PackageLicenses can’t be used to grant package access and aren’t created for subscribers. A PSL with Namespace component access replaces the PackageLicense.

PSLs with component access of “None” allow access to only licensed components in the namespace that the PSL references explicitly.

Licensed and Unlicensed Components

PSL-based packages can specify certain custom permissions and custom objects as “Licensed”. This means that for a user to receive access to that component, they must have a license assigned that explicitly allows access. Namespace component access within a PSL isn’t sufficient for receiving access to licensed components.

Licensed components must be explicitly included in a PermissionSetLicenseDefintion for a user to receive access to those components. For example, BikeCard.permissionSetLicenseDefintion-meta.xml allows users to get full CRUD access to the licensed ViewBikeCard custom permission if they have the PSL assigned. The base component access license doesn’t grant access to ViewBikeCard since ViewBikeCard is specified as requiring a license in the permission metadata.

Using Licensed and Unlicensed Permissions

We recommend flagging custom permissions and custom objects as Requires License if you want to monetize them separately from other parts of your package or they represent a premium feature in your package. Anything you want to include in your base tier should remain unlicensed, which means that having the base Component Access PSL grants access to those components.

If you have an object or permission that represents a premium feature in your package, you can sell your base PSLs with component access but put your premium components in a separate PSL to monetize separately.

How Many PSLs Should My Package Contain?

Your package namespace needs at least one PSLD, which is a component access PSL. We also recommend including PSLDs that represent tiers of access to the package. Beyond that, keep in mind that subscriber admins must assign permission set licenses to users, so including many granular PSLs may cause overhead for subscribers to use your package.

Updating PermissionSetLicenseDefinition After Release

The behavior of manageability rules fall into three categories:

Allowed - the change is allowed and is applied on package upgrade
Blocked - the change is disallowed and blocked at the time of package version creation
Allowed but not applied on upgrade - the change is allowed but not applied during package upgrade for existing subscribers

Allowed:

Adding new licensed permissions or objects to a PSLD
Adding a new PSLD
Modifying the label of a PermissionSetLicenseDefinition
Adding a new CRUD piece for a custom object in a PSLD. For example: adding update when read was already in place
Modifying the UserLicenseRestrictions in a PermissionSetLicenseDefintion

Blocked:

Modifications to ComponentAccess
Removing a PermissionSetLicenseDefintion from package metadata
Renaming a PermissionSetLicenseDefintion, label updates are allowed
Making a previously unlicensed object or permission licensed

Allowed but not applied on upgrade:

Removing custom objects from a PSLD
Removing custom permissions from a PSLD

Developer Setup and Packaging Prerequisites

Scratch orgs used to build or test PSL packages must enable the PartnerLicensingAndProvisioningPlatform feature in project-scratch-def.json. Without it, creating a licensed custom permission fails when the package version is created because you don’t have permission to create licensed custom permissions.

How PSLDs Surface in the PBO for Product Mapping

Once a package version containing PermissionSetLicenseDefinitions is released and the package has completed the AgentExchange Security Review, the PSLDs automatically surface in the partner’s PBO on the Partner Permission Set License object. No manual other step is required to move a PSLD from the package into the PBO.

Provisioning and Testing PSLs

To provision licenses from the CLI, using the sf license provision command, install the license management plugin: github.com/salesforcecli/plugin-license-management. The provision commands aren’t included in the base CLI and don’t appear in the command list without it.

PSL provisioning requires a namespaced scratch org in order to provision the PSLs.

See Also