Policy Components

• 1: Data Elements
• 1.1: Example - Creating a Token Data Element
• 1.2: Example - Creating a FPE Data Element
• 1.3: Example - Creating a Data Element for Unstructured Data
• 2: Alphabets
• 3: Masks
• 3.1: Example - Creating a Mask from a Template
• 4: Trusted Applications
• 4.1: Linking Data Store to a Trusted Application
• 5: Data Stores
• 5.1: Configuring Allowed Servers
• 5.2: Export Keys
• 5.3: Adding Trusted Applications to the Data Store
• 5.4: Adding Policies to the Data Store
• 6: Member Sources
• 6.1: Configuring Member Sources
• 6.1.1: Configuring Active Directory Member Source
• 6.1.2: Configuring File Member Source
• 6.1.3: Configuring LDAP Member Source
• 6.1.4: Configuring POSIX Member Source
• 6.1.5: Configuring Azure AD Member Source
• 6.1.6: Configuring Database Member Source
• 7: Roles
• 7.1: Role Refresh Modes
• 7.2: Adding Members to a Role
• 7.2.1: Filtering Members in a Role
• 7.2.1.1: Filtering Members from AD and LDAP Member Sources
• 7.2.1.2: Filtering Members from Azure AD Member Source
• 7.3: Managing Members in a Role
• 7.4: Searching Members
• 7.5: Searching Member Access

1 - Data Elements

Data Elements are the most critical elements of data protection. Data Elements determine how cryptographic algorithms are applied to data.

Typically, there is one Data Element per data type. For example, name, address, or credit card number. This allows for granular enforcement of control over sensitive data.

Protegrity supports two types of Data Elements:

• Structured: Used for fine-grained field- and column-level protection. For example, a name attribute in a JSON file, or a column in a database table storing customer names.
• Unstructured: Used for course-grained file protection. It is only applicable to the Protegrity File Protector.

To create, view and manage Data Elements, navigate to Policy Management from the main menu, and choose Data Elements & Masks. The Data Elements tab opens by default.

Creating Data Elements

Before creating a Data Element, understand the type and format of data that you are protecting, and what is your desirable output. For example, if length and format preservation are required, tokenization or Format Preserving Encryption (FPE) are the recommended methods.
For guidance regarding the protection methods, refer to the section Protection Method Reference.

To add a new Data Element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks.

   The Data Elements tab appears by default.

2. Click Add New Data Element.

   The New Data Element screen appears.

3. Specify the following common properties for each Data Element:

   Property	Description
   Type	Type of the Data Element to be created. For example, structured or unstructured.
   Name	Unique name identifying the data element. The maximum length of the data element is 55 characters.
   Description	Text describing the Data Element.
   Method	Types of data protection to apply: Tokenization Encryption Format Preserving Encryption (FPE) Hashing Masking Monitoring Depending on the chosen protection method, additional configuration options appear. For example, Encryption has an option to use Initialization Vectors, while Tokenization shows different tokenization options depending on the data type. For more information about the available protection methods and their properties, refer to the section Protection Methods Reference.

4. Click Save.

Note: You can use the Policy Management REST API to create Data Elements.

Managing Data Elements

After a Data Element is created, it cannot be modified. You can only provide a new description for the Data Element.

Deleting Data Elements

A Data Element can be deleted. It must first be removed from all policies where it has been attached before it can be removed.

To remove a Data Element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks.

   The Data Elements tab appears by default.

2. Select the Data Element from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Data Element has been deleted successfully appears.

Warning: The Delete action cannot be reversed. By deleting a Data Element, you are effectively removing the cryptographic material associated with that Data Element. You will lose the ability to re-identify the data protected with that Data Element. You can only restore Data Elements by restoring the Policy from a backup file.

1.1 - Example - Creating a Token Data Element

Note: You create token data elements for all protectors, except for the FileProtector.

To create a structured data element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Data Elements.

2. Click Add New Data Element.

   The New Data Element screen appears.

3. Select Structured from Type.

4. Type a unique name for the data element in the Name textbox.

Note: Ensure that the length of the data element name does not exceed 55 characters.

5. Type the description for the data element in the Description textbox.

6. Select the protection method from the Method drop-down. In this example, select Tokenization.

7. Select the tokenization data type from the Data Type drop down. In this example, select Numeric (0-9).

   For more information about the different data types, refer to the section Protection Methods Reference.

8. Select the tokenizer from the Tokenizer drop-down.

   For more information about the different token elements, refer to the section Protection Methods Reference.

9. If the Tokenizer should leave characters in clear, then set the number of characters from left and from right in the From Left and From Right text boxes.

   For more information on the maximum and minimum input values for these fields, refer to the section Minimum and Maximum Input Length in the section Protection Methods Reference.

10. If the token length needs to be equal to the provided input, then select the Preserve length check box.

11. If you select the Preserve length option, then you can also choose the behavior for short data tokenization in the Allow Short Data drop-down.

12. Click Save.

A message Data Element has been saved successfully appears.

1.2 - Example - Creating a FPE Data Element

To create a structured FPE data element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Data Elements.

2. Click Add New Data Element.

   The New Data Element screen appears.

3. Select Structured from Type.

4. Enter a unique name for the data element in the Name textbox.

   Note: Ensure that the length of the data element name does not exceed 55 characters.

5. Type the description for the data element in the Description textbox.

6. Select FPE NIST 800-38G from the Method drop-down.

7. Select a data type from the Plaintext Alphabet drop-down.

8. Configure the minimum input length from the Minimum Input Length text box.

9. Select the tweak input mode from the Tweak Input Mode drop-down.

   For more information about the tweak input mode, refer to the section Tweak Input in the Protection Methods Reference Guide.

10. Select the short data configuration from the Allow Short Data drop-down.

    Note: FPE does not support data less than 2 bytes, but you can set the minimum message length value accordingly.

    For more information about length preservation and short tokens, refer to section Length Preserving.

    Note: If you create a short data token in a policy and then deploy the policy, the Forensics displays a policy deployment warning indicating that the data element has unsupported settings.

11. Enter the required input characters to be retained in the clear in the From Left and From Right text box.

    For more information about this setting, refer to the section Left and Right Settings.

12. Configure any special numeric data handling request, such as Credit Card Number (CCN), in the Special numeric alphabet handling drop-down.

    For more information about handling special numeric data, refer to the section Handling Special Numeric Data.

13. Click Save.

A message Data Element has been created successfully appears.

1.3 - Example - Creating a Data Element for Unstructured Data

Note: Unstructured data elements are exclusively applicable to Protegrity File Protector.

To create an unstructured data element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Data Elements.

2. Click Add New Data Element.

   The New Data Element screen appears.

3. Select Unstructured from Type.

4. Type a unique name for the data element in the Name textbox.

   Note: Ensure that the length of the data element name does not exceed 55 characters.

5. Type the required description for the data element in the Description textbox.

6. Select AES-256 from the Method drop-down list.

7. If you want to enable multiple instances of keys with the data element, then check the Use Key ID (KID) checkbox.

8. Click Save.

A message Data Element has been saved successfully appears.

2 - Alphabets

Alphabets are groupings of Unicode character sets. Their main purpose is to support additional languages or character input domains that exist in the user’s environment, such as Spanish, Polish, or Korean. The ESA includes some pre-defined alphabets. Users can create their own custom alphabets.

The alphabets are supported with the Tokenization Data Elements of the Unicode Gen2 type.

For more information about the code points and considerations around creating alphabets, refer to the section Considerations while creating custom Unicode alphabets.

Creating Alphabets

To create an alphabet:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Alphabets.

2. Click Add New Alphabet.

   The New Alphabet screen appears.

3. Enter a unique name for the alphabet in the Name text box.

4. Under the Alphabet tab, click Add to add existing alphabets or custom code points to the new alphabet.

   The Add Alphabet entry screen appears.

   If you plan to use multiple alphabet entries to create a token alphabet, then click Add again to add other alphabet entries.

   Ensure that code points in the alphabet are supported by the protectors using this alphabet.

5. Select an existing alphabet, a custom code point, or a range of custom code points.

   The following options are available for creating an alphabet.

   Important: For the SLT_1_3 tokenizer, you must include a minimum of 10 code points and a maximum of 160 code points.

   Important: For the SLT_X_1 tokenizer, you must include a minimum of 161 code points and a maximum of 100k code points.

   Alphabet Option	Description
   Existing Alphabets	Select one of the existing alphabets. The list includes internal and custom alphabets.
   Custom code point in hex (0020-3FFFF)	Add custom code points that will be used to generate the token value.
   Custom code point range in hex (0020-3FFFF)	Add a range of code points that will be used to generate the token value. Note: When creating an alphabet using the code point range option, note that the code points are not validated. For more information about consideration related to defining code point ranges, refer to the section Considerations while creating custom Unicode alphabets.

6. Click Add to add the alphabet entry to the alphabet.

7. Click Save to save the alphabet.

   Important: Only the alphabet characters that are supported by the Operating System fonts are rendered properly on the Web UI.

A message Alphabet has been created successfully appears.

Managing Alphabets

After an Alphabet is created, it cannot be modified.

Deleting Alphabets

To remove an Alphabet:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Alphabets.

   The Alphabets tab appears.

2. Select the Alphabet from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Alphabet has been deleted successfully appears.

3 - Masks

Masks are patterns of symbols or characters that can be applied to obfuscate the content of a field. Masks can obfuscate data completely or partially. For example, a partial mask might display the last four digits of a credit card number on a grocery store receipt, while masking the first twelve digits.

You can combine Masks with Data Elements. In this scenario, Masks are applied during presentation to the end-user, after the data has been unprotected. You can also apply Masks on their own, through a Masking Data Element.

You can create, view, and manage Masks by navigating to Policy Management from the main menu, and choosing Data Elements & Masks.

For more information about the properties and behavior of Masks, refer to the section Masking.

Creating Masks

To add a new Data Element:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Masks.

   The Masks tab appears by default.

2. Click Add New Mask.

   The New Mask screen appears.

3. Specify the following common properties for the Mask:

   Property	Description
   Name	Unique name to identify the mask.
   Description	Text describing the mask.
   Mask Template	A pre-defined mask template to use. For detailed characteristics of each Mask Template, refer to the section Masking.
   Mask Options	Detailed characteristics of how a mask is applied on data.
   From Left / From Right	The number of characters from left and right for additional configuration.
   Mask mode	Mask or clear the characters specified in the From Left / From Right property.
   Mask character	The character used for masking.
   Sample Output	Mask simulation based on mask options.

4. Click Save.

Managing Masks

Masks can be fully modified after they have been created.

To modify a Mask:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Masks.

   The Masks tab appears.

2. Click the name of the Mask that you want to modify from the list.

   A screen appears displaying the Mask details.

3. Edit the required details.

4. Click Save.

   A message Mask has been updated successfully appears.

Deleting Masks

To remove a Mask:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Masks.

   The Masks tab appears.

2. Select the name of the Mask from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Mask has been deleted successfully appears.

3.1 - Example - Creating a Mask from a Template

To create a mask:

1. On the ESA Web UI, navigate to Policy Management > Data Elements & Masks > Masks.

2. Click Add New Mask.

   The New Mask screen appears.

3. Enter a unique name for the mask in the Name text box.

4. Enter the description for the mask in the Description textbox.

5. Select CCN 6X4 from the Mask Template drop-down.

6. Select Clear from Mask Mode.

7. Select the masking character from the Character drop-down.

8. Click Save.

A message Mask has been saved successfully appears.

4 - Trusted Applications

Note: Trusted Applications are applicable only for Application Protector. Skip this section if you are not using the Application Protector.

A Trusted Application is an entity that defines which system users and applications are authorized to run the Application Protector. Using a Trusted Application adds another layer of security for operating the system.

A single Trusted Application instance covers a single application and its corresponding system user. Multiple users and applications are not supported under a single Trusted Application and must be created separately.

Creating Trusted Applications

To create a Trusted Application:

1. On the ESA Web UI, navigate to Policy Management > Policies & Trusted Applications > Trusted Applications.

2. Click Add New Trusted Application.

   The New Trusted Application screen appears.

3. Type a unique name to the trusted application in the Name textbox.

4. Type the required description to the trusted application in the Description textbox.

5. Type the name of the application in the Application Name textbox.

   The maximum length of an Application Name is up to 63 characters.

   Important: In case of AP Java and AP Go applications, ensure that you specify the complete module or package name.

   In the application name, you can type the asterisk (*) wild card character to represent multiple characters or the question mark (?) wild card character to represent a single character. You can also use multiple wild card characters in the application name.

   For example, if you specify Test_App* as the application name, then you can use applications with names, such as, Test_App1 or Test_App123 to perform security operations.

   Caution: Use wild card characters with discretion, as they can potentially lead to security threats.

6. Type the name of the application user in the Application User textbox.

   In the application user name, you can type the asterisk (*) wild card character to represent multiple characters or the question mark (?) character to represent a single character. You can also use multiple wild card characters in the application user name.

   For example, if you specify User* as the application user name, then you can have users with names, such as, User1 or User123 to perform security operations.

   Caution: Use wild card characters with discretion, as they can potentially lead to security threats.

7. Click Save.

A message Trusted Application has been created successfully appears.

Managing Trusted Applications

Trusted Applications can be fully modified after they have been created.

Deleting Trusted Applications

To remove a Trusted Application:

1. On the ESA Web UI, navigate to Policy Management > Policies & Trusted Applications > Trusted Applications.

   The Trusted Applications tab appears.

2. Select the name of the Trusted Application from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Trusted Application has been deleted successfully appears.

4.1 - Linking Data Store to a Trusted Application

To link a trusted application to a data store:

1. On the ESA Web UI, navigate to Policy Management > Policies & Trusted Applications > Trusted Applications.

   The list of all the trusted applications appear.

2. Select the required trusted application.

   The screen to edit the trusted application appears.

3. Under the Data Stores tab, click Add.

   The screen to add the data stores appears.

4. Select the required data stores.

5. Click Add.

A message Select Data Stores have been added to Trusted Application successfully appears.

5 - Data Stores

A Data Store is a central concept in Policy Management. It is another built-in safety mechanism for operating the system securely. Data Stores group the Protector locations and the relevant Policies. Only the allowed servers are able to pull the Policy and enforce it.

If more flexibility is required, you can create a default Data Store that deploys the Policy to any Protector that requests it from ESA. This is a valid strategy for Cloud Protectors, such as serverless functions and containers, that frequently update their IP ranges.

You can create, view, and manage Data Stores by navigating to Policy Management from the main menu, and choosing Data Stores.

Note: The maximum length of the data store name is 55 characters.

You cannot create multiple data stores with the same names. You can create only one default data store for a single instance of ESA.

Creating Data Stores

Perform the following steps to create a data store. The Policy Management REST API can also be used to create data stores. For those steps, refer to the Policy Management REST API.

To create a data store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. Click Add New Data Store.

   The New Data Store screen appears.

3. Enter a unique name identifying the data store in the Name textbox.

4. Enter the description describing the data store in the Description textbox.

5. Determine if the new Data Store should be a default Data Store by setting the value to Yes or No.

   If a default data store already exists and you are updating another data store as the default data store, then the following message appears.

   A default Data Store already exists, Please confirm to make this the new default Data Store.

6. Click Ok.

7. Click Save.

A message Data Store has been created successfully appears.

Managing Data Stores

Data Stores can be fully modified after they have been created.

Deleting Data Stores

To remove a Data Store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The Data Stores tab appears.

2. Select the name of the Data Store from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Data Store has been deleted successfully appears.

5.1 - Configuring Allowed Servers

A non-default Data Store will only allow specified servers to pull the dynamically deployed policy or package from it. The policies are applicable for protectors earlier than 10.0.x, while packages are applicable for 10.0.x protectors and later. The list of servers is controlled in the Allowed Servers section.

You may specify a single IP address or a range of IP addresses as Allowed Servers.

Note: Make sure to use IP addresses that are reachable from ESA.

To add Allowed Servers to a Data Store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. From the Allowed Servers tab for the data store, click Add.

   The Add Allowed Servers screen appears.

3. If you want to add a single server, then select Single Server and specify the server IP address.

4. If you want to add a range of servers, then Multiple Servers. Enter the range in the From and To text boxes.

5. Click Add.

The servers are added to the list of Allowed Servers.

5.2 - Export Keys

The data store export key is used to identify the data store and encrypt the resilient package. It is also used by the Node Administrator, who runs the DevOps API, to export the encrypted package. The export key is the public part of an asymmetric public-private key pair. A Key Management System (KMS) administrator, who is responsible for managing the cryptographic keys in your system, creates this public-private key pair in a Key Store. The KMS administrator then shares the public key with the user who has the Security Officer permission in the ESA. The Security Officer adds the public key to the data store. This step is required only if you are distributing the resilient package to Immutable Resilient protectors.
For more information, and example, of using the DevOps process in Immutable Resilient protectors, refer to the section DevOps Approach for Application Protector.

The Security Officer shares the fingerprint of the public key to the Node Administrator.

Adding Export Key

Use the following instructions to add a Public Key to a Data Store.

To add a Public Key to a Data Store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. From the Export Keys tab for the data store, click Add.

   The Add Export Key screen appears.

3. In the Algorithm drop-down list, specify one of the following options:

   • RSA-OAEP-256
   • RSA-OAEP-512

   In case of AWS, the algorithm must be the same one that was selected by the KMS Administrator while creating the asymmetric key pair in the Key Store. Currently, AWS only supports RSA-OAEP-256.

4. In the Description field, add a description to reference the key pair. For example, specify the key name or the key ID.

5. In the Public key drop-down list, choose the PEM file that you have downloaded from the Key Store. The contents of the PEM file appear in the text box below. Alternatively, you can paste the contents of the PEM file in the text box.

6. Click Add.
   The public key is added to the list of keys. A public key can be assigned to only one data store. However, a data store can contain multiple public keys.

7. Click the Copy Fingerprint icon to copy the fingerprint of the public key without the colon separators.
   The user exporting the resilient package uses this fingerprint in the DevOps API that is used to download the resilient package. Note that the DevOps API works even when the fingerprint contains colon separators.

Managing Export Key

After an export key is created, it cannot be modified. However, you can update the RSA algorithm to be used with the key and the description of the key. Only a user with Security Officer permissions can modify an export key.

To modify an export key:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. From the Export Keys tab for the data store, click the Edit Export Key icon for the specified key.

   The Edit Export Key screen appears.

3. In the Algorithm drop-down list, modify the RSA algorithm to be used with the export key.

   Note: In case of AWS, the algorithm must be the same one that was selected by the KMS Administrator while creating the asymmetric key pair in the Key Store. Currently, AWS only supports RSA-OAEP-256.

4. In the Description field, update the description as required.

5. Click Save to save the changes.

Deleting Export Key

Only a user with Security Officer permissions can delete an export key.

To remove an export key:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. From the Export Keys tab for the data store, click the Delete Export Key icon for the specified key.

   A confirmation dialog appears.

3. Click OK.

   A message Export Key has been removed from the Data Store successfully appears.

5.3 - Adding Trusted Applications to the Data Store

For more information about Trusted Applications, refer to the section Trusted Applications.

To add Trusted Application to a Data Store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. Select the data store.

   The screen to edit the data store appears.

3. Click the Trusted Applications tab.

4. Click Add.

   The list of trusted applications created appear.

5. Select the trusted applications.

6. Click Add.

A message Selected Trusted Applications have been added to the Data Store successfully appears.

5.4 - Adding Policies to the Data Store

To add policy to a data store:

1. On the ESA Web UI, navigate to Policy Management > Data Stores.

   The list of all the data stores appear.

2. Select the data store.

   The screen to edit the data store appears.

3. Click the Policies tab.

4. Click Add.

   The list of policies created appear.

5. Select the policies.

6. Click Add.

A message Selected Polices have been added to the Data Store successfully appears.

For more information on creating policies, refer to section Creating Policies.

6 - Member Sources

Member Sources specify the source location of users and groups that will be attached to the Policy Roles.

The following Member Sources are supported:

• User directory, such as:
  • LDAP
  • Posix LDAP
  • Active Directory
  • Azure AD
• Database
  • Teradata
  • Oracle
  • SQL Server
  • DB2
  • PostgreSQL
• File

A Member Source configuration specifies the connection to the chosen directory for retrieving information on user and groups.

Creating Member Sources

The steps to create a member source depend on the source type, as shown in the following table.

Managing Member Sources

Member Sources can be fully modified after they have been created.

Deleting Member Sources

To remove a Member Source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Sources > Member Sources.

   The Member Sources tab appears.

2. Select the name of the member source from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Member Source has been deleted successfully appears.

Testing Connection

Before configuring the Member Source, it is advised to test that a connection to the specified directory can be established.

To test the connection, click Test adjacent to the Member Source entry from the list or from the respective Member Source screen. The Test Member Source Connection dialog box displays the status along with the following information:

• connection
• authentication
• groups
• users

Note: The password length of a member source on some platforms may have a limitation.

6.1 - Configuring Member Sources

Configure the Member Sources based on the source type, as shown in the following table.

6.1.1 - Configuring Active Directory Member Source

To create an Active Directory member source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name of the file member source in the Name textbox.

4. Type the description in the Description textbox.

5. Select Active Directory from the Source Type drop-down list.

   The Active Directory Member Source screen appears.

6. Enter the information in the directory fields.

   The following table describes the directory fields for Active Directory member sources.

   Field Name	Description
   Host	The Fully Qualified Domain Name (FQDN), or IP of the directory server.
   Port	The network port on the directory server where the service is listening.
   TLS Options	- The Use TLS option can be enabled to create secure communication to the directory server. - The Use LDAPS option can be enabled to create secure communication to the directory server. LDAPS uses TLS/SSL as a transmission protocol. Note: Selection of the LDAPS option is dependent on selecting the TLS option. If the TLS option is not selected, then the LDAPS option is not available for selection.
   Recursive Search	The recursive search can be enabled to search the user groups in the active directory recursively. For example, consider a user group U1 with members User1, User2, and Group1, and Group1 with members User3 and User4. If you list the group members in user group U1 with recursive search enabled, then the search result displays User1, User2, User3, and User4.
   Base DN	The base distinguished name where users can be found in the directory.
   Username	The username of the Active Directory server.
   Password/Secret	The password of the user binding to the directory server.

7. Click Save.

A message Member Source has been created successfully appears.

6.1.2 - Configuring File Member Source

In Policy Management, the exampleusers.txt and examplegroups.txt are sample member source files that contain a list of users or groups respectively. These files are available on the ESA Web UI. You can edit them to add multiple user name or user groups. You can also create a File Member source by adding a custom file.

The examplegroups.txt has the following format.

[Examplegroups]
<groupusername1>
<groupusername2>
<groupusername3>

Note: Ensure that the file has read permission set for Others.

Important: The exampleusers.txt or examplegroups.txt files do not support the Unicode characters, which are characters with the \U prefix.

Viewing the List of Users and Groups in the Sample Files

This sections describes the steps to view the list of users and groups in the sample files.

To view list of users and groups in the sample files:

1. On the ESA Web UI, navigate to Settings > Systems > Files.

2. Click View, corresponding to exampleusers.txt or examplegroups.txt under Policy Management-Member Source Service User Files and Policy Management-Member Source Service Group Files respectively.

The list of users in the exampleuser.txt file or examplegroups.txt file appear.

Creating File Member Source

This section describes the procedure on how to create a file member source.

To create file member source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name of the file member source in the Name textbox.

4. Type the description in the Description textbox.

5. Select File from the Source Type drop-down list.

6. Select Upload file from the User File drop-down list.

7. Click the Browse.. icon to open the file browser.

8. Select the user file.

9. Click Upload File icon.

   A message User File has been uploaded successfully appears.

10. Select Upload file from the Group File drop-down list.

11. Click the Browse.. icon to open the file browser.

12. Select the group file.

13. Click Upload File icon.

    A message Group File has been uploaded successfully appears.

14. Click Save.

A message Member Source has been created successfully appears.

6.1.3 - Configuring LDAP Member Source

To create an LDAP member source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name of the file member source in the Name textbox.

4. Type the description in the Description textbox.

5. Select LDAP from the Source Type drop-down list.

   The LDAP Member Source screen appears.

6. Enter the information in the LDAP member source fields.

   The following table describes the directory fields for LDAP member sources.

   Field Name	Description
   Host	The Fully Qualified Domain Name (FQDN), or IP of the directory server.
   Port	The network port on the directory server where the service is listening.
   Use TLS	The TLS is enabled to create a secure communication to the directory server. LDAPS, which is deprecated, is no longer the supported protocol. TLS is the only supported protocol.
   User Base DN	The base distinguished name where users can be found in the directory. The user Base DN is used as the user search criterion in the directory.
   Group Base DN	The base distinguished name where groups can be found in the directory. The group base dn is used as a group search criterion in the directory.
   User Attribute	The Relative Distinguished Name (RDN) attribute of the user distinguished name.
   Group Attribute	The RDN attribute of the group distinguished name.
   User Object Class	The object class of entries where user objects are stored. Results from a directory search of users are filtered using user object class.
   Group Object Class	The object class of entries where group objects are stored. Results from a directory search of groups are filtered using group object class.
   User Login Attribute	The attribute intended for authentication or login.
   Group Members Attribute	The attribute that enumerates members of the group.
   Group Member is DN	The members may be listed using their fully qualified name, for example, their distinguished name or as in the case with the Posix user attribute (cn) value.
   Timeout	The timeout value when waiting for a response from the directory server.
   Bind DN	The DN of a user that has read access, rights to query the directory.
   Password/Secret	The password of the user binding to the directory server

   Parsing users from a DN instead of querying the LDAP server: By default, a user is not resolved by querying the external LDAP server. Instead, the user is resolved by parsing the User Login Attribute from the Distinguished Name that has been initially retrieved by the Member Source Service. This option is applicable only if the Group Member is DN option is enabled while configuring the Member Source. In this case, the members must be listed using their fully qualified name, such as their Distinguished Name. If the ESA is unable to parse the DN or the DN is not available in the specified format, the user is resolved by querying the external LDAP server.

7. Click Save.

A message Member Source has been created successfully appears.

6.1.4 - Configuring POSIX Member Source

You can retrieve users and user groups from any external LDAP and Posix LDAP. The internal LDAP available on ESA, uses the Posix schema. Thus, when using ESA, it is recommended to use Posix LDAP to configure the connection with the internal ESA LDAP.

To create a Posix LDAP member source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name of the file member source in the Name textbox.

4. Type the description in the Description textbox.

5. Select Posix LDAP from the Source Type drop-down list.

   The Posix LDAP Member Source screen appears.

6. Enter the information in the directory fields.

   The following table describes the directory fields for Posix LDAP member source.

   Field Name	Description
   Host	The Fully Qualified Domain Name (FQDN), or IP of the directory server.
   Port	The network port on the directory server where the service is listening.
   Use TLS	The TLS can be enabled to create a secure communication to the directory server.
   Base DN	The base distinguished name where users can be found in the directory.
   Username	The username of the Posix LDAP server.
   Password/Secret	The password of the user binding to the directory server.

7. Click Save.

A message Member Source has been created successfully appears.

6.1.5 - Configuring Azure AD Member Source

To create an Azure AD member source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Sources > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name of the Azure AD member source in the Name textbox.

4. Type the description in the Description textbox.

5. Select Azure AD from the Source Type drop-down list.

   The Azure AD Member Source screen appears.

6. Enter the information in the directory fields.

   The following table describes the directory fields for the Azure Active Directory member sources.

   Field Name	Description
   Recursive Search	The recursive search can be enabled to search the user groups in the Azure AD recursively.
   Tenant ID	The unique identifier of the Azure AD instance
   Client ID	The unique identifier of an application created in Azure AD
   Environment	The Azure cloud environment used for the Azure AD Member Source. Default value is “Public Cloud”.
   User Attribute	The Relative Distinguished Name (RDN) attribute of the user distinguished name. The following user attributes are available: - displayName - The name displayed in the address book for the user. - userPrincipalName - The user principal name (UPN) of the user. - givenName - The given name (first name) of the user. - employeeId - The employee identifier assigned to the user by the organization. - id - The unique identifier for the user. - mail - The SMTP address for the user. - onPremisesDistinguishedName - Contains the on-premises Active Directory distinguished name (DN). - onPremisesDomainName - Contains the on-premises domainFQDN, also called dnsDomainName, synchronized from the on-premises directory. - onPremisesSamAccountName - Contains the on-premises samAccountName synchronized from the on-premises directory. - onPremisesSecurityIdentifier - Contains the on-premises security identifier (SID) for the user that was synchronized from the on-premises setup to the cloud. -onPremisesUserPrincipalName - Contains the on-premises userPrincipalName synchronized from the on-premises directory. - securityIdentifier - Security identifier (SID) of the user, used in Windows scenarios.
   Group Attribute	The RDN attribute of the group distinguished name. The following group attributes are available: - displayName - The display name for the group. - id - The unique identifier for the group. - mail - The SMTP address for the group. - onPremisesSamAccountName - Contains the on-premises SAM account name synchronized from the on-premises directory. - onPremisesSecurityIdentifier - Contains the on-premises security identifier (SID) for the group that was synchronized from the on-premises setup to the cloud. - securityIdentifier - Security identifier of the group, used in Windows scenarios.
   Group Members Attribute	The attribute that enumerates members of the group. Note: Ensure to select the same Group Members Attribute as the User Attribute. The following group members attributes are available: - displayName - The name displayed in the address book for the user. - userPrincipalName - The user principal name (UPN) of the user. - givenName - The given name, or first name, of the user. - employeeId - The employee identifier assigned to the user by the organization. - id - The unique identifier for the user. - mail - The SMTP address for the user. - onPremisesDistinguishedName - Contains the on-premises Active Directory distinguished name (DN). - onPremisesDomainName - Contains the on-premises domainFQDN, also called dnsDomainName, synchronized from the on-premises directory. - onPremisesSamAccountName - Contains the on-premises samAccountName synchronized from the on-premises directory. - onPremisesSecurityIdentifier - Contains the on-premises security identifier (SID) for the user that was synchronized from the on-premises setup to the cloud. - onPremisesUserPrincipalName - Contains the on-premises userPrincipalName synchronized from the on-premises directory. - securityIdentifier - Security identifier (SID) of the user, used in Windows scenarios.
   Password/Secret	The client secret is the password/secret of the Azure AD application.

7. Click Save.

A message Member Source has been created successfully appears.

6.1.6 - Configuring Database Member Source

You use the Database type to obtain users from database, such as, SQL Server, Teradata, DB2, PostgreSQL, or Oracle. An ODBC connection to the database must be setup to retrieve user information.

The following table describes the connection variable settings for the databases supported in Policy Management.

Creating Database Member Source

This section describes the procedure on how to create a database member source.

To create a Database Member Source:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Member Sources.

2. Click Add New Member Source.

   The New Member Source screen appears.

3. Enter a unique name for the file member source in the Name text box.

4. Type the description in the Description text box.

5. Select Database from the Source Type drop-down list.

6. Select one of the following database from the Source drop-down list.

   • Teradata
   • Oracle
   • SQL Server
   • DB2
   • PostgreSQL

7. To enable the usage of a custom data source name, switch the Use Custom DSN toggle.

   1. Enter the custom data source name in the DSN text box.
   2. Ensure that the specified DSN is present in the odbc.ini configuration file located in the /opt/protegrity/mbs/conf/ directory.

8. If you are selecting the Oracle database as the source database, then enter the service name in the Service Name text box.

   Note: This step is applicable for the Oracle database only.

9. If you are not using Custom DSN, then the following steps are applicable.

   1. Enter the database name in the Database text box.

   2. Enter the host name in the Host text box.

   3. Enter the port to connect to the database in the Port text box.

10. Enter the username in the Username text box.

11. Enter the password in the Password text box.

12. Click Save.

The message Member Source has been created successfully appears.

7 - Roles

A Role is a grouping of users that interacts with data in Protegrity Data Security Platform. A Role can consist of users, groups, or a combination of both. It can be configured for Manual, Automatic, or Semi-Automatic retrieval of its members. Each Role is associated with specific data access privileges in the policy.

You can create, view, and manage Roles by navigating to Policy Management from the main menu, and choosing Roles & Member Sources.

Creating Roles

To create a role:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Roles.

2. Click Add New Role.

   The New Role screen appears.

3. Enter a unique name for the role in the Name textbox.

   Note: Ensure that the length of the role name does not exceed 55 characters.

4. Enter the required description for the role in the Description textbox.

5. In the Mode drop-down, select a refresh mode.

   For more information about about mode types for a role, refer to section Role Refresh Modes.

6. If you want to apply this role to all members in all the member sources, click Applicable to all members. If enabled, the role is applied to all members in users or groups that do not belong to any other role.

   Note: It is recommended to enable Applicable to all members option only for unauthorized user roles. Using it for authorized roles may result in unintentionally open access level to sensitive data.

7. Click Save.

Managing Roles

Roles can be fully modified after they have been created.

Deleting Roles

To remove a Role:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Sources.

   The Roles tab appears by default.

2. Select the name of the role from the list, and click the Delete action.

   A confirmation dialog box appears.

3. Click OK.

   A message Role has been deleted successfully appears.

7.1 - Role Refresh Modes

The Member Sources that you have configured will change over time, as users and groups are added and removed. You can control how those changes are deployed to the Policy by choosing your preferred Refresh Mode.

The following three refresh modes are supported for the Roles:

1. Manual Mode
   In Manual Mode, you manually synchronize the Role members and manually deploy the Policy. For more information on synchronizing members, please refer to the section Managing Members in a Role.

   After the synchronization is done, you must set the Policies linked to the Role as Ready to Deploy, followed by deploying the Policy manually.

   The Manual Mode accepts both groups and users.

2. Semi-Automatic Mode
   In Semi-Automatic Mode, you manually synchronize the Role members, whilst the Policy deployment is automatic. For more information on synchronizing members, please refer to the section Managing Members in a Role.

   The updated Policy is deployed automatically after the synchronization.

   The Semi-Automatic Mode accepts groups only.

3. Automatic Mode
   In Automatic Mode, both the Role member synchronization and the Policy deployment are automatic. The updated Policy is deployed automatically after the synchronization.

   The Automatic Mode accepts groups only.

Automatic Synchronization and Deployment

Synchronization is performed by the Member Source component. Every hour it pulls the latest changes made in the external Member Sources such as LDAP, AD, file, or database. HubController communicates with the Member Source to update the policy with any changes detected in Roles.

Role Conflicts

The HubController checks for conflicts in the user name capitalization. If there are users of the same name, but different capitalization, that are configured within different roles, an error will be generated in the Hub Controller logs.

This error appears in the Notifications section of the ESA dashboard to inform you that such conflicting users have been found. The error specifies the correlation ID of the HubController audit log that has been generated. To identify the conflicting users, navigate to the Discover page in the Audit Store Dashboards and search for the specified correlation ID.

7.2 - Adding Members to a Role

To add Members to a Role:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Roles.

2. Click on the role name link to which you want to add members.

   The selected role screen appears.

3. In the Members tab, click Add.

   The Add Members screen appears.

4. In the Choose Member Source drop-down, select the Member Source.

5. In the Display Member Type drop-down, select the member type.

   Automatic or Semi-Automatic mode causes the removal of members of type Users from the role. The Display Member Type drop-down is disabled in this case with default Group member type.

6. Enter the filter parameter in the Filter Members text box.

   It accepts characters such as * to display all results or word search to search with a word.

   For more information about filtering members from AD and LDAP member sources, refer to the sections Filtering Members from AD and LDAP Member Sources and Filtering Members from Azure AD Member Source.

7. Select the number of display results in the Display Number of Results spin box.

8. Click Next.

   The step 2 of Add Members dialog box appears.

9. Select the check box next to each member you want to add.

10. Click Add.

    The selected members are added to the role.

**Note:** The **ID** column displays the unique identifier for the Azure AD, Posix LDAP and Active Directory member sources.

11. Click Save to save the role.

7.2.1 - Filtering Members in a Role

By using filtering, you can add specific members to a Role. The filtering mechanism uses search filters based on user-provided criteria for filtering the Member Sources.

7.2.1.1 - Filtering Members from AD and LDAP Member Sources

You can filter members from Active Directory, LDAP, and POSIX LDAP using the following search convention.

If the input in the search filter includes special characters, then you must use the escape sequence in place of the special character to make it a valid input in the search filters.

The following table lists the escape sequence for each of the special characters.

The following table lists some examples of search filters with the usage of escape sequences to include special characters in the search input.

7.2.1.2 - Filtering Members from Azure AD Member Source

You can filter members from Azure Active Directory using the following search convention.

7.3 - Managing Members in a Role

Note: The ID column in the Members tab displays the unique identifier for the Azure AD, Posix LDAP and Active Directory member sources.

The following actions are available within the Members section of a Role.

7.4 - Searching Members

The Search Member tab from the Roles & Member Sources screen enables you to search for members within configured Roles. It provides additional information about the users, such as their added time, member source, and associated roles.

To search a member:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Search Member.

2. Enter the search criteria in the Member Name textbox.

   For more on valid search criteria, refer to Search Criteria.

3. Click the Search icon.

The search results appear.

Search Criteria

Consider the following scenario:

1. You have created a file member source named MemberSource1 which includes:
   • Group File named examplegroups with users examplegroupuser1 and examplegroupuser2.
   • User File named exampleusers with users exampleuser1 and exampleuser2.
2. You have created a role named Role1.
3. You have added all users from MemberSource1 to Role1.

For the given example, the following table lists the search results with different search criteria.

Table: Search Criteria

Search Criteria	Description	Output
Wild card	Search with *.	It displays all the members.
Character search	Search with 1.	It displays examplegroupuser1 and exampleuser1.
Word search	Search with group.	It displays examplegroupuser1 and examplegroupuser2.

You can perform additional actions on the search results such as:

• Clicking on the Role or Source column values redirects you to the Roles or Member Sources page respectively.
• Members can be sorted based on Name, Added Time, Role or Source columns.
• Search results also can be filtered with another search option, which is provided in the search results.

7.5 - Searching Member Access

The Search Member Access tab on the Roles & Member Sources screen enables you to check effective permissions for a user. This can be done if a user is assigned a role and that role is linked to policies. It provides additional information about effective permissions for a user on data elements mapped in policies. It will also show permissions for each policy and the final permission when multiple policies are connected to the datastore.

Note: Ensure that the policies are deployed to view the permissions.

It provides options to view effective permissions.

• Simple view: It shows the final permission granted to a user on data elements mapped in policies. This consolidated view is ideal for quickly understanding the user’s overall access.

• Advanced view: It shows a detailed breakdown of permissions. It displays both the final effective permission and the individual permissions granted by each policy.

  For example; a policy user can be associated with multiple roles, each configured with distinct Data Element permissions. The table below illustrates that role R1 is directly linked to Data Element DE1 across Policies P1, P2, and P3. These policies are deployed to the same data store. As a result, role R1 inherits a combined set of permissions, forming an effective policy that merges all applicable role permissions for DE1.

  Table: Policy Structure in the ESA

  Policy	Role	User	Data Element	Permission
  P1	R1	U1	DE1	Protect (P)
  P2	R1	U1	DE1	Unprotect (U)
  P3	R1	U1	DE1	Reprotect (R)

  The following table lists the effective permissions after deploying the policies to same datastore.

  User	Data Element	Effective Permissions
  U1	DE1	P, U, R

  In the context of the policy structure and effective permissions, the Simple view presents the final, effective permissions a user has on a data element, regardless of how those permissions were granted. This tells us that User U1 has the ability to Protect, Unprotect, and Reprotect data in DE1, without showing how those permissions were assigned.

  The Advanced View breaks down the underlying policy structure, showing how permissions are granted through roles and policies. It’s useful for auditing, debugging, or understanding permission inheritance. This shows that:

  • Role R1 is assigned to User U1.
  • R1 is granted different permissions on DE1 across three policies (P1, P2, P3).
  • When these policies are deployed to the same data store, the permissions are merged, resulting in the effective permissions shown in the Simple view.

To search member access:

1. On the ESA Web UI, navigate to Policy Management > Roles & Member Source > Search Member Access.

2. Enter the search criteria in the Member Name textbox.

3. Click the Search icon.

   The search results appear with the search member name, associated data store, member status, and view member permissions information.

   Note: If multiple users have the same search member name, only the first 10 results will be displayed. For example, the search member name “test” will return results for the provided name, with variations like “test”, “testuser”, and so on. The search will display the first 10 matching results.
   To avoid this, use an exact username instead of a common name for the search member name.

4. In the View Member Permissions column, click the View Member Permissions icon. The Permissions dialog box appears.

   Note: The Permissions dialog box displays information in the Simple View mode. It shows the member access set on Data Elements for the associated Data Store. It is displayed after policies and role permissions has been merged. You will also see how data is returned in the Output column.

5. Click the Advanced View button. The Permissions dialog box appears in the Advanced View mode.

   Note: This mode includes a Role column that displays permissions derived from merged policies connected to the Data Store. It also includes a Policy [Role] column, showing the permission set for a role on a specific policy.