portnox/fw-id-mapper repository overview

⁠Portnox Firewall Identity Mapper

The Portnox Firewall Identity Mapper is an on-premises Docker container that connects Portnox Cloud identity and network events to on-premises firewalls.

It receives user-to-IP mapping events from Portnox Cloud and securely delivers them to supported firewalls, allowing the firewall to associate a user's identity with their current IP address.

The initial integration supports Palo Alto Networks User-ID through the Palo Alto XML API.

⁠What problem does it solve?

Traditional firewall policies are often based on IP addresses, VLANs, subnets, ports, and applications. This can make it difficult to enforce policies based on who the user actually is.

For example, without user identity information, a firewall policy might look like:

Allow 10.10.20.0/24 to Salesforce

With User-ID, the same firewall can make decisions based on identity:

Allow Finance users to Salesforce

or:

Allow Domain Administrators to SSH to servers

This becomes particularly important when users move between:

• Wi-Fi networks
• Wired networks
• VPN connections
• Hot desks
• DHCP-assigned IP addresses
• Remote access environments

The user's IP address may change, but their identity remains the same.

The Firewall Identity Mapper bridges this gap by continuously communicating current Portnox identity information to the customer firewall.

⁠Why use the Portnox Firewall Identity Mapper?

The container provides several important benefits.

⁠Identity-aware firewall policies

Palo Alto User-ID can use the mappings supplied by Portnox to associate an IP address with a specific user. This allows firewall policies to be based on users and groups rather than only network addresses.

⁠More meaningful firewall logs

Instead of seeing activity associated only with an IP address:

10.22.45.18 downloaded malware

the firewall can associate the activity with the authenticated user:

sparkles downloaded malware

This improves visibility, investigation, and incident response.

⁠Real-time session updates

Portnox can communicate changes to user sessions, including:

• User authentication
• IP address changes
• DHCP changes
• Network roaming
• VPN transitions
• User disconnects
• Deauthentication
• Session expiration

The firewall can therefore maintain a more accurate representation of the current user-to-IP relationship.

⁠Transactional API integration

The integration uses the firewall vendor's API rather than relying on generic Syslog parsing.

This provides an explicit response from the firewall indicating whether the mapping was accepted or rejected.

This helps avoid problems associated with Syslog integrations, such as:

• Incorrect message formatting
• Parser changes
• Username extraction problems
• IP address parsing problems
• Messages being sent but not actually accepted
• Silent synchronization failures

⁠Secure on-premises deployment

The container runs inside the customer network and establishes outbound connectivity to Portnox Cloud.

The firewall does not need to be exposed to the public Internet.

The container communicates directly with the customer's firewall from the internal network.

⁠The container

1. Authenticates to Portnox Cloud using its connector identity.
2. Receives user-to-IP mapping events from Portnox Cloud.
3. Maintains communication with the Portnox Firewall Integration Gateway.
4. Receives the firewall connection configuration from the gateway.
5. Sends user-to-IP mappings to the configured firewall.
6. Reports firewall connectivity and command results back to the gateway.

The container uses Azure Service Bus over AMQP WebSockets/TLS to receive mapping events. This deliberately uses HTTPS port 443 rather than the standard AMQP ports 5671/5672, which are commonly blocked by corporate firewalls.

⁠Requirements

Before deploying the container, ensure the following are available:

• Docker Engine
• Network connectivity from the Docker host to:
  • Portnox Cloud
  • Portnox Firewall Integration Gateway
  • The target firewall
• A Portnox organization ID
• A Portnox connector instance ID
• A Portnox connector API key
• A Palo Alto firewall configured for User-ID XML API access
• A Palo Alto administrator/API account with the required User-ID permissions

The Docker host should be able to initiate outbound HTTPS connections to Portnox Cloud and the Portnox Firewall Integration Gateway.

The Docker host must also be able to reach the firewall's management interface over HTTPS.

⁠Docker Image

The Docker image is available from Docker Hub:

portnox/fw-id-mapper

Pull the latest image with:

docker pull portnox/fw-id-mapper:latest

## Deployment

### Docker

Pull the image:

```bash
docker pull portnox/fw-id-mapper:latest

Run the container:

docker run -d \
  --name portnox-fw-id-mapper \
  --restart unless-stopped \
  -e OrgId="YOUR_ORG_ID" \
  -e InstanceId="YOUR_UNIQUE_INSTANCE_ID" \
  -e ApiKey="YOUR_API_KEY" \
  -e GatewayUrl="https://extfwint-local-gw.portnox.com" \
  portnox/fw-id-mapper:latest

Replace the following values:

The container does not require any inbound ports to be exposed.

It establishes outbound connections to the Portnox Cloud gateway, Azure Service Bus, and the configured firewalls.

⁠Docker Compose

Example docker-compose.yml:

services:
  fw-id-mapper:
    image: portnox/fw-id-mapper:latest
    container_name: portnox-fw-id-mapper
    restart: unless-stopped
    environment:
      OrgId: "YOUR_ORG_ID"
      InstanceId: "YOUR_UNIQUE_INSTANCE_ID"
      ApiKey: "YOUR_API_KEY"
      GatewayUrl: "https://extfwint-local-gw.portnox.com"

Start the container:

docker compose up -d

Check the container:

docker compose ps

View logs:

docker compose logs -f fw-id-mapper

⁠Configuration

Configuration can be supplied through environment variables.

Environment variables take precedence over values specified in appsettings.json.

Nested configuration settings use double underscores (__) in environment variable names.

For example:

SbListener__MinRetryDelay

corresponds to:

SbListener:MinRetryDelay

⁠Required Configuration

⁠Gateway URL

For production deployments, use:

https://extfwint-local-gw.portnox.com

For test environments, use the gateway URL provided for that environment.

For example:

https://extfwint-local-gw-test.portnox.com

The gateway is used for:

• Connector registration
• Connector authentication
• Connector heartbeat
• Firewall connection synchronization
• Reporting firewall reachability
• Reporting firewall command results

⁠TLS and Certificate Configuration

The Firewall Identity Mapper communicates with configured firewalls using HTTPS.

By default, TLS certificate validation is enabled.

⁠Ignore Firewall Certificate Validation

IgnoreFwRemoteCertificateValidation

Default:

false

When set to true, TLS certificate validation is disabled for firewall connections.

Example:

-e IgnoreFwRemoteCertificateValidation="true"

This option is intended for development and testing environments.

It is not recommended for production deployments.

⁠Custom CA Certificates

If the firewall uses a certificate signed by a private or otherwise non-standard CA, the CA certificate can be supplied to the container.

There are three supported configuration options.

⁠Certificate File Paths

FwCaCertificatePaths

Specify one or more certificate files separated by semicolons.

Example:

-e FwCaCertificatePaths="/certs/firewall-ca.pem;/certs/another-ca.pem"

⁠Base64-Encoded Certificates

FwCaCertificatesBase64

Specify one or more Base64-encoded certificates separated by semicolons.

Example:

-e FwCaCertificatesBase64="BASE64_CERTIFICATE_1;BASE64_CERTIFICATE_2"

⁠Certificate Directory

FwCaCertificatesDir

Specify a directory containing CA certificates.

The container searches the directory for:

• .pem
• .crt
• .cer

Example:

-e FwCaCertificatesDir="/certs/ca"

This is the recommended approach for container deployments.

⁠Certificate Configuration Precedence

If:

IgnoreFwRemoteCertificateValidation=true

certificate configuration is ignored because certificate validation has been disabled.

For production environments, keep certificate validation enabled and provide the required CA certificate instead.

⁠Operational Configuration

The following settings control synchronization, connectivity checks, event processing, and retry behavior.

⁠Retry Behavior

Palo Alto User-ID operations use retry behavior to handle transient communication failures.

The default configuration allows up to three attempts.

The retry delay starts at:

250 ms

and doubles after each retry.

These settings can be changed using:

PaloAltoUserId__MaxAttempts
PaloAltoUserId__RetryBaseDelay

⁠Event Aggregation

User-to-IP mapping events can occur in rapid succession, particularly when users authenticate, roam between wireless access points, reconnect, or otherwise change network state.

The Firewall Identity Mapper aggregates mapping events within a configurable time window.

Default:

00:00:05

Configure the aggregation window using:

MappingEventAggregation__Window

Example:

-e MappingEventAggregation__Window="00:00:10"

⁠Palo Alto Networks Integration

The initial Firewall Identity Mapping integration supports Palo Alto Networks User-ID.

The Firewall Identity Mapper receives user-to-IP mapping information from Portnox Cloud and sends the mappings directly to the Palo Alto firewall.

The integration uses the Palo Alto XML API rather than relying on syslog parsing.

⁠Palo Alto Firewall Configuration

Create a dedicated administrator account for the integration.

The account should be configured with the minimum permissions required to perform the User-ID operations needed by the integration.

For Palo Alto deployments, configure the appropriate User-ID Agent permission in the administrator role's XML API permissions.

Generate an API key for the account using the Palo Alto XML API key-generation endpoint.

The resulting API key is configured as part of the firewall connection in Portnox.

⁠Firewall Connection

Firewall connection information is configured through Portnox Cloud.

The Firewall Identity Mapper periodically synchronizes the configured firewall connections from the Portnox gateway.

The firewall connection contains the information required to communicate with the firewall, including:

• Firewall address
• Firewall port
• Virtual system (vsys), where applicable
• API key

The Firewall Identity Mapper does not require firewall connection information to be hard-coded in the Docker command.

⁠User-ID Mapping Lifecycle

The mapping lifecycle is driven by Portnox authentication and accounting information.

When Portnox determines that a user is associated with an IP address, the Firewall Identity Mapper receives a mapping event.

The mapper then sends the corresponding User-ID update to the configured Palo Alto firewall.

A typical mapping contains:

User
IP address

The Palo Alto User-ID API supports both login and logout operations.

A login operation establishes a user-to-IP mapping.

A logout operation removes the mapping.

The integration can therefore maintain the firewall's identity state as users connect and disconnect from the network.

⁠Network Connectivity

The Firewall Identity Mapper requires outbound network connectivity.

⁠Azure Service Bus

The connector uses AMQP over WebSockets.

This allows Service Bus communication to use:

TCP 443

The connector does not require direct outbound AMQP connectivity on ports 5671 or 5672.

This is particularly useful in environments where outbound Internet traffic is restricted to HTTPS.

⁠Firewall Connectivity

The Docker host must be able to reach each configured firewall on the configured address and port.

For a typical Palo Alto deployment, this will be:

TCP 443

The Firewall Identity Mapper performs firewall reachability checks using the configured timeout.

Default:

10 seconds

Configure this value with:

FwReachabilityCheckTimeout

Example:

-e FwReachabilityCheckTimeout="00:00:15"

⁠Proxy and Firewall Considerations

If the Docker host is located behind an outbound proxy or restrictive firewall, allow outbound HTTPS connectivity to the Portnox gateway.

Allow outbound TCP 443 to the Portnox gateway:

Allow TCP 443 from the Docker host to the Portnox gateway

Allow outbound TCP 443 for Azure Service Bus WebSockets:

Allow TCP 443 from the Docker host to Azure Service Bus

Allow the Docker host to reach each configured firewall:

Allow TCP 443 from the Docker host to the Palo Alto firewall

The firewall connection may use a different port if the Palo Alto User-ID API is configured on a non-standard HTTPS port.

No inbound Internet connection to the Firewall Identity Mapper container is required.

⁠Health and Troubleshooting

⁠View Container Status

docker ps

Example:

CONTAINER ID   IMAGE                         STATUS
xxxxxxxxxxxx   portnox/fw-id-mapper:latest   Up 5 minutes

⁠View Logs

docker logs portnox-fw-id-mapper

Follow logs in real time:

docker logs -f portnox-fw-id-mapper

With Docker Compose:

docker compose logs -f fw-id-mapper

⁠Verify Gateway Connectivity

From the Docker host, verify that the gateway can be reached:

curl -v https://extfwint-local-gw.portnox.com

A successful TCP/TLS connection confirms basic network connectivity.

An HTTP response does not necessarily indicate that the connector is authenticated or registered correctly.

⁠Verify Firewall Connectivity

Test connectivity from the Docker host to the Palo Alto firewall:

nc -vz FIREWALL_IP 443

Or:

curl -vk https://FIREWALL_IP/

If the connection fails, verify:

1. The firewall address is correct.
2. The firewall port is correct.
3. Routing exists between the Docker host and firewall.
4. Intermediate firewalls permit the connection.
5. The Palo Alto management/API interface is reachable.
6. TLS certificate validation is configured correctly.

⁠Common Configuration Problems

⁠Container Starts but Does Not Connect

Check:

docker logs portnox-fw-id-mapper

Verify:

• OrgId
• InstanceId
• ApiKey
• GatewayUrl
• Outbound TCP 443 connectivity

⁠Firewall Is Reported as Unreachable

Verify connectivity from the Docker host:

nc -vz FIREWALL_IP FIREWALL_PORT

Then verify:

• Firewall address
• Firewall port
• Routing
• ACLs
• Firewall management interface access
• TLS certificate configuration

⁠TLS Certificate Errors

If the firewall uses a private CA, configure:

FwCaCertificatesDir

or:

FwCaCertificatePaths

For temporary development/testing only, certificate validation can be disabled:

IgnoreFwRemoteCertificateValidation=true

⁠Palo Alto User-ID Updates Fail

Verify:

• The firewall connection is configured correctly in Portnox Cloud.
• The API key is valid.
• The API key belongs to an account with the required User-ID XML API permissions.
• The firewall is reachable from the Docker host.
• The configured vsys is correct, if applicable.
• The Palo Alto User-ID service/API is available.

Review the container logs for the specific API operation and response.

⁠Verifying Palo Alto User-ID Mappings

After a user has authenticated and the mapping event has been processed, verify the mapping on the Palo Alto firewall.

From the Palo Alto CLI:

show user ip-user-mapping all

The output should include the user-to-IP mapping reported by Portnox.

You can also verify the mapping through the Palo Alto management interface and User-ID monitoring/logging.

A successful mapping allows security policies and other identity-aware firewall functionality to reference the authenticated user rather than relying only on the source IP address.

⁠Security Recommendations

For production deployments:

1. Run the container on a dedicated or appropriately secured Docker host.
2. Protect the Portnox API key.
3. Do not place credentials directly into scripts that are committed to source control.
4. Use Docker secrets or an equivalent secure secret-management mechanism where appropriate.
5. Use a dedicated Palo Alto administrator account for the integration.
6. Grant only the permissions required by the integration.
7. Keep TLS certificate validation enabled.
8. Use a trusted CA certificate for the firewall when required.
9. Restrict network connectivity to only the destinations and ports required by the integration.
10. Monitor the container logs and firewall User-ID activity.

⁠Example Production Deployment

Example:

docker run -d \
  --name portnox-fw-id-mapper \
  --restart unless-stopped \
  -e OrgId="12345678" \
  -e InstanceId="fw-id-mapper-dc01" \
  -e ApiKey="REPLACE_WITH_API_KEY" \
  -e GatewayUrl="https://extfwint-local-gw.portnox.com" \
  -e FwCaCertificatesDir="/certs/ca" \
  -v /opt/portnox/fw-id-mapper/certs:/certs/ca:ro \
  portnox/fw-id-mapper:latest

In this example:

• The container automatically restarts if the Docker host restarts.
• Firewall CA certificates are mounted read-only.
• The Portnox gateway is accessed over HTTPS.
• No inbound container port is exposed.
• Firewall connections are obtained from Portnox Cloud.

⁠Configuration Reference

⁠Summary

Portnox Firewall Identity Mapper provides a lightweight on-premises integration between Portnox Cloud and network firewalls.

The container:

1. Authenticates to the Portnox gateway.
2. Receives user-to-IP mapping events through Azure Service Bus.
3. Synchronizes configured firewall connections.
4. Checks firewall reachability.
5. Sends user-to-IP mappings to supported firewalls.
6. Reports firewall command results back through the Portnox integration infrastructure.

The initial firewall integration supports Palo Alto Networks User-ID using the Palo Alto XML API.

The deployment is designed to require only outbound connectivity from the Docker host and does not require inbound Internet access to the container.