Configuration of the Lenel Onguard API to disable card holder accounts to provision users and entitlements using the IdentityNow Web Service Connector.
Lenel Onguard is a badging system that allows individuals to gain access to certain locations. Typically, every employee/identity gets a card holder account, and this card holder account stays with the individual until they are terminated. Other factors:
- The card holder account alone does not allow individuals to access certain areas.
- The card holder account gets assigned a “badge” and that “badge” will allow the individual to access certain areas.
- Individuals should not have more than one card holder account and although it is technically feasible for a card holder account to have multiple badges, it is not considered a good practice in Lenel OnGuard.
The Lenel OnGuard Web Services Configuration guide outlines how to configure the IdentityNow Web Services Connector to communicate with the Lenel Onguard REST API to create card holder accounts, read card holder account information including badge information, and then remove individual badges from the card holder account. However, it was determined that the Lenel Onguard API cannot disable card holder accounts.
Below are the configuration options configured for the Lenel Onguard API using IdentityNow & Identity Security Cloud.
Base Configuration
This section is not covered as it is self-explanatory and determined by your IdentityNow tenant.
Connection Settings
The authentication for Lenel Onguard API requires a session token to be generated every time you call the Web Service. Due to the session token expiration, custom authentication must be configured. Below are the settings needed to be in place for Custom Authentication on the Connection Settings page.
- Authentication Type – No/Custom Authentication
- Base URL – This is the URL of the Rest API. (i.e. https://APIDOMAINNAME:8080)
- Connection Timeout – 300
- Account Enable Status Attribute – 24 (represents an enabled badge)
- Account Lock Status Attribute – 26 (represents a disabled badge)
Encrypt Service Account Password
It is required to encrypt the password for the Lenel OnGuard Service Account. This can be done by calling the following APIs in IdentityNow. *Please note: SailPoint is in the process of depreciating some of their older API calls. The API calls below might need to be updated to the newer API calls. Any Identity Now APIs are relevant for Identity Security Cloud.*
1st API CALL
POST – https://{tenentURL}/cc/api/source/update/{SourceID}
The SourceID list about in the Source ID obtained through the UI.
BODY of the API call using FORM fields
KEY – connector_password_CA
Value – Service Account Password (this is the password in clear text)
2nd API CALL
POST – https://{tenentURL}/cc/api/source/update/{SourceID}
The SourceID list about in the Source ID obtained through the UI.
BODY of the API call using FORM fields
KEY – connector_encrypted
Value – accesstoken,refresh_token,oauth_token_info,client_secret,private_key,private_key_password,clientCertificate,clientKeySpec,resourceOwnerPassword,custom_auth_token_info,password_CA
Account Schema
Below is the schema used for the Web Service connector. The SSNO attribute contained the individual’s employee ID and was made the Account ID and Name. The ALLOWEDVISITORS attribute was a Boolean value and was used as an Entitlement in an Access Profile to allow IDN to create card holder accounts.
| Attribute Name | Type | Notes |
| SSNO | String – Account ID and Name | Typically contains the employeeID |
| ZIP | String | |
| STATUS | String | Status of the Badge assigned to card holder account. Either 24 or 26. |
| ADDR1 | String | |
| ALLOWEDVISITORS | Entitlement – Group, Multi-valued | |
| PERSON_ID | String | |
| BADGE_ID | String | Needed to disable a badge |
| CITY | String | |
| FIRSTNAME | String | |
| LASTNAME | String | |
| STATE | String | |
| DEPT | String | |
| TITLE | String | |
| String | ||
| DIVISION | String | |
| BADGEKEY | String |
HTTP Operations
The section below will detail all the HTTP Operations configured for the Web Service Connector. To configure a new HTTP Operation, click the “Add Operation” button located at the bottom of the screen. If the field is not present below in the operation listed, then the field was not populated during configuration and is not required.
HTTP Operation Name: Custom Authentication
General Information
- Operation Name: Custom Authentication
- Operation Type: Custom Authentication
- Custom Authentication URL:
https://REST-API-DOMAIN-NAME/api/access/onguard/openaccess/authentication?version=1.0
- HTTP Method: Post
Headers
| Key | Value |
| Application-Id | Unique to customer environment |
| Content-Type | application/json |
Body
- Type: Raw
- Body:
{
user_name: “Unique to customer environment”,
password: “$application.password_CA$”,
directory_id:”: “id-1”
}
Response Mapping
| Schema Attribute | Attribute Path |
| session_token | session_token |
HTTP Operation Name: Account Aggregation
General Information
- Operation Name: Account Aggregation
- Operation Type: Account Aggregation
- Context URL: /api/access/onguard/openaccess/instances?type_name=Lnl_Cardholder&version=1.0&page_size=100&queue=false&do_not_reset_inactivity_timer=false
- HTTP Method: GET
Headers
| Key | Value |
| Application-Id | Unique to customer environment |
| Session-Token | $application.session_token$ |
| Content-Type | application/json |
Body
- Type: Raw
- Body:
{
“user_name”: “Unique To Customer Environment”,
“password”: “$application.password$”,
“directory_id”: “id-1”
}
Response Information
- Root Path: $..property_value_map
- Success Codes: 2**
Response Mapping
| Schema Attribute | Attribute Path |
| ZIP | ZIP |
| SSNO | SSNO |
| STATE | STATE |
| FIRSTNAME | FIRSTNAME |
| LASTNAME | LASTNAME |
| DIVISION | DIVISION |
| ADDR1 | ADDR1 |
| CITY | CITY |
| PERSON_ID | PERSON_ID |
| DEPT | DEPT |
| TITLE | TITLE |
| ALLOWEDVISITORS | ALLOWEDVISITORS |
HTTP Operation Name: Create Account
General Information
- Operation Name: Create Account
- Operation Type: Create Account
- Context URL: /api/access/onguard/openaccess/instances?type_name=Lnl_Cardholder&version=1.0&page_size=100&queue=false&do_not_reset_inactivity_timer=false
- HTTP Method: POST
Headers
| Key | Value |
| Application-Id | Unique to customer environment |
| Session-Token | $application.session_token$ |
| Content-Type | application/json |
Body
- Type: Raw
- Body:
{
“property_value_map”:
{
“CITY”: “$plan.CITY$”,
“DEPT”: “10010”,
“EMAIL”: “$plan.EMAIL$”,
“FIRSTNAME”: “$plan.FIRSTNAME$”,
“LASTNAME”: “$plan.LASTNAME$”,
“PRIMARYSEGMENTID”: “1”,
“SSNO”: “$plan.nativeIdentity$”,
“STATE”: “$plan.STATE$”,
“ZIP”: “$plan.ZIP$”
}
}
Response Information
- Root Path: $property_value_map
- Success Codes: 2**
Response Mapping
| Schema Attribute | Attribute Path |
| ZIP | ZIP |
| SSNO | SSNO |
| STATE | STATE |
| FIRSTNAME | FIRSTNAME |
| LASTNAME | LASTNAME |
| DIVISION | DIVISION |
| ADDR1 | ADDR1 |
| CITY | CITY |
| PERSON_ID | PERSON_ID |
| DEPT | DEPT |
| TITLE | TITLE |
| ALLOWEDVISITORS | ALLOWEDVISITORS |
HTTP Operation Name: Disable Account
General Information
- Operation Name: Disable Account
- Operation Type: Disable Account
- Context URL: /api/access/onguard/openaccess/instances?type_name=Lnl_Badge&filter=ID=$BadgeID$&version=1.6&version=1.6
- HTTP Method: GET
Headers
| Key | Value |
| Application-Id | Unique to customer environment |
| Session-Token | $application.session_token$ |
| Content-Type | application/json |
Body
- Type: Raw
- Body:
{
“user_name”: “Unique To Customer Environment”,
“password”: “$application.password$”,
“directory_id”: “id-1”
}
Response Information
- Root Path: $..property_value_map
- Success Codes: 2**
Response Mapping
| Schema Attribute | Attribute Path |
| BADGE_ID | ID |
| STATUS | STATUS |
Author: Jay Neenan, IDMWORKS, Senior IAM Architect