The firewall identity mapper Docker container (fw-id-mapper)

In this topic, you will learn what the fw-id-mapper Docker container does, its requirements, as well as how to deploy and configure it.

Overview

A user’s IP address changes as they move between Wi-Fi, wired, VPN, hot desk, and DHCP-assigned connections, which makes it difficult or even impossible to apply firewall rules correctly. The fw-id-mapper Docker container tracks these changes and reports them to the firewall, covering authentication, IP changes, DHCP changes, roaming, VPN transitions, disconnects, deauthentication, and session expiration.

The container is available in the public Docker repository as portnox/fw-id-mapper. It has no virtual machine equivalent.

Examples:

Policy:
- Without identity mapping:
  
  Allow 10.10.20.0/24 to Salesforce
- With identity mapping:
  
  Allow Finance users to Salesforce
  
  Allow Domain Administrators to SSH to servers
Log:
- Without identity mapping:
  
  10.22.45.18 downloaded malware
- With identity mapping:
  
  kosh@vorlon.com downloaded malware

Requirements

The container can run on Linux, or on Windows or macOS via Docker Desktop. If running in a VM environment, we recommend Linux for the best results, since Windows and macOS would require double virtualization.
The Docker host needs outbound HTTPS (port 443 only) connectivity to Portnox Cloud, the Portnox firewall integration gateway, and the target firewall’s management interface. Follow the general firewall rules in the following topic: How to set up the firewall for Portnox Docker containers to connect to Portnox Cloud.
You need a Portnox organization ID, a Portnox connector instance ID, and a Portnox connector API key. Portnox Cloud supplies all of these values when you add the integration.
For Palo Alto firewall configuration requirements, see below.

Deployment

We recommend getting the deployment command from Portnox Cloud rather than copying the example below. In Portnox Cloud, go to Settings > Integration Services > Firewall Integration Service and click on the Add Docker container button. Portnox Cloud generates the complete command for you, already containing your organization ID, instance ID, and API key, along with the API token that authenticates the container.

Note:

You can only generate this token in the Add Docker container window. It doesn’t work with tokens you generate on the CLEAR API TOKENS screen, and that screen doesn’t list it.

Warning:

When you generate a new token, the current one becomes invalid, so any container already running with it stops working until you redeploy it with the new token. The token itself never expires.

Run the container in Docker:
```
docker run -d \
  --name portnox-fw-id-mapper --restart=on-failure --pull always \
  -e OrgId="org_id" \
  -e InstanceId="instance_id" \
  -e ApiKey="api_key" \
  portnox/fw-id-mapper:latest
```
Note:
This command is an example only, with placeholder values that won’t work as-is. Replace them with your Portnox organization ID, instance ID, and API key, or use the complete command that Portnox Cloud generated for you.

Optional: Alternatively, deploy the container with Docker Compose:

services:
  fw-id-mapper:
    image: portnox/fw-id-mapper:latest
    container_name: portnox-fw-id-mapper
    restart: on-failure
    pull_policy: always
    environment:
      OrgId: "org_id"
      InstanceId: "instance_id"
      ApiKey: "api_key"

docker compose up -d

After deployment, we recommend that you monitor the container’s logs to confirm it registered and authenticated with the Portnox gateway:

Docker:
```
docker logs -f portnox-fw-id-mapper
```
Docker Compose:
```
docker compose logs -f fw-id-mapper
```

Configuration

Configure the container using either environment variables or a configuration file, appsettings.json, inside the container. If you use both methods, environment variables take priority.


Environment variable Config file setting	Default	Description
`OrgId`	Required	Portnox organization ID
`InstanceId`	Required	Unique identifier for this connector instance
`ApiKey`	Required	API key used to authenticate with the Portnox gateway
`GatewayUrl`	`https://extfwint-local-gw.portnox.com`	Portnox firewall identity mapping gateway URL; set this only if Portnox Cloud gave you a separate test environment URL, for example `https://extfwint-local-gw-test.portnox.com`
`SyncInterval`	`00:00:30`	Interval at which the connector polls the gateway for firewall connection changes
`FwReachabilityCheckTimeout`	`00:00:10`	TCP timeout used when checking firewall reachability
`SbListener__MinRetryDelay` `SbListener:MinRetryDelay`	`00:00:02`	Minimum service bus listener retry delay
`SbListener__MaxRetryDelay` `SbListener:MaxRetryDelay`	`00:01:00`	Maximum service bus listener retry delay
`SbListener__SettingsPollInterval` `SbListener:SettingsPollInterval`	`00:00:02`	Interval used to poll service bus listener settings
`SbListener__TokenExpiryMargin` `SbListener:TokenExpiryMargin`	`00:05:00`	Margin used when handling service bus authentication token expiration
`PaloAltoUserId__MaxAttempts` `PaloAltoUserId:MaxAttempts`	`3`	Maximum attempts for Palo Alto User-ID operations
`PaloAltoUserId__RetryBaseDelay` `PaloAltoUserId:RetryBaseDelay`	`00:00:00.250`	Initial retry delay for Palo Alto User-ID operations. Doubles after each retry.
`MappingEventAggregation__Window` `MappingEventAggregation:Window`	`00:00:05`	Time window used to aggregate mapping events that occur in rapid succession, such as during roaming or reconnects

TLS and certificate configuration

The container communicates with configured firewalls over HTTPS. By default, it validates the firewall’s certificate against the standard system trust store. You only need the settings below if your firewall’s certificate comes from a private or internal CA that isn’t in that trust store.

Note:

To disable validation entirely, set IgnoreFwRemoteCertificateValidation="true". Use this for development and testing, not production.


Variable	Description
`FwCaCertificatePaths`	One or more certificate file paths, separated by semicolons
`FwCaCertificatesBase64`	One or more Base64-encoded certificates, separated by semicolons
`FwCaCertificatesDir`	A directory inside the container containing .pem, .crt, or .cer files. Recommended for container deployments. Mount your host’s certificate directory to this path, for example: `-v /opt/portnox/fw-id-mapper/certs:/certs/ca:ro`, then set `FwCaCertificatesDir="/certs/ca"` to match.

If IgnoreFwRemoteCertificateValidation is true, the container ignores any CA certificate configuration, since validation is already disabled. Keep validation enabled in production and provide the CA certificate instead.

Palo Alto Networks integration

As of this moment, this container supports only Palo Alto Networks User-ID, through the Palo Alto XML API rather than syslog parsing. This gives an explicit accept or reject response for each mapping, avoiding problems syslog-based integrations commonly have: incorrect message formatting, parser changes, username or IP address extraction errors, messages sent but not accepted, and silent synchronization failures.

On the Palo Alto firewall, create an administrator account with the User-ID agent permission, then generate a key from that account’s /api/?type=keygen endpoint. Save the key in a temporary file. You will need it in the next step.
In Portnox Cloud, go to Settings > Integration Services > Firewall Integration Service, find your container, and click on the Add firewall connection button. Then, fill in the details:
- Connection name: Enter a name for this connection
- Vendor: Currently, only the Palo Alto option is available.
- Integration type: Currently, only the User ID option is available.
- IP address/hostname and Port: Enter the values to connect to the firewall (default port: 443). Use the firewall’s own port if the Palo Alto User-ID API is configured on a non-standard HTTPS port.
- Vsys: Enter a value only if the firewall runs multiple virtual systems, otherwise leave this field blank to use the firewall’s default vsys1.
- Keygen API key: Paste the key that you generated in the previous step.
- Automatically unregister IP address-to-tag mapping (minutes): Enter a value or leave the default value 60.
Click on the Test connection button to confirm Portnox Cloud can reach the firewall, then click on the Save connection button.

Note:

The Palo Alto User-ID API supports login and logout operations. A login operation creates a user-to-IP mapping, a logout operation removes it. The container issues these based on Portnox authentication and accounting events, so the firewall’s identity state tracks users as they connect and disconnect.

Troubleshooting

To collect Docker container logs for troubleshooting, see the following topic: How to collect Portnox Docker container logs for support.

Check container status:
```
docker ps
```
If you deployed with Docker Compose, use instead:
```
docker compose ps
```
Verify gateway connectivity from the Docker host:
```
curl -v https://extfwint-local-gw.portnox.com
```
A successful TCP/TLS connection confirms basic network connectivity. It does not confirm the connector is registered or authenticated.
Verify firewall connectivity from the Docker host:
```
nc -vz firewall_ip 443
```
To also verify the TLS handshake, not just that the port is open:
```
curl -vk https://firewall_ip/
```
Use the firewall’s actual port instead of 443 if the Palo Alto User-ID API is configured on a non-standard HTTPS port.
Check for common configuration problems:
- Container starts but doesn’t connect: check the logs and verify OrgId, InstanceId, ApiKey, GatewayUrl (if set), and outbound TCP 443 connectivity.
- Portnox Cloud reports the firewall as unreachable: verify the firewall address, port, routing, ACLs, management interface access, and TLS certificate configuration.
- Palo Alto User-ID updates fail: verify the firewall connection in Portnox Cloud, the API key and its permissions, firewall reachability, the configured vsys, and the container logs for the specific API operation and response.
Verify a mapping on the firewall by running the following command from the Palo Alto CLI:
```
show user ip-user-mapping all
```
The output includes the user-to-IP mapping that Portnox reported. You can also check the mapping through the Palo Alto management interface and User-ID monitoring.

Updates

If you use a Docker container running on a local Docker host, it does not update automatically, unless you also use the autoupdate container. The autoupdate container updates all Portnox Docker containers when new versions are available. Updating requires recreating the Docker container, so there may be a short service interruption.
If you deploy the Docker container in a cloud environment, you cannot use the autoupdate container, because it requires direct access to the local Docker engine, which these managed cloud services do not expose. You must update containers deployed this way manually by redeploying them with the latest image.