Identity-Based Microsegmentation Guide
LAST UPDATED: October 8, 2021

Windows hosts

About Windows host installs

To deploy the enforcer to a Windows host, use one of the following procedures.

  • Cloud install: uses a short-lived token from AWS, GCP, or Azure to install, register, and connect the enforcer to the Microsegmentation Console. Many of our customers complete this procedure once and make an image of the machine that has the enforcer installed.

  • On-Premise install: requires a Microsegmentation token to install. Once installed, the enforcer uses a least-privilege app credential to register and connect to the Microsegmentation Console.

Cloud install

  1. Ensure that you meet the following prerequisites.

    Entity Requirement
    Target host Meets the system requirements
    ■ Set up to synchronize time with authoritative sources: AWS, GCP, Azure
    ■ Can connect to *.aporeto.com, *.prismacloud.io, and *.network.prismacloud.io
    Local host apoctl installed
    Privileges namespace.administrator privileges in the target Microsegmentation namespace
    ■ Administrator access to the target instance
    Cloud credentials AWS: an IAM role attached to the target host with read-only access to tags (ec2:DescribeTags)
    GCP: GCP service account attached to the target host
    Azure: target host assigned a managed identity
  2. Construct a Microsegmentation tag that identifies your cloud account, project, tenant, or organization. The tag must begin with @auth: followed by a key-value pair. Refer to the table below for some common examples.

    Cloud provider Value Microsegmentation tag syntax Microsegmentation tag example
    AWS AWS account ID* @auth:account=<AWS_ACCOUNT_ID> @auth:account=942613894219
    GCP GCP project ID @auth:projectid=<GCP_PROJECT_ID> @auth:projectid=acme-dev
    Azure Microsoft tenant ID @auth:tenantid=<TENANT_ID> @auth:tenantid=cd629cb5-2826-4126-82fd-3f2df5f5bc7
    GCP and Azure Name of organization @auth:organization=<ORGANIZATION> @auth:organization=acme

    * You can find your AWS account ID under My security credentials in the AWS Management Console.
    To learn how to find your tenant ID, refer to the Microsoft documentation.

  3. On your local host, set a CLOUD_ID_TAG environment variable containing the Microsegmentation tag you’ve constructed to identify authorized enforcers. If the target virtual machine is hosted on AWS, also set an AWS_IAM_ROLE environment variable containing the name of the IAM role attached to the instance prepended with @auth:rolename=. See below for examples.

    • Windows local host:
      $env:CLOUD_ID_TAG="@auth:account=942613894219"
      $env:AWS_IAM_ROLE="@auth:rolename=aporeto"
      
      $env:CLOUD_ID_TAG="@auth:projectid=acme-dev"
      
      $env:CLOUD_ID_TAG="@auth:tenantid=cd629cb5-2826-4126-82fd-3f2df5f5bc7"
      
    • macOS/Linux local host:
      export CLOUD_ID_TAG="@auth:account=942613894219"
      export AWS_IAM_ROLE="@auth:rolename=aporeto"
      
      export CLOUD_ID_TAG="@auth:projectid=acme-dev"
      
      export CLOUD_ID_TAG="@auth:tenantid=cd629cb5-2826-4126-82fd-3f2df5f5bc7"
      
  4. Set a TARGET_NS environment variable containing the Microsegmentation namespace of this enforcer. It should be a grandchild namespace.

    $env:TARGET_NS="/803920923337065472/aws-dev-826088932159/vm1"
    
    export TARGET_NS=/803920923337065472/aws-dev-826088932159/vm1
    

  5. Use one of the following commands to create an API authorization that allows the enforcer to access the Microsegmentation Console. Select the tab that corresponds to the cloud provider of the target host and whether or not you are using the optional mapping.

    • Windows local host:
      Set-Content -Path enf-api-auth.yml -Value @"
      APIVersion: 0
      label: ec2-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $($env:TARGET_NS)
           authorizedSubnets: []
           name: Authorize EC2 enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=awssecuritytoken"
               - "$($env:AWS_IAM_ROLE)"
               - "$($env:CLOUD_ID_TAG)"
      "@ ; if ($?) 
      { apoctl api import -f enf-api-auth.yml }
      
      Set-Content -Path enf-api-auth.yml -Value @"
      APIVersion: 0
      label: gcp-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $($env:TARGET_NS)
           authorizedSubnets: []
           name: Authorize GCP enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=gcpidentitytoken"
               - "$($env:CLOUD_ID_TAG)"
      "@ ; if ($?) 
      { apoctl api import -f enf-api-auth.yml }
      
      Set-Content -Path enf-api-auth.yml -Value @"
      APIVersion: 0
      label: azure-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $($env:TARGET_NS)
           authorizedSubnets: []
           name: Authorize Azure enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=azureidentitytoken"
               - "$($env:CLOUD_ID_TAG)"
      "@ ; if ($?) 
      { apoctl api import -f enf-api-auth.yml }
      
    • macOS/Linux local host:
      cat << EOF | apoctl api import -f -
      APIVersion: 0
      label: ec2-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $TARGET_NS
           authorizedSubnets: []
           name: Authorize EC2 enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=awssecuritytoken"
               - "$AWS_IAM_ROLE"
               - "$CLOUD_ID_TAG"
      EOF
      
      cat << EOF | apoctl api import -f -
      APIVersion: 0
      label: gcp-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $TARGET_NS
           authorizedSubnets: []
           name: Authorize GCP enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=gcpidentitytoken"
               - "$CLOUD_ID_TAG"
      EOF
      
      cat << EOF | apoctl api import -f -
      APIVersion: 0
      label: azure-enforcerd-auth
      data:
       apiauthorizationpolicies:
         - authorizedIdentities:
             - '@auth:role=enforcer'
           authorizedNamespace: $TARGET_NS
           authorizedSubnets: []
           name: Authorize Azure enforcer to access Microsegmentation Console
           propagate: true
           subject:
             - - "@auth:realm=azureidentitytoken"
               - "$CLOUD_ID_TAG"
      EOF
      
  6. Retrieve the URL of your Microsegmentation Console API.

    echo $Env:MICROSEG_API
    
    echo $MICROSEG_API
    

  7. Access the target host, such as via Microsoft Remote Desktop.

  8. Set a MICROSEG_API environment variable containing the URL of your Microsegmentation Console API that you just echoed on your local host.

    $env:MICROSEG_API="https://api.app0.network.prismacloud.io"
    
  9. Confirm that the host can connect to the Microsegmentation Console API and trusts its certificate.

    Invoke-WebRequest -URI $($env:MICROSEG_API)
    
  10. Set a TARGET_NS environment variable containing the Microsegmentation namespace of this enforcer. It should be a grandchild namespace.

    $env:TARGET_NS="/803920923337065472/aws-dev-826088932159/vm1"
    
  11. Download the apoctl MSI to the target host and execute it in quiet mode.

    curl https://download.aporeto.com/apoctl/windows/apoctl.msi -o apoctl.msi; `
    if ($?) {. .\apoctl.msi /quiet}
    if ($?) {$env:PATH+="C:\Program Files\Apoctl;"}
    
  12. Use the following command to install the enforcer.

    apoctl enforcer install windows --auth-mode cloud `
                                    --namespace $($env:TARGET_NS) `
                                    --api $($env:MICROSEG_API) `
                                    --repo https://repo.aporeto.com/windows/prisma-enforcer.msi
    

    TIP

    Refer to Enforcer configuration options if you wish to modify the enforcer’s default settings. You can also run apoctl enforcer install windows -h to review its flags. You can find more information about the enforcer install windows command in the apoctl reference page.

  13. Open the Network Security section of the Prisma Cloud web interface, select Agent under Manage, and navigate to the enforcer’s namespace. You should find your enforcer listed with a status of connected. Click the enforcer and review its metadata.

  14. Select App Dependency Map in the side navigation menu. You should see your host as a processing unit, with a dashed green line to a Somewhere external network. Your host is in discovery mode.

  15. Return to your Remote Desktop session.

  16. Uninstall apoctl, remove the apoctl.msi file, and remove the .apoctl directory.

    Start-Process msiexec.exe -ArgumentList '/x apoctl.msi /quiet' -Wait ; `
    if($?) {rm 'apoctl.msi'} ; `
    if($?) {rm '.apoctl' -r -fo}
    
  17. Refer to Securing host communications to learn how to allow the desired traffic and disable discovery mode.

On-premise install

  1. Make sure you meet the following prerequisites.

    Entity Requirement
    Target host(s) Meets the system requirements
    Set up to synchronize time with authoritative sources
    curl installed
    ■ Can connect to the Microsegmentation Console API without TLS interception
    ■ Can connect to *.aporeto.com, *.prismacloud.io, and *.network.prismacloud.io
    Local host apoctl installed
    Privileges namespace.administrator privileges in the Microsegmentation namespace of the target host
    ■ Administrator access to the target host
  2. From your local host, generate a short-lived Microsegmentation token that the enforcer can exchange for an app credential. You can set a variety of restrictions on this token. If you’re in a hurry, just copy and paste the minimally restricted example below. The other tabs illustrate optional additional restrictions, such as requiring the enforcer to register in a specified namespace or make its request from a specific subnet.

    • macOS/Linux local host
      apoctl auth appcred --path ~/.apoctl/default.creds \
                          --restrict-role @auth:role=enforcer \
                          --restrict-role @auth:role=enforcer-installer \
                          --validity 60m
      
      apoctl auth appcred --path ~/.apoctl/default.creds \
                          --restrict-role @auth:role=enforcer \
                          --restrict-role @auth:role=enforcer-installer \
                          --validity 60m \
                          --restrict-namespace /803920923337065472/aws-dev-826088932159/vm1 \
                          --restrict-network 10.0.0.0/8 
      
      apoctl auth appcred --path <app-credential-file> \
                          --restrict-role @auth:role=enforcer \
                                          @auth:role=enforcer-installer \
                          --validity <golang-duration> \
                          [--restrict-namespace <namespace>] \
                          [--restrict-network <cidr>]
      
    • Windows local host
      apoctl auth appcred --path '.apoctl/default.creds' `
                          --restrict-role @auth:role=enforcer `
                          --restrict-role @auth:role=enforcer-installer `
                          --validity 60m
      
      apoctl auth appcred --path '.apoctl/default.creds' `
                          --restrict-role @auth:role=enforcer `
                          --restrict-role @auth:role=enforcer-installer `
                          --validity 60m `
                          --restrict-namespace /803920923337065472/aws-dev-826088932159/vm1 `
                          --restrict-network 10.0.0.0/8 
      
      apoctl auth appcred --path <app-credential-file> `
                          --restrict-role @auth:role=enforcer `
                                          @auth:role=enforcer-installer `
                          --validity <golang-duration> `
                          [--restrict-namespace <namespace>] `
                          [--restrict-network <cidr>]
      
  3. Retrieve the URL of your Microsegmentation Console API.

    echo $MICROSEG_API
    
    echo $Env:MICROSEG_API
    

  4. Access the target host, such as via Microsoft Remote Desktop.

  5. Set a TOKEN environment variable containing the token you just generated. We’ve truncated the example token value below for readability.

    $env:TOKEN="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWFsbSI6IkNlcnRpZmljYXRlIiwiZGF0YSI6eyJjb21tb25O...."
    
  6. Set a MICROSEG_API environment variable containing the URL of your Microsegmentation Console API. You can copy and paste this value from your local host terminal where you just echoed it.

    $env:MICROSEG_API="https://api.app0.network.prismacloud.io"
    
  7. Confirm that the host can connect to the Microsegmentation Console API and trusts its certificate.

    Invoke-WebRequest -URI $($env:MICROSEG_API)
    
  8. Set a TARGET_NS environment variable containing the Microsegmentation namespace of this enforcer. It should be a grandchild namespace.

    $env:TARGET_NS="/803920923337065472/aws-dev-826088932159/vm1"
    
  9. Download the apoctl MSI to the target host and execute it in quiet mode.

    curl https://download.aporeto.com/apoctl/windows/apoctl.msi -o apoctl.msi; `
    if ($?) {. .\apoctl.msi /quiet}
    if ($?) {$env:PATH+="C:\Program Files\Apoctl;"}
    
  10. Use the following command to install the enforcer.

    apoctl enforcer install windows --token $($env:TOKEN) `
                                    --auth-mode appcred `
                                    --namespace $($env:TARGET_NS) `
                                    --api $($env:MICROSEG_API) `
                                    --repo https://repo.aporeto.com/windows/prisma-enforcer.msi
    

    TIP

    Refer to Enforcer configuration options if you wish to modify the enforcer’s default settings. You can also run apoctl enforcer install windows -h to review its flags. You can find more information about the enforcer install windows command in the apoctl reference page.

  11. Open the Network Security section of the Prisma Cloud web interface, select Agent under Manage, and navigate to the enforcer’s namespace. You should find your enforcer listed with a status of connected. Click the enforcer and review its metadata.

  12. Select App Dependency Map in the side navigation menu. You should see your host as a processing unit, with a dashed green line to a Somewhere external network. Your host is in discovery mode.

  13. Return to your Remote Desktop session.

  14. Uninstall apoctl, remove the apoctl.msi file, remove the .apoctl directory, and clear the TOKEN variable.

    Start-Process msiexec.exe -ArgumentList '/x apoctl.msi /quiet' -Wait ; `
    if($?) {rm 'apoctl.msi'} `
    if($?) {$env:TOKEN=""} ; `
    if($?) {rm '.apoctl' -r -fo}
    
  15. Refer to Securing host communications to learn how to allow the desired traffic and disable discovery mode.

Enforcer configuration options

The enforcer exposes the following configuration options at startup. To modify the configuration of a running enforcer, you must restart it. To modify the enforcer’s tags, you have to also delete the enforcer object from the Microsegmentation Console.

You can modify the default configuration by passing the flags with apoctl enforcer install linux as the value of --raw-flags. Example: apoctl enforcer install linux --raw-flags "--log-level=debug --log-format=human --log-to-console=true"

enforcer flag Description
--activate-control-plane-pus Pass this flag if you wish to recognize the Microsegmentation Console as a processing unit, allowing its communications to be monitored and controlled. By default, the enforcer ignores them.
--api The URL of the Microsegmentation Console API.
--api-cacert Path to CA certificate.
--api-skip-verify Disables check on certificate signature as trusted.
--appcreds Path to application credentials.
--application-proxy-port Start of the port range for ports used by the enforcer application proxy. Defaults to 20992. You may adjust this if you experience conflicts.
--cloud-probe-timeout The enforcer can determine if it is running in a cloud environment, such as AWS, GCP, or Azure. This is the maximum amount of time to wait for these internal probes to complete. Defaults to two seconds: 2s
--disable-dns-proxy Pass this flag to disable the enforcer DNS proxy, which allows policies to be written based on FQDN, in cases where an exact IP address may be unpredictable.
--dns-server-address DNS server address or CIDR that is observed by the enforcer DNS proxy. Defaults to 0.0.0.0/0.
--enable-ebpf (Beta) Pass this flag to gain performance improvements by using extended Berkeley Packet Filter (eBPF) on systems that support it.
--enable-ipv6 (Beta) The enforcer ignores IPv6 communications by default. If you have IPv6 enabled and wish to monitor and control these connections, pass this flag.
--log-level Quantity of logs that the enforcer should generate. Defaults to info. Alternatively, you can set it to debug, trace, or warn.
--log-to-console Controls whether the enforcer’s logs are written to stdout. Boolean that defaults to false.
--namespace The Microsegmentation namespace the enforcer should register in.
--tag Microsegmentation tag for this enforcer
--token Microsegmentation token for the enforcer to use to register to the Microsegmentation Console.
--working-dir A persistent working directory with write, read, and execute permissions. Files such as logs are stored here. Defaults to %PROGRAMDATA%\enforcerd