Entitlements are the access rights an account has on a source. Each source’s account schema specifies which account attributes represent its entitlements. When you aggregate accounts, IdentityNow marks each account with the entitlements it has and creates a simple representation of the entitlements in the source’s entitlement catalog.
Many sources also contain enhanced data about their entitlements, such as display names, that can help users better understand what they mean. You can also collect that information from the source through a separate process called entitlement aggregation.
Though not mandatory, it is both common and desirable to define an entitlement type and run entitlement aggregations to collect this information, providing these important benefits:
- It defines the entire catalog of entitlements associated with the source, regardless of whether they're already associated with accounts.
- It can aggregate additional attributes for each entitlement, including display names, descriptions, and relationships to other entitlements.
Creating and Managing Entitlement Types
Each source can have at least one entitlement type, and many support multiple entitlement types. Each entitlement type has a schema that defines its attributes - the enhanced information you want to include in IdentityNow about that type. Most direct connect sources come with an entitlement type and schema configured by default.
You can edit the default schema to fit the data in your source. If your direct connect source doesn't have an entitlement schema by default, you can create a new one.
Creating an Entitlement Type
For sources that have no predefined entitlement type or that support multiple entitlement types, you can create a new entitlement type and manage its schema through the user interface.
Go to Admin > Connections > Sources and select the direct connect source you want to edit.
Go to the Import Data tab and select Entitlement Types.
If you already have one or more types of entitlements for this source, they are listed here.
Not all source types include the Entitlement Types UI. If that option does not appear, the source's entitlement type schema can only be edited through the API.
Select + Create Entitlement Type.
Enter the Name of your entitlement type and add a Description.
The name you give your entitlement type must exactly match the name of the entitlement type as it appears on the source. This is sometimes called the native object type.
To aggregate indirect permissions granted through this type of entitlement, check the box beside Include permissions in aggregations. This information appears in certifications to aid decision-making about access to the entitlements.
Your new entitlement type is added to the list.
Defining Entitlement Type Schema Attributes
Within the entitlement type on the Entitlement Types page, select + Add New Attribute to add an attribute to this entitlement type's schema.
Add a Name and a Description for this attribute.
The attribute's name should exactly match the attribute name in the source system.
Under Type, choose the type of value that this attribute will contain.
You can choose string, long, int, or boolean, or you can link entitlement types together by choosing another entitlement type.
To configure this attribute to support multiple values, select the Multi-Valued checkbox.
If you want to add another attribute after saving this one, select the Add Another checkbox.
- When you create the first attribute in an entitlement schema, it is automatically marked as both the Entitlement Name and Entitlement ID. This can be edited later.
- Be sure to select the correct entitlement name and ID before aggregating any entitlements of this type. Changing these attributes later can cause duplicate entitlements to be aggregated.
- Entitlement attribute names cannot include periods.
Repeat steps 1-6 for each attribute you want to include in this entitlement schema.
If necessary, edit which attributes are listed as the Entitlement Name and ID by editing the entitlement type.
Populated entitlement schema attributes will appear in certifications as additional attributes within the entitlement's details page. Reviewers can use these attributes to help inform their decisions.
Linking Multiple Entitlement Types
In systems with multiple types of entitlements, one entitlement type might contain and grant entitlements of another type. In that case, the Type of the attribute that connects them should be set to the other entitlement type.
For example, if a system has both groups and roles as entitlement types and a group can grant role entitlements to its members, then the group schema will contain an entitlement attribute of type roles, linking groups to the roles they grant.
If you choose an entitlement type as an attribute's Type, Entitlement is automatically selected.
Connecting Account Data to Entitlement Type
When you have an entitlement type and schema, your account schema's entitlement attribute needs to be connected to the entitlement data by setting the Type of that attribute to the entitlement type.
- Within the source, navigate to the Import Data tab and select Account Schema.
- Select the Edit icon on the attribute marked as an Entitlement.
Set the Type to the entitlement type and select Update.
Editing an Entitlement Type
For any source type, you can edit the entitlement schema through a source schema API call. For source types that support UI creation of entitlement types, you can also edit them in the UI.
In the source, go to the Import Data tab and select Entitlement Types.
Select the name of an entitlement type to expand its details.
Select Options > Edit Type.
Make any necessary changes.
On this page, you can select which attributes are used as the Entitlement ID and the Entitlement Name.
If you changed the attributes marked as the Entitlement ID and Name, you'll be asked to confirm your selections. Updating these attributes after aggregating your entitlements can cause duplicate entitlements to be aggregated.
You can add schema attributes as you did in creating the entitlement type.
To remove schema attributes, select the Delete icon on any attribute row. You can also delete attributes in bulk by selecting the checkboxes on the rows you want to delete and selecting Delete Attributes.
Deleting an Entitlement Type
To delete an entitlement type and its associated schema:
Expand the entitlement type schema in the list.
Deleting an entitlement type does not delete the associated entitlements. Entitlements of that type will not be aggregated or updated until another type is created for them. Refer to Managing Entitlements for details on deleting entitlements.
Loading Entitlements for a Direct Connect Source
You can aggregate entitlements from a direct connect source just as you can aggregate accounts: manually or on a schedule.
To aggregate entitlements from a direct connect source:
Go to Admin > Connections > Sources.
Select a direct connect source.
Select the Import Data tab and select Entitlement Aggregation.
Complete the steps below depending on which type of aggregation you want to perform.
Starting a Manual Aggregation
If your source only has a single type of entitlement, select Start beside Manual Aggregation.
Your aggregation begins immediately and occurs once.
If your source has more than one entitlement type:
- Choose whether to aggregate all types of entitlements or only specific types. a. To aggregate all types of entitlements in your site, select the All Types radio button and select Start. Your aggregation begins immediately. b. To aggregate specific types of entitlements, select the types of entitlement to aggregate from the list. You can select + Add for more rows to add additional entitlement types to the aggregation.
- Select Start to run the aggregation. The process begins immediately and occurs only once.
Scheduling Recurring Aggregations
From the Entitlement Aggregation page, select the Enable Schedule checkbox.
Choose how often the aggregation should run from the following options, and specify the required scheduling details:
- Daily: choose starting time of day and frequency of execution
- Weekly: choose day of week and time
- Monthly: choose day of month and time
- If you choose Daily, the time period selected in the Recurring Every field determines how often the aggregation occurs after the time selected. For example, if you schedule a daily aggregation for 5pm to recur every 4 hours, the aggregation will run only at 5pm and 9pm, depending on the load.
- The time zone (GMT offset) for the entitlement aggregation schedule is determined by the time zone set for the connected virtual appliance cluster.
If your source has more than one type of entitlement, choose whether you want to aggregate all types of entitlements or only specific types.
a. To aggregate all types of entitlements during a scheduled aggregation, select the All Types button and select Save. b. If you chose to aggregate specific types of entitlements, select the types of entitlement to aggregate from the list. You can select + Add for more rows to add additional entitlement types to the aggregation. When finished, select Save.
This source will automatically run an entitlement aggregation on the schedule you configured for the entitlement types you selected.
Loading Entitlements for a Flat File Source
You can aggregate entitlements from a flat file source by uploading a flat file containing your entitlement data. It is not possible to schedule recurring entitlement aggregations or configure multiple entitlement types for a flat file source. The most common type of flat file source is a delimited file.
To upload entitlements from a flat file source:
Go to Admin > Connections > Sources.
Select a source that uses a flat file feed.
Select the Import Data tab and select Import Entitlements.
If you are preparing to create the file to upload for the first time, you can obtain the set of expected columns by selecting Download to download the template.
- The file you upload for a source must not exceed 1 MB.
- The file you upload for a source must use the column headings included in the entitlements template for that source. Column headings differ based on the type of source you're downloading entitlements from.
- You cannot change the columns by rearranging, adding, or omitting columns in this file. To change these fields, you must modify the entitlement schema.
All default entitlement schemas will include at least these columns:
- id - the technical ID for the entitlement
- name - the technical name for the entitlement
- displayName - the name for the entitlement that displays in the IdentityNow UI
- description - the description of the entitlement visible in the UI and during certifications
Create a comma separated values (CSV) file with the required columns, either by editing your existing entitlements file to include the template's column headings or by recording your entitlements data into the template.
The id column is required for each entitlement. This is the unique identifier for the entitlement and is the value matched to the account schema's entitlement column values. If you need help setting up this entitlement file, contact SailPoint Expert Services.
- Names and descriptions should help users to make good decisions when reviewing access requests or certifications.
- Multiple entitlement types are not supported in flat file sources.
Save the file.
Return to the source's Import Entitlements page and select Import.
Select the file you saved in step 6.
Screenshots related to these files are examples only. Excel is not required.
Information about the file is loaded into the Current File section.
After uploading this file, you can edit entitlements as described in Managing Entitlement Details. You can add or remove entitlements by importing a new file.
For both flat files and direct connection aggregations, IdentityNow truncates entitlement descriptions longer than 2000 characters.
Troubleshooting Entitlement Aggregation Issues
The following list describes common aggregation issues that may occur and their typical causes:
Entitlements that contain emojis or the + character in their names are not aggregating.
IdentityNow supports the UTF8MB3 character set, which excludes many emojis and some special characters. Review information about the Basic Multilingual Planefor details. It does not support the + character in entitlement names.