Skip to content

Loading Entitlements

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, the accounts are marked with the entitlements they have, creating 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.

Source  entitlements with enhanced data like descriptions and the type.

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 aggregate 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.

  1. Go to Admin > Connections > Sources and select the direct connect source you want to edit.

  2. 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.

    A table containing the schema for one type of entitlement.

    Note

    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.

  3. Select + Create Entitlement Type.

  4. Enter the Name of your entitlement type and add a Description.

    Important

    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.

  5. 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.

  6. If you use Cloud Access Management or CIEM, and this entitlement type can grant access to a cloud resource, select the Cloud Enabled checkbox.

    The edit entitlement type window with the Cloud Enabled checkbox selected.

  7. Select Save.

Your new entitlement type is added to the list.

Defining Entitlement Type Schema Attributes

  1. Within the entitlement type on the Entitlement Types page, select + Add New Attribute to add an attribute to this entitlement type's schema.

  2. Add a Name and a Description for this attribute.

    The attribute's name should exactly match the attribute name in the source system. Entitlement attribute names cannot include periods.

  3. 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.

  4. To configure this attribute to support multiple values, select the Multi-Valued checkbox.

  5. If you want to add another attribute after saving this one, select the Add Another checkbox.

  6. Select Save.

    Important

    • 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.
  7. Repeat steps 1-6 for each attribute you want to include in this entitlement schema.

  8. If necessary, edit which attributes are listed as the Entitlement Name and ID by editing the entitlement type.

    Note

    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.

Example of an entitlement schema with the roles attribute entitlement type highlighted.

Note

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.

  1. Within the source, navigate to the Import Data tab and select Account Schema.
  2. Select the Edit icon on the attribute marked as an Entitlement.
  3. Set the Type to the entitlement type and select Update.

    Groups edit attribute window with the group type dropdown list emphasized and the entitlement and multi-valued checkboxes selected.

    Account schema for a Directory with the groups attribute and group entitlement type emphasized.

Editing an Entitlement Type

For any source type, you can edit the entitlement schema through a Update Source Schema (Full) API call. For source types that support UI creation of entitlement types, you can also edit them in the UI.

  1. In the source, go to the Import Data tab and select Entitlement Types.

  2. Select the name of an entitlement type to expand its details.

  3. Select Options > Edit Type.

  4. Make any necessary changes.

    On this page, you can select which attributes are used as the Entitlement ID and the Entitlement Name.

  5. If you use Cloud Access Management or CIEM, and this entitlement type can grant access to a cloud resource, select the Cloud Enabled checkbox.

    Edit entitlement type with the Cloud Enabled checkbox selected.

  6. Select Update.

    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.

  7. You can add schema attributes as you did in creating the entitlement type.

  8. 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:

  1. Expand the entitlement type schema in the list.

  2. Select Options > Delete Type. You can also delete a schema with the Delete icon in the Edit Type overlay.

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 Deleting Entitlements for more information.

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:

  1. Go to Admin > Connections > Sources.

  2. Select a direct connect source.

  3. Select the Import Data tab and select Entitlement Aggregation.

  4. Choose whether to perform a one-time manual aggregation or to schedule recurring aggregations.

Starting a Manual Aggregation

If your source only has a single type of entitlement, select Start beside Manual Aggregation.

Entitlement Aggregation panel with the Manual Aggregation option and Start button emphasized.

Your aggregation begins immediately and occurs once.

If your source has more than one entitlement type:

  1. Choose whether to aggregate all types of entitlements or only specific types.

    • To aggregate all types of entitlements in your site, select the All Types radio button and select Start. Your aggregation begins immediately.
    • 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.
  2. Select Start to run the aggregation. The process begins immediately and occurs only once.

    Manual Aggregation window with the Specific Types option selected. The Group and Type 3 entitlements are selected.

Scheduling Recurring Aggregations

  1. From the Entitlement Aggregation page, select the Enable Schedule checkbox.

  2. 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

    Notes

    • 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.
  3. If your source has more than one type of entitlement, choose whether you want to aggregate all types of entitlements or only specific types.

    • To aggregate all types of entitlements during a scheduled aggregation, select the All Types button and select Save.

    • 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:

  1. Go to Admin > Connections > Sources.

  2. Select a source that uses a flat file feed.

  3. Select the Import Data tab and select Import Entitlements.

  4. 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.

    Important

    • 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 Identity Security Cloud UI
    • description - the description of the entitlement visible in the UI and during certifications
  5. 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.

    Important

    • 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.

    Flat file CSV example displaying the names, descriptions, and other fields.

  6. Save the file.

  7. Return to the source's Import Entitlements page and select Import.

  8. Select the file you saved in step 6.

  9. Select Open.

    Note

    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.

Note

For both flat files and direct connection aggregations, Identity Security Cloud 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.

Entitlement names do not support emojis or the + character. Identity Security Cloud supports the UTF8MB3 character set, which excludes emojis and some special characters. Review information about the Basic Multilingual Plane for details.

Documentation Feedback