Encompass Security Configuration

Encompass Security Overview

Encompass security capabilities are layered, configurable and flexible allowing integration into different enterprise environments. The tiers of encompass security are as follows: 

  • First Layer : User Authentication
  • Second Layer: Application Authorization
  • Third Layer: Data Security 


Authentication is the ability for Encompass to obtain and trust an authorized user id. Encompass supports the following types:

1)    Integrated User database. This is most basic form provided by encompass, and requires manual entry of user id’s and account creation via the embedded Admin panel. This mode is not intended for wide scale enterprise deployment, rather is a mode suitable for testing, or small deployments where enterprise authentication is not available.  The user will be prompted for a userid and password, which is compared against that stored in the encompass database.

2)     LDAP Integration – in this mode, encompass will prompt the user for a user id, and password, this will be compared to the LDAP server configured. Encompass will received a pass/fail if the user ID and password are valid.

3)    Header based SSO: Encompass can support identifying a valid user ID from the request header.  Encompass is assumed to be an environment where the specified header field can be trusted as valid for the user based on the companies SSO environment.

4)    SAML 2.0 – Encompass can support SAML 2.0 authentication for SSO, using the apache Shibboleth Service Provider module.  In this mode Shibboleth acts as the SP, and assumes a compatible IDP and existing SAML infrastructure.  SP agent then obtains a valid user-id and passes that along to encompass. 

Application Authorization

Once encompass has obtain a authenticated userid Encompass may optionally be configured to authorize the user to utilize Encompass.  This is used in environments where the SSO infrastructure is not capable of authorizing a user to a given endpoint.   Encompass maintains a database of authorized userids.  If the userid exists in this database, the user is then permitted to utilize Encompass and its features. If the userid is not located then the following error message is displayed.

Encompass does not provide a management UI for authorization, this capability is provided with a standard data import format, and is intended to be integrated with an external system that controls user authorization.

Data Security 

The last layer in the Encompass security tiers deals with Authorization to specific data elements based on a basic role assignment.  Encompass provides a configurable capability to restrict access to items stored in the index.  When an item is restricted for a given role it is as though that item simply is NOT in the encompass index. Therefore the item can not be seen, cannot be searched or discovered, and will not contribute to search result counts, filter values its.

Item level security is based on item level privileges associated with specific roles.  If the user role(s) specifies a restricted privileges on certain data the user will be unable to see, discover  or otherwise know anything about any items linked to those restricted roles. Item level restrictions are computed directly into the index and associated with each restricted item.   The mapping of a user  ID to a Role is handled in a set of external tables, and is designed to be integrated or synchronized with an external system administering the data privileges.

Standard Configuration

The following will describe the steps needed to configure the various security elements of Encompass.


Embedded Authentication

Encompass out of the box is configured for its embedded authentication. In this model, login into encompass as the administrator user (contact perception software on obtaining your admin credentials), then navigate to the administrative panel, to add/remove or configure users.

LDAP Based Authentication

Encompass supports authentication using LDAP. Encompass will take the username and password supplied at the login screen. This will be used to verify against the LDAP directory. If a positive response is provided from LDAP then the user will be allowed into the application.

To configure the LDAP edit the following properties in the webtop.properties file, located in the $ENCOMPASS_HOME/conf directory.



OAM & CA-SiteMinder SSO Authentication

Encompass requires no additional configuration to work with header based SSO’s. Encompass is configured to extract the userid from SSO infrastructures based on Oracles OAM, and CA-SiteMinder.

SAML 2.0 Authentication

SAML 2.0 utilizes Apache Shibolleth as the SP.  A traditional SP installation and proxy must be configured, and the SP endpoint registered via metadata exchange with the IDP.   Please refer to Perceptions SAML 2.0 configuration how-to for more details. The SP will provide to encompass  the information required such as the authorized user-id in the request headers. No additional configuration beyond properly configuring the SP and reverse proxy is required.  More information may be found here (SAML 2.0 Configuration).

General Authentication Notes

Regardless of the form of authentication used, an application server restart is required for these changes to picked up.


Configuring Application Authorization

Encompass can be configured to read a table of users and groups. This table is utilized to enable authorization to the entire Encompass application, given an authenticate user. This is typically utilized in conjunction with SSO implementations where the SSO environment cannot be configured to authorize a user to a given system.

To configure application level authorization a database with the following table structure is required to pre-exist. Encompass will consult this list at login attempt to determine if a user may proceed.

Example table:









The username must be the matching username found from the SSO authentication, the Group ID is numeric value, or other unique id provided by the system of record.

Encompass must be configured to point to this database, using the following configuration file located in the config file directory.

Edit the file: “security_usersgroups.properties” located in the ${ENCOMPASS_HOME}/dataload/conf directory


Example Configuration File:







[onramp.query=select count(*) from auth_groups_table_isearch ag, user_groups_table_isearch ug where ag.group_id = ug.group_ids and ug.username = ?

The above file must be configured to specify the HOSTNAME, PORT, USERNAME and PASSWORD for database housing the usernames and groupid.

Item Level Security Configuration 

Item Level security is based on a configurable list of index fields, which contain lists of restricted user roles.  If a user belongs to a restricted user role, AND the item is associated with at least one of the restricted roles, the items will be removed from ALL users search results.

To Configure the Item Level Security, the following steps are required.

The encompass item level security is data driven, and requires data fields linked with the items to be secured. The Encompass ETL process needs to be informed of these fields so the correct metadata can be loaded into the index. Additionally the encompass application needs be made aware of which roles a given user is associated with. This is accomplished via a simple database table. Encompass relys on an existing enterprise grade database infrastructure to accommodate this data.

Updating Index with Restricted Data Access Privileges 

ETL must be configured to extract or otherwise obtain fields about an item that list the roles that will have a restricted access to each item.  Therefore it is a prerequisite to configure an ETL datasource or process to have or to produce one or more fields containing a list of restricted roles. The restricted role fields must be a text/string field containing a comma-separated list of role names. For example:

Agile PLM, may be configured with a TextField, called “RestrictedRoles”. This property is then set on one or more items in Agile PLM to have values such as “external_supplier, contractor, limited_access”.

Configure ETL for the Restricted Role Fields

For ETL to properly encode the fields into the index, it is required to tell ETL what Fields  in the extracts are to be used as sources of role restrictions. These fields that were updated into the index (or may already exist)

Multiple fields are allowed. For Example, assume a Agile PLM Field call “RestrictedRoles”, and customer database field called “RestrictectedContractors” has been extracted.

The “restricted_fields”  property should be set in the security module's rakefile with the following:

security_fields = “RestrictedContractors, RestrictedRoles”                                                               

4) Configure User to Role Mapping Database.   This is a single table, that describes the user, to role mapping.   The database has two columns, USERID and ROLE.  A User may have multiple roles, hence multiple entries. Encompass assumes this table is kept current by another system or process. Encompass will only ever read this database. This database must exist, and be populated for security policy to take affect.


Example Restricted Roles Table:









Configure the “restrictedroles.properties” file with the following information to connect to the database:

Example Configuration File: “restrictedroles.properties”







[onramp.query=select count(*) from auth_groups_table_isearch ag, user_groups_table_isearch ug where ag.group_id = ug.group_ids and ug.username = ?


The ROLE(s) listed for each user must match the roles used in the fields specified by the securityfields property.

Production Execution and Updates

Once the changes have been implemented the index needs rebuilt, and the application restarted. The new security policy based on the restricted fields, and user to role database will be active.

User to role mappings may be made update at any point. However, the change in access will not be reflected until the user initiates a new sessions. This occurs automatically based on a timeout (default 3600 seconds) when the user is forced to logout, or if the user creates a new login attempt.

Changes to the restricted roles fields associated with each item in the index can only be refreshed upon a index refresh. This will be based on the index update cycle, commonly a nightly process.

Process Review

At this point the following sequence of events should occur:

1)   Encompass determines the list of restricted roles the user is mapped to by interrogating the database specified in the security.properties file

2)    User issues a query using any of the encompass methods

3)    Encompass removes any result for which any of the user restricted roles are contained in any of the fields listed in the “securityfields” property.



Have more questions? Submit a request


Article is closed for comments.
Powered by Zendesk