BambooHR is a comprehensive human resources information system (HRIS) that provides essential employee data and organizational context for access control decisions. By integrating BambooHR with SGNL, you can establish relationships between employees, supervisors, departments, and roles that enable sophisticated policy-based access control throughout your organization.
The BambooHR integration brings critical HR data into the SGNL graph, allowing you to create policies based on employee attributes such as department, job title, employment status, supervisor relationships, and custom fields defined in your BambooHR instance. This integration is particularly valuable for organizations that need to make access decisions based on organizational hierarchy, employment status, or HR-specific attributes.
To successfully configure the BambooHR integration, you need the following permissions and access:
BambooHR uses API key authentication for system integrations. Follow these steps to create the necessary credentials:
Your BambooHR company domain is the subdomain used to access your account. For example, if you access BambooHR at https://acmecorp.bamboohr.com
, then your company domain is “acmecorp”. You will need this value when configuring the SGNL integration.
Before configuring SGNL, review your BambooHR employee data structure to understand which fields are available and relevant for your access policies. BambooHR provides both standard fields (like employee ID, email, department) and custom fields that your organization may have defined. The BambooHR Field Names documentation provides a comprehensive list of available standard fields.
BambooHR uses HTTP Basic Authentication with your API key. Configure the authentication settings as follows:
The authentication configuration follows BambooHR’s standard approach where the API key serves as the username and the password field can contain any value since it is not validated.
Complete the following required configuration fields:
BambooHR API Address: The address field should be set to “api.bamboohr.com/api/gateway.php” (this is pre-configured in the template)
Company Domain: Replace the {{Input Required}}
placeholder in the adapter configuration with your actual BambooHR company subdomain. This is the subdomain portion of your BambooHR URL.
The BambooHR integration includes several optional configuration parameters that can be customized based on your needs:
Employee Filtering: The onlyCurrent
parameter determines whether to synchronize all employees or only current employees. Set this to true
if you only want active employees in your SGNL policies, or false
to include all employee records including terminated employees.
Date Format Configuration: BambooHR allows different date input formats. The attributeMappings.date
parameter should match your BambooHR date format setting. Check your BambooHR Admin Console under Settings → Account → General Settings → Date Input Format to determine the correct format.
Boolean Field Mapping: If your BambooHR instance uses custom boolean fields with non-standard values, you can configure the attributeMappings.bool
section to specify how these values should be interpreted. The default configuration handles standard true/false representations.
The BambooHR template defines an Employee entity with several key attributes that provide comprehensive employee information:
Core Identity Attributes: The id
field serves as the unique identifier for each employee, while bestEmail
provides the primary email address for the employee. These attributes are essential for establishing identity relationships with other systems.
Personal Information: Attributes like fullName
, dateOfBirth
, and employeeNumber
provide basic employee information that can be used in access policies.
Organizational Relationships: The supervisorEId
and supervisorEmail
attributes establish supervisor relationships, enabling policies based on organizational hierarchy.
Custom Field Support: The template includes examples of custom fields (like checkboxField1
) that demonstrate how to integrate custom BambooHR fields into your SGNL policies.
Audit and Tracking: The lastChanged
attribute provides timestamp information for tracking when employee records were last modified.
The BambooHR template establishes a critical “Manager” relationship that connects employees to their supervisors:
Manager Relationship: This relationship uses the employee’s id
field and relates it to another employee’s supervisorEId
field, creating the organizational hierarchy within SGNL. This relationship enables policies that consider reporting structures, such as allowing managers to access resources for their direct reports.
You can extend these relationships by connecting BambooHR data to other systems in your SGNL configuration. For example, if employee numbers in BambooHR match user identifiers in your identity provider, you can create relationships that bridge HR data with authentication systems.
After configuring the BambooHR integration, follow these steps to verify that the connection is working correctly:
Once synchronization is complete, use DataLens to explore the imported BambooHR data:
API Key Not Working: If you receive authentication errors, verify that your API key is correct and has not expired. BambooHR API keys do not typically expire, but they can be deactivated. Try generating a new API key if authentication continues to fail.
Permission Errors: Ensure that the API key has sufficient permissions to read employee data. Some BambooHR configurations restrict API access to specific data fields or employee groups.
Domain Configuration Errors: Double-check that your company domain is correctly specified without the “https://” prefix or “.bamboohr.com” suffix. Only the subdomain portion should be included.
Network Connectivity: Verify that your SGNL instance can reach “api.bamboohr.com” and that no firewall rules are blocking the connection.
Missing Employee Records: If some employees are not appearing in SGNL, check the onlyCurrent
configuration parameter. If set to true
, only active employees will be synchronized.
Incorrect Date Values: If date fields are not parsing correctly, verify that the attributeMappings.date
parameter matches your BambooHR date format configuration.
Custom Field Problems: Custom fields in BambooHR must be prefixed with “custom” in the external ID configuration. Verify that custom field names in the template match exactly with your BambooHR custom field definitions.
Boolean Field Conversion: If boolean custom fields are not converting properly, review the attributeMappings.bool
configuration to ensure it accounts for the specific string values used in your BambooHR instance.
Slow Synchronization: Large employee datasets may take time to synchronize initially. The template is configured with reasonable default intervals, but you can adjust the syncFrequency
and apiCallFrequency
parameters if needed.
API Rate Limiting: BambooHR may have API rate limits that could affect synchronization speed. The default configuration respects these limits, but contact BambooHR support if you experience persistent rate limiting issues.
Once your BambooHR integration is successfully configured and synchronized, you can leverage the employee data in your SGNL policies:
Organizational Hierarchy Policies: Use the manager relationships to create policies that grant supervisors access to resources related to their direct reports.
Department-Based Access: Leverage department and job title information to create role-based access policies aligned with your organizational structure.
Employment Status Policies: Use employment status and start date information to automatically manage access for new hires and departing employees.
Custom Field Policies: Incorporate any custom HR fields into your access decisions, such as security clearance levels, project assignments, or office locations.
For comprehensive guidance on creating policies with HR data, refer to the SGNL Policy Management documentation. For understanding how employee entities relate to other systems in your environment, review the Entities and Relationships guide.