Creating and Configuring a HashiCorp Boundary System of Record

HashiCorp Boundary provides secure, identity-based access to dynamic infrastructure resources, bringing critical infrastructure access context into SGNL for sophisticated access control decisions. By integrating Boundary with SGNL, you gain comprehensive visibility into who is accessing which infrastructure resources, their session patterns, credential usage, and the hierarchical scope structures that govern resource access within your organization.

The Boundary integration captures the complete infrastructure access ecosystem including users, groups, roles, targets (the resources being accessed), hosts, active sessions, credentials, and the scoped organizational structure that Boundary uses to manage access permissions. This integration is particularly valuable for organizations implementing Zero Trust network access where infrastructure access patterns must inform broader security decisions across applications and services.

Unlike traditional VPN or network access solutions, Boundary provides identity-aware, session-based access with comprehensive auditing capabilities. This creates rich context about infrastructure usage patterns, resource access relationships, and user behavior that can significantly enhance access control decisions in other systems throughout your environment.

Prerequisites

  • A HashiCorp Boundary deployment (either self-managed or HCP Boundary)
  • Administrative access to Boundary with permissions to create and manage authentication methods
  • Understanding of your Boundary organizational structure including scopes, targets, and user groups
  • Knowledge of which Boundary data is most relevant for your access control policies

Permissions Required

To successfully configure the HashiCorp Boundary integration, you need administrative access within Boundary to read user, group, role, target, session, and credential information across the scopes you want to include in SGNL.

Boundary Administrative Permissions: You need administrative privileges within Boundary to create authentication methods, manage users and groups, and read session and audit information. The integration requires access to read entities across multiple Boundary services including users, groups, roles, targets, hosts, sessions, and credentials.

Authentication Method Management: The integration requires the ability to create and configure authentication methods within Boundary. This includes setting up username/password authentication or integrating with external identity providers that Boundary can use for API access.

Cross-Scope Access: Boundary organizes resources within hierarchical scopes (organizations, projects). The integration needs read access across all scopes that contain resources relevant to your access control policies. This may require configuring the integration user with appropriate permissions across multiple scope levels.

Session and Audit Data Access: To provide comprehensive access context, the integration needs the ability to read session information, connection logs, and credential usage patterns across your Boundary deployment.

Configuring HashiCorp Boundary

Setting Up Authentication

HashiCorp Boundary integration uses HTTP Basic Authentication with username and password credentials configured within your Boundary deployment.

Creating a Boundary User for Integration

  1. Access Boundary Console: Log into your Boundary console (either self-managed or HCP) with administrative privileges
  2. Navigate to Authentication: Go to the appropriate scope (typically the global or organization scope) and access the Authentication section
  3. Identify Auth Method: Locate the authentication method you’ll use for the SGNL integration (typically a password-based auth method)
  4. Create Integration User: Create a new user account specifically for SGNL integration with a descriptive name like “sgnl-integration-user”
  5. Set Strong Credentials: Configure a strong username and password combination for the integration user
  6. Document Auth Method ID: Note the authentication method ID (format: ampw_*) as you’ll need this for the adapter configuration

Configuring User Permissions

  1. Create Integration Role: Create a role specifically for the SGNL integration with read permissions across the entities you want to synchronize
  2. Assign Scope Permissions: Grant the role appropriate permissions across all scopes that contain relevant resources (users, groups, targets, hosts, sessions)
  3. Associate User with Role: Add the integration user to the role to grant necessary permissions
  4. Test Access: Verify that the integration user can authenticate and read the necessary data across your Boundary deployment

Understanding Your Boundary Structure

Before configuring SGNL, review your Boundary organizational structure to understand how scopes, projects, targets, and user groups are organized. Consider which targets represent critical infrastructure resources, how user groups align with organizational structure, and which session patterns might inform access control decisions in other systems.

Boundary’s hierarchical scope structure (Global → Organization → Project) affects how resources are organized and accessed. Understanding this hierarchy is crucial for configuring the integration to capture the most relevant access context for your policies.

Configuring SGNL

Setting Up the HashiCorp Boundary System of Record

  1. Access SGNL Console: Login to the SGNL Console with appropriate administrative privileges
  2. Navigate to Identity Data Fabric: From the left menu, select “Identity Data Fabric”
  3. Add New System of Record: Click “Add System of Record” or “Add” to open the SoR catalog
  4. Select HashiCorp Boundary Template: Locate and click on “HashiCorp Boundary” in the SGNL SoR Catalog to open the configuration screen with pre-populated settings

Authentication Configuration

HashiCorp Boundary uses HTTP Basic Authentication with your Boundary user credentials:

  1. Select Authentication Method: Choose “Basic” as the authentication method
  2. Configure Username: Enter the username of your Boundary integration user
  3. Configure Password: Enter the password for your Boundary integration user

This authentication approach uses the standard Boundary API authentication mechanism where the username and password correspond to a user account configured within a Boundary authentication method.

System Configuration

Complete the required configuration parameters for your HashiCorp Boundary integration:

Boundary Hostname: Replace the {{Input Required: uuid.boundary.hashicorp.cloud}} placeholder with your Boundary deployment hostname. For HCP Boundary, this typically follows the format {uuid}.boundary.hashicorp.cloud. For self-managed Boundary, use your Boundary controller’s hostname and port.

Adapter Configuration Details

The HashiCorp Boundary integration includes a comprehensive adapter configuration that must be properly set up for your specific Boundary deployment. The adapter configuration is provided as a base64-encoded JSON object with the following parameters:

Required Configuration Parameters

Request Timeout: Set the requestTimeoutSeconds parameter to control how long SGNL waits for responses from Boundary APIs. The default of 10 seconds is typically sufficient for most deployments.

Authentication Method ID: The authMethodId parameter is required and must contain the ID of the Boundary authentication method that contains your integration user. This ID typically follows the format ampw_* for password authentication methods.

Optional Entity Configuration

The adapter supports optional entityConfig parameters that allow you to filter and scope which data is synchronized:

Host Configuration: You can configure the hosts entity to synchronize from specific scopes:

  • scope_id: Specify the Boundary scope ID (format: o_* for organizations, p_* for projects) to limit host synchronization to that scope
  • filter: Apply additional filtering criteria to the hosts query using Boundary’s powerful filter expression syntax

Additional Entity Scoping: Similar scoping can be applied to other entities like users, groups, roles, and targets by adding corresponding sections to the entityConfig.

Boundary Filter Expression Syntax

HashiCorp Boundary supports sophisticated filter expressions that allow you to precisely control which entities are synchronized based on their attributes and metadata. Understanding this filtering capability is crucial for optimizing your integration and focusing on the most relevant data for your access control policies.

Filter Expression Structure: Boundary filter expressions use JSON Pointer selectors with matching operators to create Boolean logic expressions. JSON Pointer is a standardized syntax for identifying specific elements within a JSON document, using a string of keys and indices to navigate the document’s structure. All filter expressions are evaluated on the Boundary controller and support complex logical combinations.

Matching Operators Available:

// Equality and Inequality Checks
"/name" == "production-database"
"/type" != "dev"

// Emptiness Checks
"/description" is empty
"/tags" is not empty

// Contains Checks and Substring Matching
"prod" in "/name"
"test" not in "/name"
"/name" contains "database"
"/description" not contains "deprecated"

// Regular Expression Matching
"/name" matches "^prod-.*"
"/host_set_ids" not matches ".*-dev-.*"

Selector Format: Selectors use JSON Pointer syntax to reference entity attributes. Each selector must be enclosed in quotes and include a leading slash. For example:

  • "/name" - References the entity’s name attribute
  • "/created_time" - References when the entity was created
  • "/authorized_actions" - References the list of authorized actions
  • "/attributes/environment" - References nested attributes (if available)

Logical Operators: Filter expressions can be combined using logical operators:

// Logical combinations
"/name" contains "prod" and "/type" == "tcp"
"/name" contains "dev" or "/name" contains "test"
not ("/description" is empty)
("/name" contains "database" and "/type" == "tcp") or "/name" contains "cache"

Practical Filtering Examples:

Filter Production Targets Only:

"targets": {
  "scope_id": "p_ProductionProject",
  "filter": "/name contains 'prod' and /type == 'tcp'"
}

Exclude Development and Test Hosts:

"hosts": {
  "scope_id": "o_MainOrg",
  "filter": "/name not contains 'dev' and /name not contains 'test'"
}

Filter Active Sessions Only:

"sessions": {
  "scope_id": "o_MainOrg",
  "filter": "/status == 'active' and /expiration_time != ''"
}

Filter Users by Role or Group:

"users": {
  "scope_id": "o_MainOrg",
  "filter": "/name matches '^admin-.*' or 'admin-group' in /account_ids"
}

Complex Multi-Condition Filters:

"targets": {
  "scope_id": "p_CriticalInfra",
  "filter": "(/name contains 'database' or /name contains 'cache') and /session_max_seconds >= 3600 and not (/description contains 'deprecated')"
}

Performance Considerations: Filter expressions are executed on the Boundary controller, so complex filters with many conditions or regular expressions may impact controller performance. Consider the following best practices:

  • Use simple equality checks when possible instead of regular expressions
  • Apply the most selective filters first in logical AND operations
  • Use scope filtering (scope_id) to reduce the dataset before applying complex filters
  • Test filter performance in non-production environments with realistic data volumes

Filter Expression Validation: Boundary validates filter expressions when they’re applied. Invalid JSON Pointer paths, malformed regular expressions, or syntax errors will cause synchronization failures. Always test filter expressions in your Boundary environment before deploying them in SGNL.

Example Adapter Configuration

Here’s an example of a complete adapter configuration with practical filtering:

{
  "requestTimeoutSeconds": 10,
  "authMethodId": "ampw_UNEy43ZyMf",
  "entityConfig": {
    "hosts": {
      "scope_id": "o_6W7PFp6pzM",
      "filter": "/name not contains 'dev' and /name not contains 'test'"
    },
    "users": {
      "scope_id": "o_6W7PFp6pzM",
      "filter": "/description is not empty"
    },
    "targets": {
      "scope_id": "p_ABCdefGHij",
      "filter": "/name contains 'prod' and /session_max_seconds >= 1800"
    },
    "sessions": {
      "scope_id": "o_6W7PFp6pzM",
      "filter": "/status == 'active' or /status == 'pending'"
    }
  }
}

This configuration would:

  • Use a 10-second request timeout
  • Authenticate using the specified auth method
  • Synchronize hosts from the organization scope, excluding development and test systems
  • Synchronize users from the organization scope, including only those with descriptions
  • Synchronize targets from a specific project scope, including only production targets with sessions longer than 30 minutes
  • Synchronize only active and pending sessions across the organization

Advanced Filtering Scenarios

For more complex organizational needs, you can create sophisticated filtering strategies:

Multi-Environment Filtering:

"targets": {
  "scope_id": "o_MainOrg",
  "filter": "(/name contains 'prod' and /session_max_seconds >= 3600) or (/name contains 'staging' and /session_max_seconds >= 1800)"
}

Role-Based User Filtering:

"users": {
  "scope_id": "o_MainOrg",
  "filter": "/name matches '^(admin|operator|engineer)-.*' and /description is not empty"
}

Time-Based Session Filtering:

"sessions": {
  "scope_id": "o_MainOrg",
  "filter": "/status in ['active', 'pending'] and /session_max_seconds >= 900"
}

Configuring Your Adapter Settings

When setting up your Boundary integration in SGNL:

  1. Replace Hostname: Update the hostname field with your actual Boundary deployment URL
  2. Update Auth Method ID: Replace the example auth method ID with your actual authentication method ID
  3. Configure Entity Scoping: Add entityConfig sections for entities you want to scope to specific organizational levels
  4. Set Appropriate Timeouts: Adjust the request timeout if your Boundary deployment requires longer response times

Understanding HashiCorp Boundary Entity Structure

The HashiCorp Boundary template defines several interconnected entities that represent the complete infrastructure access ecosystem within your Boundary deployment.

Account Entity: Represents authentication accounts within Boundary, including login names, email addresses, associated authentication methods, and managed group memberships. Accounts link users to their authentication credentials and provide the foundation for session establishment.

User Entity: Represents Boundary users with their organizational context, including scope assignments, account associations, login names, and contact information. Users are the primary entities that establish sessions and access targets within the Boundary ecosystem.

Group Entity: Represents organizational groups within Boundary that can contain users and be assigned to roles. Groups provide organizational structure that can inform access decisions and simplify permission management across large user populations.

Role Entity: Represents permission sets within Boundary that define what actions principals (users or groups) can perform within specific scopes. Roles contain grant strings that specify detailed permissions and are fundamental to Boundary’s authorization model.

Scope Entity: Represents the hierarchical organizational structure within Boundary (Global, Organization, Project levels). Scopes contain other resources and define permission boundaries, making them crucial for understanding the organizational context of access decisions.

Target Entity: Represents the infrastructure resources that users access through Boundary, including connection details, session limits, credential sources, and worker filters. Targets are the primary resources that Boundary protects and represent the infrastructure access patterns that inform broader security decisions.

Host Entity: Represents the actual infrastructure endpoints (servers, databases, applications) that are accessible through Boundary targets. Hosts contain network addressing information and external identifiers that connect Boundary’s access control to actual infrastructure resources.

Session Entity: Represents active and historical connection sessions between users and targets, including session duration, status, connection details, and termination information. Sessions provide critical access pattern data that can inform real-time and historical access control decisions.

Credential Entity: Represents managed credentials that Boundary uses to authenticate to target resources on behalf of users. Understanding credential usage patterns provides important context about infrastructure access methods and security posture.

SessionStates Entity: Represents the detailed state information for sessions, including status transitions, timing data, and lifecycle information. This provides granular visibility into session behavior and access patterns.

Complex Infrastructure Access Relationships

The HashiCorp Boundary template captures sophisticated relationships that reflect how identity, resources, and access patterns interconnect within infrastructure access scenarios.

User-Session-Target Relationships: The integration maps the complete access chain from users through their active sessions to the targets they’re accessing. This enables policies that understand current infrastructure usage patterns and can make decisions based on active access contexts.

Role-Based Permission Mapping: Boundary roles define complex permission sets through grant strings and scope assignments. The integration captures these relationships to enable policies that understand not just what users can access, but what permissions they have within specific organizational contexts.

Credential and Target Associations: The integration maps how credentials are associated with targets and used within active sessions. This provides visibility into credential usage patterns and can inform policies about infrastructure access methods and security practices.

Hierarchical Scope Relationships: Boundary’s hierarchical scope structure (Global → Organization → Project) is captured in the integration, enabling policies that understand organizational boundaries and permission inheritance patterns.

Host and Target Infrastructure Mapping: The relationship between targets (Boundary’s access endpoints) and hosts (actual infrastructure resources) provides the connection between Boundary’s access control layer and real infrastructure resources.

Testing and Verification

After configuring the HashiCorp Boundary integration, systematic testing ensures that your infrastructure access data is being correctly imported and that the complex relationships between users, sessions, targets, and infrastructure resources are properly established.

Initial Connection Test

  1. Save Configuration: Click “Continue” to save your HashiCorp Boundary System of Record configuration
  2. Verify Authentication: SGNL will attempt to connect to Boundary using your provided credentials and hostname
  3. Check API Access: Review any error messages related to authentication failures or permission issues
  4. Validate Hostname: Ensure that the Boundary hostname is correctly formatted and accessible from your SGNL environment

Enable Entity Synchronization

The Boundary integration includes multiple related entities that should be enabled systematically to ensure complete infrastructure access mapping:

  1. Review Entity Structure: Examine each entity type (User, Group, Role, Scope, Target, Host, Session, Account, Credential) to understand the infrastructure data each will provide
  2. Enable Core Entities First: Start by enabling User, Group, and Scope entities to establish the basic organizational structure
  3. Enable Infrastructure Entities: Add Target and Host entities to capture the infrastructure resources being accessed
  4. Enable Access Pattern Entities: Enable Session and Account entities to capture actual access patterns and authentication relationships
  5. Enable System Synchronization: Once all individual entities are enabled, enable synchronization for the entire Boundary System of Record

Verify Infrastructure Access Data Import

  1. Monitor Synchronization Progress: Watch the import progress for each entity type, noting that Session entities may provide the most dynamic data as they reflect current access patterns
  2. Validate Entity Counts: Compare the number of imported entities with your expectations based on your Boundary deployment size and organizational structure
  3. Check Infrastructure Relationships: Use SGNL’s interface to spot-check that users are properly connected to their sessions, sessions to targets, and targets to actual infrastructure hosts
  4. Review Access Patterns: Verify that current and recent session data is being captured to provide real-time infrastructure access context

Test Infrastructure Access Context

  1. Verify Target-Host Relationships: Confirm that Boundary targets are properly connected to their underlying infrastructure hosts and that network addressing information is correctly captured
  2. Check Session Activity: Verify that active sessions are being captured and that session state transitions are properly recorded
  3. Validate Credential Relationships: If using Boundary-managed credentials, confirm that credential associations with targets and sessions are properly established
  4. Test Scope Hierarchy: Verify that the hierarchical scope structure is correctly represented and that resources are properly associated with their containing scopes

Test with DataLens

Once synchronization is complete, use DataLens to explore your Boundary infrastructure access data:

  1. Explore User Access Patterns: Query which targets users are accessing and what their current session status is across your infrastructure
  2. Test Infrastructure Relationships: Verify that you can trace from users through sessions to specific infrastructure hosts they’re accessing
  3. Check Permission Context: Confirm that role assignments and scope relationships are correctly established and queryable
  4. Validate Session Data: Test queries that show current active sessions, recent access patterns, and session duration information

Troubleshooting

Authentication and Connection Issues

Basic Authentication Failures: If SGNL cannot authenticate with Boundary, verify that your username and password are correctly entered and that the user account exists within the specified authentication method. Test the credentials by logging into Boundary directly with the same credentials.

Authentication Method ID Issues: If authentication fails with auth method errors, verify that the authMethodId in your adapter configuration matches exactly with an existing authentication method in your Boundary deployment. Check that the authentication method is active and properly configured.

Hostname and Connectivity Problems: If SGNL cannot connect to Boundary, verify that the hostname is correctly formatted and that there are no network connectivity issues. For HCP Boundary, ensure the UUID is correct. For self-managed Boundary, verify that the controller is accessible and that any required ports are open.

Permission and Authorization Errors: If authentication succeeds but entity synchronization fails, verify that your integration user has appropriate read permissions across all the scopes and entity types you’re trying to synchronize. Check role assignments and scope permissions within Boundary.

Data Synchronization Challenges

Large Deployment Performance: Boundary deployments with thousands of targets, extensive session history, or complex organizational hierarchies may experience slow synchronization times. Consider using entity scoping in the adapter configuration to limit synchronization to the most relevant organizational units or time periods.

Session Data Volume: Session entities can generate large amounts of data, especially in active environments. If session synchronization is impacting performance, consider filtering session data by date range or status to focus on the most relevant access patterns.

Scope and Entity Filtering Issues: If entity scoping isn’t working as expected, verify that your scope IDs are correctly formatted and that the specified scopes contain the entities you’re trying to synchronize. Boundary’s hierarchical structure means that entities exist within specific scope contexts.

Filter Expression Errors: If synchronization fails with filter-related errors, check your filter expression syntax against Boundary’s filter documentation. Common issues include:

  • Missing quotes around JSON Pointer selectors (use "/name" not /name)
  • Invalid JSON Pointer paths that don’t match actual entity attributes
  • Malformed regular expressions in matches operators
  • Incorrect logical operator precedence (use parentheses to group complex expressions)
  • Using unsupported operators or comparing incompatible data types

Filter Performance Issues: Complex filter expressions with many conditions or regular expressions can impact synchronization performance. If you experience slow synchronization:

  • Simplify filter expressions by using equality checks instead of regular expressions where possible
  • Apply the most selective filters first in AND operations
  • Use scope filtering to reduce the dataset before applying complex attribute filters
  • Test filter performance in your Boundary environment with realistic data volumes

Credential Sensitivity: Credential entities contain sensitive information. Ensure that your SGNL environment is properly secured and that credential synchronization is configured according to your organization’s security policies for handling infrastructure access credentials.

Boundary-Specific Configuration Issues

Auth Method Configuration: If the authentication method ID is not working, verify that you’re using the correct ID format (typically ampw_* for password methods) and that the authentication method is properly configured within the correct Boundary scope.

Entity Configuration Scoping: Boundary’s hierarchical scope structure can be complex. If certain entities aren’t synchronizing, verify that you’re specifying the correct scope level (Global, Organization, or Project) and that the integration user has access to those scopes.

Target and Host Relationship Mapping: If target-to-host relationships aren’t being established correctly, verify that your targets are properly configured with host sources and that the host entities exist within the scopes you’re synchronizing.

Session State Complexity: Boundary sessions have complex state transitions. If session state information isn’t synchronizing correctly, check that the SessionStates parent-child relationship is properly configured and that session data is being processed in the correct order.

Performance and Scale Considerations

API Rate Limiting: Boundary APIs may have rate limits that affect synchronization of large deployments. The default configuration should respect these limits, but you may need to adjust the request timeout or API call frequency for very large environments.

Session History Volume: Historical session data can be extensive. Consider whether you need complete session history for your access control policies or whether focusing on recent sessions (last 30-90 days) would provide sufficient context while improving performance.

Real-Time Session Updates: Sessions are dynamic entities that change frequently. Consider how often you need session data updates to balance real-time accuracy with system performance requirements.

Integration with SGNL Policies

Once your HashiCorp Boundary integration is successfully configured and synchronized, you can leverage the comprehensive infrastructure access data in sophisticated SGNL policies that bridge infrastructure access patterns with broader organizational access control decisions.

Infrastructure Access Context Policies: Use Boundary session data to create policies that consider current infrastructure access patterns when making decisions about other system access. For example, users currently accessing production database targets might receive enhanced scrutiny for administrative application access.

Target-Based Resource Policies: Leverage Boundary target information to understand infrastructure resource usage patterns and apply those patterns to related systems. Users who regularly access specific infrastructure targets might automatically receive access to related monitoring tools, documentation systems, or support applications.

Session-Based Dynamic Access: Use active Boundary session information to create dynamic access policies that change based on current infrastructure connectivity. Users with active sessions to critical infrastructure might be subject to additional authentication requirements or restricted from certain other activities.

Credential Management Policies: Leverage Boundary credential usage patterns to inform policies about privileged access in other systems. Users who frequently use elevated credentials in Boundary might require additional verification for administrative access to business applications.

Scope-Based Organizational Policies: Use Boundary’s hierarchical scope structure to extend organizational boundaries into other systems. Users with access to specific Boundary projects might automatically receive corresponding access to related development tools, project management systems, or collaboration platforms.

Role-Based Infrastructure Permissions: Map Boundary role assignments to corresponding permissions in other systems. Users with specific infrastructure access roles might receive related permissions in monitoring tools, incident response systems, or documentation platforms.

Historical Access Pattern Analysis: Use Boundary’s comprehensive session history to identify access patterns and anomalies that can inform broader security policies. Unusual infrastructure access patterns might trigger additional verification requirements or security reviews across other systems.

For comprehensive guidance on creating policies with infrastructure access data, refer to the SGNL Policy Management documentation. For understanding how Boundary entities relate to other systems in your environment, review the Entities and Relationships guide.