# SailPoint OnGuard Connector Documentation > OnGuard Connector Documentation # Documentation # Connecting SailPoint and OnGuard To connect SailPoint with OnGuard, perform the following tasks: ## Adding the Source in SailPoint To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs. > [!IMPORTANT] > > By default, the provisioning feature is **disabled**, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration. **To configure a new source:** 1. Sign in to SailPoint. 2. Go to **Admin \> Connections \> Sources**. 3. Select **Create New**. 4. Search for the connector by entering the name in the search box, and then select **Configure**. 5. In the **Source Name** field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters. 6. In the **Description** field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters. 7. In the **Source Owner** field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to [Assigning a Source Owner](). 8. Under **Connection Type**, select **Direct Connection** or **Flat File**. - **Direct Connection** - A direct connection fetches data from the **Virtual Appliance Cluster** you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the [Virtual Appliance Reference Guide](). - **Flat File** - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable. 9. If you selected **Direct Connection**, in **Virtual Appliance Cluster**, select the virtual appliance cluster that will be used as the application connector for the source. 10. (Optional) Select a governance group to grant its members [source]() or [role]() sub-admin level oversight of the source and its access. For more information, refer to [Creating and Managing Governance Groups](). 11. If this source represents a primary system containing your organization's personnel records, select the **Authoritative Source** checkbox. For more information, refer to [Creating Identity Profiles](). 12. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Base Configuration Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary. 1. Enter a unique name and description for the source. 2. In the **Source Owner** dropdown list, select the identity that owns this source. - To find a source owner, begin entering their name. 3. In the **Virtual Appliance Cluster** dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to [SailPoint Virtual Appliances](). 4. (Optional) If enabled for your organization, select the **Use a Credential Provider** checkbox to manage the source's authentication using a credential provider. > **Note** > > To add a credential provider, go to **Admin \> Connections \> Credential Providers**. For more information about credential providers, refer to [Credential Providers](). 5. Configure the authentication to allow SailPoint to connect to the source. Refer to [Connection Settings](<#connection-settings>) for more information. 6. (Optional) In the **Governance Group for Source Management** dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to [Associating Governance Groups with a Source](). 7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default. - **Enable Provisioning** - Set the toggle to **Enabled** to allow the source to create, update, and deactivate accounts in the connected source system. - **Disable Provisioning** - Set the toggle to **Disabled** to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source. 8. Select **Save**. ## Connection Settings Provide the information required to connect to and interact with the source. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() To configure connection settings, complete the following: 1. Enter the **Host URL** to connect to the OnGuard Instance. For example, you can use the following: `https://:` Contact your OnGuard Administrator for the host URL. 2. Select the **Authentication Type** used to connect to the OnGuard system. 3. Enter the service account **Username** required to connect to the OnGuard system. 4. Enter the **Password** required to connect to the OnGuard system. 5. Select **Save**. ## Time Zone Settings To configure connection settings, complete the following: > [!NOTE] > > **Screenshot** > > [![Time Zone Settings]()]() 1. Select the **Time Zone** of the system hosting the OnGuard service to ensure that connector operations are synchronized with the correct local time. If the system where the OnGuard solution is running uses the UTC timezone, the same timezone should be selected here. > **Note** > > If the selected timezone does not match the actual timezone of the OnGuard system's machine, it may result in operation failures or data inconsistencies. 2. Select **Save**. ## Segment Settings > [!NOTE] > > If segmentation is **not enabled** in the OnGuard system, you may skip this section. To configure segment settings, complete the following: > [!NOTE] > > **Screenshot** > > [![Segment Settings]()]() 1. Enable **Segment Mode** to manage the connector's operations to specific data segment. 2. In the Segment Options field, select **Access to all segments** to allow the connector to manage cardholders across all segments. 3. Select **Access to specific segment** to allow the connector to manage cardholders only within the segment specified in the Segment Name field. 4. In the **Segment Name**, provide exact segment unit or segment group name as configured in OnGuard System. 5. Select **Save**. > [!IMPORTANT] > > - If segmentation is enabled in the OnGuard system, ensure that the connector's Segment Settings match exactly with the OnGuard configuration. > - Incorrect or mismatched segment configurations can result in: > > - Connector operation failures > - Incorrect data read or update operations ## Aggregation Settings Use the settings available in **Aggregation Settings** to adjust aggregation processes as required for your organization. For more information about aggregation, refer to [Loading Account Data](). ### Configuring Page Size > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() 1. In the **Page Size** field, enter the number of records to aggregate in a single page when iterating over large datasets. You can set from 1 to 100. The default is 100. ### Filtering Cardholders By default, the OnGuard connector only aggregates cardholders with active badges. > [!NOTE] > > **Screenshot** > > [![Filter Criteria For Cardholders]()]() Configure the connector to include additional cardholders as well. 1. Select **Aggregate Cardholders with Inactive Badges** checkbox to include cardholders who have inactive badges assigned to them in aggregation processes. 2. Select **Aggregate Cardholders without Badges** checkbox to include cardholders without badges in aggregation processes. 3. Select **Save**. ### Account Aggregation If **Segment Settings** are enabled, account aggregation is performed as follows: 1. Segment Unit Segment name: Austin (Segment Unit) - All cardholders whose primary or additional segment is Austin. - All cardholders assigned to the `` (-1) segment. 2. Segment Group Segment name: United States (includes Austin, New York) The connector aggregates: - Cardholders whose primary or additional segment is United States. - Cardholders whose primary segment is Austin or New York. - Cardholders assigned to `` (-1). ### Group Aggregation If **Segment Settings** are enabled, group aggregation is performed as follows: - In group aggregation, **Segment Filter** settings apply only to Access Levels, not to Badge Types. - The connector aggregates Badge Types from all available segments, regardless of segment selection. - Segment Unit Segment name: Austin (Segment Unit) The connector aggregates: - All Badge Types from the system. - Access Levels whose primary segment is Austin. - Segment Group Segment name: United States (includes Austin, New York) The connector aggregates Access Levels whose primary segment is United States, Austin, or New York. ## Deactivation Settings With these settings, SailPoint needs to know which badge statuses of the cardholder should be considered inactive. If a badge has a status listed in the Deactivation Status List, that badge is considered inactive. Cardholders with a status listed in the **Deactivation Status List** are considered disabled by SailPoint. If a cardholder's status is not in the list, SailPoint treats the cardholder account as enabled. > [!NOTE] > > **Screenshot** > > [![Deactivation Settings]()]() 1. In the **Default Deactivation Status** field, enter the default status for deactivated cardholders. 2. In the **Deactivation Status List** field, enter deactivation statuses as configured in the source system. Type each status and press **Enter** to add it to the list. 3. Select the **Validate Deactivation Statuses** checkbox to entered deactivation statuses are valid. ### Checking Deactivation Status in OnGuard System To find the deactivation status in the OnGuard system, follow these steps: 1. Log in to the System Administration. 2. Navigate to the following path: `Administrator > List Builder > Badge Status` ## Delta Aggregation Settings The first full account aggregation is a one-time operation performed using the OpenAccess API. After the initial full aggregation completes successfully, all further account aggregations must be performed as delta aggregations. These updates are managed by the **OnGuard Event Subscriber Service**, which subscribes to relevant business events. ### SailPoint Use of Durable Subscription in OnGuard Event Subscription Service > [!NOTE] > > Acceptable Limitation (Durable Subscription) The SailPoint OnGuard Integration subscribes to Cardholder and Badge changes via the Web Event Bridge. Due to a limitation of the Web Event Bridge, the following behavior applies: - If a disconnect between the Web Event Bridge and the durable event subscriber lasts less than 30 seconds, all events that occurred during that time are still delivered once the subscriber reconnects. - If the disconnect lasts more than 30 seconds: - Events that occurred during the first 30 seconds of the disconnect will not be delivered. - Events occurring after the first 30 seconds will be queued and delivered once the durable event subscriber resumes the existing subscription. ### Configuring Delta Aggregation > [!NOTE] > > **Screenshot** > > [![Delta Aggregation Settings]()]() - The **Delta Aggregation** toggle button is enabled by default. After the first successful full account aggregation, all subsequent aggregations must be delta aggregations using OnGuard Event Subscriber Service. - Full aggregation is only supported during the initial run. - Make sure the system running the Event Subscriber Service is always accessible to ensure delta aggregations work correctly. ### Installing the OnGuard Event Subscriber Service > [!NOTE] > > **Screenshot** > > [![OnGuard Event Subscriber Service Installation]()]() - The **OnGuard Event Subscriber Service** is a prerequisite for the OnGuard Connector to function correctly. It is responsible for managing delta aggregations and must be installed and configured before using the connector. - To install the service, follow the instructions provided in the OnGuard Event Subscriber Service Documentation. Ensure the service is running and accessible before proceeding with the connector configuration. - Once service installed, configure the API settings in the OnGuard Event Subscriber Service API Configuration for Delta Aggregation section. > **Note** > > You are only entitled to download and use components for which you have an active license with SailPoint. The availability of a component for download does not grant you a license to use it. For more information, contact your SailPoint Account Representative or Customer Success Manager (CSM). ### Configuring the Event Subscriber Service API for Delta Aggregation > [!NOTE] > > **Screenshot** > > [![Event Subscriber Service API Configuration for Delta Aggregation]()]() Configure the OnGuard Event Subscriber Service API settings for delta aggregation. - In the **Service URL** field, enter the URL of the OnGuard Event Subscriber Service API. `https://:` - In the **Authentication Type** field, select the type of authorization required to connect with the SailPoint OnGuard Event Subscription Service. - In the **Client Keystore Path (.p12)**, enter the file path to the client identity file (.p12) that contains both the certificate and private key. `/home/sailpoint/client/client.p12` - In the **Client Keystore Password** field, enter the password for the .p12 file. - In the **Client Private Key Password** field, enter the private key password if it is different from the keystore password. Leave this blank if the private key uses the same password as the keystore. - In the **Client Truststore Path (.jks or.p12)** field, enter the file path to the truststore (.jks or .p12) that contains the CA certificates used to validate the server. `/home/sailpoint/client/client-truststore.jks` - In the **Client Truststore Password** field, enter the password for the client truststore. - Select **Save**. ## Provisioning Settings Configure below settings for remove entitlement operations. > [!NOTE] > > **Screenshot** > > [![Provisioning Settings]()]() 1. Select **Deactivate Access Level** to deactivate the access level without removing it from the cardholder. If this option is not selected, the connector will permanently remove the access level. 2. Select **Save**. ## Review and Test Perform a test to confirm the connection to SailPoint. 1. Go to **Review and Test**. 2. Confirm that the entries in each field are correct. If you note any mistakes, return to the section and make corrections. 3. Select **Test Connection**. ## SailPoint Application Onboarding SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to **Discovered Applications** in the SailPoint user interface. For more information, refer to [Application Onboarding]() in the SailPoint SaaS documentation. # Integrating SailPoint with OnGuard > [!NOTE] > > **Integration** > > This is an integration and requires additional licensing or subscriptions to utilize it. For more information, contact your customer success manager. The SailPoint OnGuard Integration enables comprehensive management of cardholders directly through the SailPoint platform, enabling organizations to streamline their security processes and enhance control over physical access. This integration has capabilities for cardholder management, including the management of access levels and badge types. This document provides detailed information about the requirements and field definitions necessary to successfully implement and manage an OnGuard Integration. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features The SailPoint OnGuard Integration supports the following features: ### Account Management - Manages OnGuard cardholders - Aggregate and Refresh cardholders - Create and Update cardholders - Enable and Disable cardholders - Add and Remove Entitlements to the cardholder. Refer to [Adding and Removing Entitlements]() for more information. - Delete Cardholder - Aggregate and provision custom cardholder attributes ### Entitlement Management Aggregate and refresh the following as group objects: - Badge Type - Access Level ## Prerequisites Before you configure your OnGuard connector, you must consider the following prerequisite items: - Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](). - A valid OnGuard license with part IPC-013-SAILP01. - The SailPoint OnGuard Integration SKU. - The OnGuard Event Subscription Service installed and configured. - This service is required to receive delta events, since a full aggregation can only run once in a lifetime. - For setup instructions, refer to the [OnGuard Event Subscription Service Setup]() documentation. ### Prerequisites for the OnGuard System 1. Enable Software Events. Ensure that **Generate Software Events** is enabled under **Administration \> General System Options** so the system can capture events. ### Prerequisites for the SailPoint OnGuard Connector (VA ↔ OnGuard Server) 1. Use a Fully Qualified Domain Name (FQDN). For a successful connection, always use the FQDN of the machine hosting the OnGuard (On-Premise) solution instead of its IP address. Confirm the FQDN with your OnGuard administrator or IT team. 2. Install the OnGuard Root Certificate in the Java cacerts Store. - To establish a trusted SSL connection with OpenAccess, you must install the OnGuard Server Root Certificate into the Java cacerts certificate store. - Obtain the root certificate from your OnGuard Server. - Add certificate to `/home/sailpoint/certificates` - If you encounter any issues during the import process, refer to [Troubleshooting](). ### Prerequisites for the OnGuard Event Subscription Service (RHEL Machine) Ensure the Event Subscriber Service is running successfully without errors. For setup instructions, refer to the [OnGuard Event Subscription Service Setup]() documentation. ### Prerequisites for the SailPoint OnGuard Connector ( VA↔ Event Subscriber Service) The OnGuard Event Subscription Service requires mutual TLS (mTLS) to establish secure communication between the SailPoint VA client and the SailPoint OnGuard Event Subscription Service. Before running the installer, make sure the following keystore and truststore files are prepared: **Server-Side Files** Required on the SailPoint OnGuard Event Subscription Service. For more details, see [OnGuard Event Subscription Service Setup](). - Server Identity Keystore (server.p12) Contains the server's private key and corresponding certificate. - Server Truststore (truststore.jks) Contains the client's Certificate Authority (CA) certificate(s). **Client-Side Files** Required on the VA side for delta aggregation. For more details, refer to [Delta Aggregation Settings](). - Client Identity Keystore (client.p12) Contains the client's private key and corresponding certificate. - Client Truststore (client-truststore.jks) Contains the server's Certificate Authority (CA) certificate(s). **Responsibility for File Preparation** - Server-side files (server.p12, truststore.jks) are typically generated and maintained by the OnGuard/Customer IT security team. - Client-side files (client.p12, client-truststore.jks) are generated and configured by the SailPoint implementer or the customer PKI team, depending on the deployment model. - It is essential that both parties securely exchange the required CA certificates to ensure successful mTLS handshake. In the VA, navigate to the path `/home/sailpoint/` and create a new directory named OnGuard\_Certificates. Place the client-side files `client.p12` and `client-truststore.jks` inside this folder. These files will be used to configure the mTLS (Mutual TLS) connection within the [Delta Aggregation Settings](). ## Supported Managed Systems The SailPoint OnGuard connector has been certified for the following OnGuard version: - OnGuard System 8.3 ## Required Permissions In OnGuard, service account permissions are organized through permission groups. To set up the service account, follow these steps: 1. Go to **Administration** \> **Users**. 2. Create a System Permission Group: - Go to the **System Permission Groups** tab. - Select **Add** and enter the name: (e.g., **Min Permission System Group**) - Assign the appropriate System permissions as required (refer to the below table). Select the Save to apply your configurations. 3. Create a Cardholder Permission Group - Go to the **Cardholder Permission Groups** tab. - Select the **Add** and enter the name: (e.g., **Min Permission Cardholder Group**) - Assign the appropriate Cardholder permissions as required (refer to the below table). Select the Save to apply your configurations. 4. Create a Field/Page Permission Group - Go to the **Field/Page Permission Groups** tab. - Create the group (e.g., View/Edit All Fields) - Assign the appropriate Field/ Page permissions as required (refer to thrbelow table). Select the Save to apply your configurations. 5. Go to the Users tab and Create a new User. In the permissions section, assign the user to the following groups: - System: Select **Min Permission System Group** - Cardholder: Select **Min Permission Cardholder Group** - Field/ Page: Select **View/Edit All Fields** 6. If the segment is enabled, go to the Segment Access tab and assign the necessary access permissions in the configuration. Ensure these are configured the same as [Segment Settings](). 7. Select the Save to finalize the user creation. Please refer to the table below to add permissions to the permission groups. | Connector Operations | System Permission Groups | Cardholder Permission Groups | Field/Page Permission Groups | | --- | --- | --- | --- | | All Operations | Access Control Hardware:
\- Timezones (view/access)
\- Readers (view/access)
Access Control:
\- Access levels (view/access)
\- Segments (view/access)
Software Options (view/access):
\- List Builder (view/access) | Cardholders:
\- Cardholder (view/access+add+modify+delete)
\- Search for cardholders (view/access)
\- Segments (view/access)
Badges:
\- Badge (view/access+add+modify+delete)
\- Access Level Assignments (view/access)
\- Modify access level assignments(view/access)
\- Badge Types and layouts (view/access) | Select **View All** and **Edit All Fields** checkboxes. | | Test Connection | Access Control Hardware:
\- Timezones (view/access)
\- Readers (view/access)
Access Control:
\- Access levels (view/access) | Cardholders:
\- Cardholder (view/access+add+modify+delete)
\- Search for cardholders (view/access)
Badges:
\- Badge (view/access+add+modify+delete)
\- Access Level Assignments (view/access) | Create the Group and select **View/ Edit All Fields** checkbox. | | Account Aggregation | Access Control Hardware:
\- Timezones (view/access)
\- Readers (view/access)
Access Control:
\- Access levels (view/access)
\- Segments (view/access) | Cardholders:
\- Cardholder (view/access+add+modify+delete)
\- Search for cardholders (view/access)
\- Segments (view/access)
Badges:
\- Badge (view/access+add+modify+delete)
\- Access Level Assignments (view/access) | Create the Group and select **View/ Edit All Fields** checkbox. | | Group Aggregation | Access Control Hardware:
\- Timezones (view/access)
\- Readers (view/access)
Access Control:
\- Access levels (view/access)
\- Segments (view/access) | Badges:
\- Badge Types and layouts (view/access) | Create the Group and select **View/ Edit All Fields** checkbox. | | Provisioning | Access Control Hardware:
\- Timezones (view/access)
\- Readers (view/access)
Access Control:
\- Access levels (view/access)
\- Segments (view/access)
Software Options (view/access):
\- List Builder (view/access) | Cardholders:
\- Cardholder (view/access+add+modify)
\- Search for cardholders (view/access)
\- Segments (view/access)
Badges:
\- Badge (view/access+add+modify+delete)
\- Access Level Assignments (view/access)
\- Modify access level assignments(view/access)
\- Badge Types and layouts (view/access) | Create the Group and select **View/ Edit All Fields** checkbox. | # Provisioning The OnGuard connector supports provisioning, allowing you to create and manage accounts and entitlements in OnGuard directly from SailPoint. **Prerequisite:** Your system is configured for provisioning. When SailPoint provisions new accounts to the source, it uses the attributes on the **Create Account** page as instructions or a template for what to include in the account. This page is also referred to as the *provisioning policy*. When new access is granted on a source where a user does not already have an account, SailPoint automatically includes account creation in the provisioning. This applies whether provisioning is started from an access request or from an automated role or lifecycle state assignment. For direct-connect sources, SailPoint automatically creates the account from this configuration. If the source is not configured as a direct-connect source, SailPoint creates and assigns a provisioning task to the source owner and includes the values for the source owner to use in manually creating the account. > [!IMPORTANT] > > This section describes the default **Create Account** configuration. SailPoint recommends that you work with Services to define a provisioning configuration specific to your company's needs. Be sure to verify large changes to the provisioning policy before implementation. Failure to do so might cause provisioning to fail. ### Creating Accounts When Segmentation Is Enabled If segmentation is enabled, account creation works as follows: 1. If **Access to All Segments** is selected in **Segment Settings**: - You can specify both **Primary Segment** and **Additional Segments** when creating a cardholder. - If **Primary Segment** is not provided, the cardholder will be created in the default segment, ``. 2. If **Access to a Specific Segment (Segment Unit)** is selected in **Segment Settings**: - The cardholder will always be created in the configured segment. - Creating cardholders in any other segment is not supported. - Assigning **Additional Segments** is not allowed in this configuration. 3. If **Access to a Specific Segment (Segment Group)** is selected in **Segment Settings**: - The Primary and Additional Segments provided during cardholder creation must meet one of the following conditions: - They match the configured segment group. - They are member segments within that group. For example, if the configured group is United States, allowed values include: 1. United States (group) 2. Austin, New York (member segments of United States) - Creating a cardholder in a segment outside the configured group is not supported. ## Default Create Account Attributes | Attribute Name | Description | | --- | --- | | First Name | The cardholder's first name | | Last Name\* | The cardholder's last name | | Email Address | The cardholder's email address | | City | The cardholder's city | | State | The cardholder's state | ## Configurable Attributes | Attribute Name | Description | | --- | --- | | Middle Name | The cardholder's middle name | | Location | The name of the cardholder's location | | Title | The cardholder's title | | Office Phone | The cardholder's office phone number | | Allowed Visitors | Indicates if the cardholder is allowed to have visitors | | Building | The cardholder's building | | Department | The cardholder's department | | Division | The cardholder's division | | Extension | The cardholder's phone extension | | Floor | The floor that the cardholder is assigned to | | Primary Segment | Primary Segment of a cardholder. This attribute will be visible only when segmentation is enabled . | | Additional Segments | Additional Segments of a cardholder. This attribute will be visible only when segmentation is enabled. | > [!NOTE] > > Parameters marked with an asterisk (\*) are mandatory. ### Adding Custom Attributes for Account Creation You can add customer-specific custom attributes to the Create Account provisioning policy. Add each attribute using its OnGuard internal field name, for example, `CUSTOM_ATTR`. Add each custom attribute to both the account schema and the provisioning policy, using the same internal field name. If you add the attribute only to the provisioning policy, the connector does not send it. ## Update Account Attributes | Attribute Name | Description | Out of the box / Configurable | | --- | --- | --- | | First Name | The cardholder's first name | Configurable | | Last Name | The cardholder's last name | Configurable | | Middle Name | The cardholder's middle name | Configurable | | Email Address | The cardholder's email address | Configurable | | City | The cardholder's city | Configurable | | State | The cardholder's state | Configurable | | Location | The name of the cardholder's location | Configurable | | Title | The cardholder's title | Configurable | | Office Phone | The cardholder's office phone number | Configurable | | Allowed Visitors | Indicates if the cardholder is allowed to have visitors | Configurable | | Building | The cardholder's building | Configurable | | Department | The cardholder's department | Configurable | | Division | The cardholder's division | Configurable | | Extension | The cardholder's phone extension | Configurable | | Floor | The floor that the cardholder is assigned to | Configurable | | Primary Segment | Primary Segment of a cardholder. This attribute will be visible only when segmentation is enabled . | Configurable | | Additional Segments | Additional Segments of a cardholder. This attribute will be visible only when segmentation is enabled. | Configurable | ### Adding Custom Attributes for Account Updates You can add customer-specific custom attributes to the Update Account provisioning policy. Add each attribute using its OnGuard internal field name, for example, `CUSTOM_ATTR`. Add each custom attribute to both the account schema and the provisioning policy, using the same internal field name. If you add the attribute only to the provisioning policy, the connector does not send it. ### Updating Accounts When Segmentation Is Enabled 1. If **Access to All Segments** is selected in **Segment Settings**: - You can update both **Primary Segment** and **Additional Segments** for the cardholder. 2. If **Access to a Specific Segment (Segment Unit)** is selected in **Segment Settings**: - Updating **Primary Segment** or **Additional Segments** is not supported. - The cardholder remains associated with the configured segment only. 3. If **Access to a Specific Segment (Segment Group)** is selected in **Segment Settings**: - You may update the Primary and Additional Segments only if: - They match the configured segment group. - They are member segments within that group. For example, if the configured group is United States, allowed values include: 1. United States, Austin, or New York. - Updating to segments outside the configured group is not supported. ## Enabling and Disabling Accounts ### Enabling Accounts This operation enables the cardholder's most recently modified badge. > [!NOTE] > > The default deactivation date of the badge will be set to 5 years from activation. ### Disabling Accounts This operation deactivates all active badges assigned to a cardholder. The deactivation date is set to the current date, and the status is applied based on the Default Deactivation Status configured during setup. For more information, refer to [Deactivation Settings](). ## Adding and Removing Entitlements ### Adding Entitlements to Cardholders The connector supports assigning the following entitlements to the cardholder: - **Badge Type** This operation creates a new, unique badge of the respective badge type for the cardholder. - **Access Level** The access level operation works in two ways: 1. Assign Access Level - If the access level has not been previously assigned, this operation assigns it across all active badges. - The activation date is set to the current date, and the deactivation date is left null. 2. Activate Access Level - If the access level has already been assigned but is currently deactivated, this operation reactivates it for the badge. - The activation date is set to the current date, and the deactivation date is left null. > [!NOTE] > > When both the Badge Type and Access Levels are selected together, the specified access levels will be assigned to the newly created badge accordingly. ### Removing Entitlements from Cardholders The connector supports removing the following entitlements from the cardholder: - **Badge Type** This operation will remove all the badges of the respective badge type of the cardholder. - **Access Level** The access level operation has two options: 1. Remove Access Level - This operation permanently removes the specified access level assigned to the cardholder's badges. 2. Deactivate Access Level - This operation deactivates the access level assignment to the cardholder's badges instead of removing it. If not selected, the assignment will be permanently removed. The deactivation date is set to the current date. Refer to [Provisioning Settings]() for more information about deactivating access levels. If a badge type and an access level are selected together, the connector will prioritize the Badge Type, as it is considered a super-entity. As a result, all badges of the selected type will be permanently removed. Consequently, the associated access levels will also be removed automatically, since the badge itself no longer exists. > [!NOTE] > > If the use case requires deactivating or removing access-level assignments from badges, SailPoint recommends making a separate request by selecting only the access levels without selecting a badge type. This ensures that access levels are deactivated or removed from all active badges of the cardholder without deleting the badges themselves. # Schema Reference The application schema is used to configure the objects returned from a connector. > [!NOTE] > > - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas]() for more information. > - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified. The OnGuard connector uses the following default correlation and object configurations. This section describes the different schema attributes. > [!NOTE] > > - The Account Schema tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as Entitlement or Multi-Valued. > - The identity attribute is predefined in the schema. Do not change the native identity (primary) attribute during aggregation. If the value is altered, it may result in errors in your database. Refer to Account ID for the default values. ## Default Account Schema Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location. The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas]() for more information. ### Default Account ID SailPoint requires that certain attributes remain in your configuration. These attributes are referred to as *account IDs*. > [!CAUTION] > > Changing the attribute marked as the account ID after aggregating accounts can result in duplicate accounts being created. To avoid this, either reset the accounts on this source before editing the account ID attribute or edit the account ID attribute before aggregating accounts. > > To resolve issues caused by changing account IDs, reconfigure them to their default values. The following table lists the default account IDs for this connector: | Account ID | Schema Object Type | | --- | --- | | ID | Cardholder | | ID | Badge Type | | ID | Access Level | ### Default Account Attributes The OnGuard connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified. | Attribute Name | Description | | --- | --- | | ID | The cardholder's unique ID. This is an Account ID which must not be changed. | | First Name | The cardholder's first name. | | Last Name | The cardholder's last name. | | Middle Name | The cardholder's middle name. | | Primary Segment | Primary Segment of a cardholder. This attribute will be visible only when segmentation is enabled . | | Additional Segments | Additional Segments of a cardholder. This attribute will be visible only when segmentation is enabled. | | Email Address | The cardholder's email address. | | City | The cardholder's city. | | State | The cardholder's state. | | Location | The name of the cardholder's location. | | Title | The cardholder's title. | | Office Phone | The cardholder's office phone number. | | Allowed Visitors | Indicates if the cardholder is allowed to have visitors. | | Building | The cardholder's building. | | Department | The cardholder's department. | | Division | The cardholder's division. | | Extension | The cardholder's phone extension. | | Floor | The floor that the cardholder is assigned to. | | Last Changed | Timestamp for the most recent change to the record. | | Badge Types | List of active badge types assigned to cardholders. | | Badges | List of active badges assigned to the cardholder. | | Inactive Badges | List of inactive badges assigned to the cardholder. | | Access Levels | List of active access levels assigned to the cardholder. | | Inactive Access Levels | List of inactive access levels assigned to cardholder. | ### Custom Attributes Configure the connector to include custom attributes from the source in account aggregation processes. To include additional custom attributes in the account aggregation processes, add the attribute name to the account schema exactly as it is configured in the source schema. Along with the attributes above, you can aggregate customer-specific custom cardholder attributes. Add each custom attribute to the account schema using its OnGuard internal field name, for example, `CUSTOM_ATTR`, and not the label shown on the OnGuard form. After you add a custom attribute to the schema, the connector returns it during full aggregation, delta aggregation, and single account read. The connector ignores custom attributes that you do not add to the schema, and aggregation does not fail. For date custom attributes, add the attribute as type `string`. The connector detects date fields from OnGuard and returns the same value for full aggregation, delta aggregation, and single account read. Dates are returned in ISO-8601 format in the connector time zone, for example, `1989-01-01T05:30:00+05:30`. ## Default Entitlement Attributes Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements]() for more information. > [!CAUTION] > > Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations. ### Default Group Attributes The OnGuard connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups. #### Object Type: Badge Type | Attribute Name | Description | | --- | --- | | ID | The Badge Type's unique internal database ID. This is an Account ID which must not be changed. | | Badge ID Allocation Type | Indicates the method by which the Badge ID field on the Badge Form is automatically filled in when adding a new badge. | | Badge ID Allow Edit | Indicates if badges which use this Badge Type have editable IDs. | | Badge Type Class | The Badge Type's class. | | Default Access Group | The name of the group to which the access levels belong. | | Default Deactivation Date | The default deactivation date for any badges which use this Badge Type. | | Default Deactivation Date Type | Indicates the type or class, assigned to this Badge Type. | | First Issue Code | The Badge Type's optional first issue code. | | Is Disposable | Used by Visitor-type badges, indicates if the badge can be disposed of. | | Name | The Badge Type's name. | | Use Latest Badge Deactivation Date | Indicates if the latest deactivation date can be used. | | Use Mobile Credential | Indicates if mobile credentialing is enabled. | | Segment | Segment to which the badge type belongs. | #### Object Type: Access Level | Attribute Name | Description | | --- | --- | | ID | The access level's unique internal database ID. This is an Account ID which must not be changed. | | Name | The access level's display name. | | Available For Request | Indicates if the access level can be requested. | | Download To Intelligent Readers | Indicates if the access level can be downloaded to intelligent readers. | | First Card Unlock | First card unlocks the reader. | | Has Command Authority | Indicates if the access level has Command authority. | | Segment | Segment to which the badge type belongs. | # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Unable to find valid certification path to requested target The following error message appears when multiple versions of Java are installed on the same computer, and the valid certification path is not found to the requested target. ```text Error - main, handling exception: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target ``` **Resolution** - Ensure correct OnGuard certificates are added at /home/sailpoint/certificates or Ensure correct and valid OnGuard certificates are present on VA required to connect the OnGuard Server. ## javax.net.ssl.SSLPeerUnverifiedException: Hostname \ Not Verified **Resolution** - Make sure the Fully Qualified Domain Name (FQDN) of the machine on which the OnGuard Solution is installed is defined. ## Fatal Errors from OnGuard Requiring Human Intervention If the OnGuard connector encounters any of the following fatal errors, manual investigation and corrective action may be needed: ```text "The username/password combination you have entered is incorrect"; "The OpenAccess license has expired"; "The license for this application is currently unavailable"; "The event subscription does not exist"; ``` **Resolution** - Review the error details and take the necessary manual steps to correct the configuration, license status, or system setup. ## Incorrect Data in Badge and Access Level Attributes Inaccurate data displayed in the following attributes: ```text Active Badges Inactive Badges Active Access Levels Inactive Access Levels ``` **Resolution** - This issue caused by incorrect timezone settings. Ensure the same and correct timezone is selected in all of the following: - Connector Configuration - OnGuard Server - System where the OnGuard Event Subscriber Service is running ## Certificate Path Building Failed Error The following error is displayed: ```text PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target ``` **Resolution** - This error indicates that the OnGuard root certificate is either missing or not correctly imported into the Java cacerts truststore. Re-import the root certificate and verify the installation. Also, ensure that you import the certificate into the same Java environment (cacerts) that is being used to run IdentityIQ. - To import on Windows: ```shell keytool -importcert ^ -alias onguard ^ -file "C:\Users\user\Documents\OnGuard\ls_server_cert.pem" ^ -keystore "C:\Program Files\Java\jdk-17\lib\security\cacerts" ^ -storepass changeit ``` Verify installation: ```shell keytool -list ^ -keystore "C:\Program Files\Java\jdk-17\lib\security\cacerts" ^ -storepass changeit | findstr onguard ``` If successful, you will see the alias **onguard** listed. - To import on macOS / Linux (RHEL) ```shell sudo keytool -importcert \ -alias onguard \ -file \ -keystore /lib/security/cacerts \ -storepass changeit ``` Verify installation: ```shell keytool -list \ -keystore /lib/security/cacerts \ -storepass changeit | grep onguard ``` If successful, you will see the alias **onguard** listed. ## java.net.UnknownHostException:\: Name or service not known **Resolution** - The hostname is not properly mapped or is missing in the VA configuration. 1. Verify that the hostname is correctly mapped on the VA (Virtual Appliance). 2. If the issue persists, perform the following steps: - Add the host entry as described in the [Configuring a Hosts.yaml File]() documentation. - Restart the CCG service. - Reboot the VA. ## Custom attribute is missing or shows an unexpected value **Resolution** - Set the schema attribute name to the OnGuard internal field name, for example, `CUSTOM_ATTR`, and not the label shown on the OnGuard form. If a custom attribute shows an unexpected value, confirm that the account schema attribute uses the exact OnGuard internal field name and the correct type: `int` or `long` for whole numbers, and `string` for text, dates, and decimals. A date custom attribute must be `string`. After aggregation, a date appears in ISO-8601 format in the connector time zone, for example, `1989-01-01T05:30:00+05:30`, and not as the date-only value shown in OnGuard. ## Updating a custom attribute fails with system.invalid\_field **Resolution** - Verify the format of the field. If it is a date field, check the format OnGuard expects and provide the value in that format only, often `yyyy-MM-dd`, for example, `2008-08-09`. Do not send the aggregated ISO-8601 value unless OnGuard expects that format. # Timeout Errors Timeout errors might occur when SailPoint is waiting for a response from the Virtual Appliance (VA). These errors are applicable to all connectors and tend to occur during the setup of sources or when sources are down. This document is designed to give specific information that can be used to resolve these errors. Each timeout attribute has a default time value that is listed in seconds or minutes. Increasing the time value may resolve the error as it will allow for longer communication time between the two systems, thus avoiding the timeout error. > [!IMPORTANT] > > Add the necessary attributes or values before performing the "replace" operation, as missing attributes will cause the operation to fail. To increase the communication time, increase the value of the appropriate timeout attribute. Then submit the change to the VA using the SailPoint REST API. > [!NOTE] > > For more information on SailPoint's REST APIs, refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() in the SailPoint Developer Community. ### aggregateTimeout **Description:** This parameter is set for the aggregation timeout, measured in seconds. **Resolution:** Increase the `aggregateTimeout` value gradually to optimize aggregation. Start with 180, then increase to 600, 900, and finally 1800. The maximum value is 3600 seconds. For example: If your current time value is 180 seconds, update the `aggregateTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/aggregateTimeout", "value": 600 } ] ``` ### healthCheckTimeout **Description:** This parameter is set for the test connection and health check timeout. **Resolution:** The default value is 30 seconds. If the timeout error continues, increase the value in 15 second increments and try again. For example: If your current time value is 30 seconds, update the `healthCheckTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/healthCheckTimeout", "value": 45 } ] ``` ### provisioningTimeout **Description:** This parameter is set for provisioning timeout. **Resolution:** Increase the `provisioningTimeout` value gradually to optimize provisioning. Start with 180, then increase to 360, and finally 600. The maximum value is 600 seconds. For example: If your current time value is 180 seconds, update the `provisioningTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/provisioningTimeout", "value": 360 } ] ``` ### timeout **Description:** This parameter is set for pass-through authentication timeout. **Resolution:** The default value is 15 seconds. If the timeout error continues, increase this value in 15 second increments and try again. For example: If your current time value is 15 seconds, update the `timeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeout", "value": 30 } ] ``` ### apiTimeout **Description:** This parameter is set for API time tracking; customers can check it using an external tool. **Resolution:** The default value is 60 seconds. If the error continues, increase the value by 15 second increments and try again. For example: If your current time value is 60 seconds, update the `apiTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/apiTimeout", "value": "75" } ] ``` ### timeoutInSeconds **Description:** This parameter helps prevent the VA from waiting indefinitely for an API response, ensuring efficient handling of API requests. For example: If your current time value is 30 seconds, update the `timeoutInSeconds` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeoutInSeconds", "value": "15" } ] ```