Configuring F5 Access Guard

Overview of the F5 Access Guard Configuration

Overview of the configuration steps for F5 Access Guard deployment

1. Install the certificate bundle on the BIG-IP.
2. Push the service to Windows or macOS endpoints.
3. Install certificates on the endpoints.
4. Configure the service with an XML configuration file (also pushed to endpoints). This file specifies the servers, keyfile and certificate, and the system checks that the browser extension will pass to the server. Refer to the Configuration Schema and example configuration files for Windows or macOS.
5. Install the browser extension on Firefox or Chrome, either manually or automatically.
6. Test the configuration. The recommended method to test the configuration is to create a simple configuration with Access Guided Configuration, and check that the client can access a server through the specified checks.
7. Troubleshoot the configuration, if any problems occur.

Creating and installing the certificate bundle on the BIG-IP system

To create and install the certificate bundle, you should have generated and have access to the root and intermediate certificate.

1. In the BIG-IP admin UI, click System > Certificate Management > Traffic Certificate Management.

2. Click Import and from the Import Type list, select Certificate.

3. Type the Certificate Name.

4. Select Paste Text from the Certificate Source section and a text area will appear.

5. Copy the intermediate CA PEM certificate and paste it in the text area.

6. Copy the root CA PEM and paste it on the next line after the intermediate CA PEM’s trailer.

7. Click Import.

Install the F5 Access Guard service

Install the service

The F5 Access Guard ISO installer is available in your account on downloads.f5.com. Download the zipped installer and extract the files. The installer includes two files:

• F5AccessGuardService.msi - The Windows installer for the F5 Access Guard service.
• F5AccessGuardService.pkg - The macOS installer for F5 Access Guard.

Install the F5AccessGuardService.msi on Windows or F5AccessGuardService.pkg on macOS.

Note: The software check library must be installed separately to use any software checks. To install the library automatically, specify the <Update> <Software> URL in the XML configuration file. See the Update Oesis Inspectors section for more details.

Note for macOS clients

To check the version of the F5AccessGuardService:

    pkgutil --file-info /Library/F5Networks/F5AccessGuardService/F5AccessGuardService
    volume: /
    path: ./Library/F5Networks/F5AccessGuardService/F5AccessGuardService

    pkgid: com.f5.accessguard
    pkg-version: 1.0.0.0
    install-time: 1556945003
    uid: 0
    gid: 0
    mode: 755

F5AccessGuardService, F5AccessGuardNativeMessaging and OesisInstaller provide --version command-line option:

    /Library/F5Networks/F5AccessGuardService/F5AccessGuardService --version
    /Library/F5Networks/F5AccessGuardService/F5AccessGuardNativeMessaging --version
    /Library/F5Networks/F5AccessGuardService/OesisInstaller --version

    F5AccessGuardService 1.0.0.0
    F5AccessGuardNativeMessaging 1.0.0.0
    OesisInstaller 1.0.0.0

To uninstall F5AccessGuardService:

sudo /Library/F5Networks/F5AccessGuardService/F5AccessGuardServiceUninstall.sh

Install certificates

Install certificates

Important: Certificates created for use with the F5 Zero Trust Identity Aware Proxy must include the Secure Mail or Secure Email (S/MIME) field as a certificate purpose.

• Create the certificates using your desired certificate generator. You must create and deploy unique certificates to each endpoint. You can generate the certificates with ActiveDirectory, OpenSSL, or another tool.
• It is not recommended that keys be stored in plain text on the client devices.
• The CA certificates used to sign the client certificates must be imported to APM.

Windows

• It is recommended that you deploy the certificate/key pair to CAPI on Windows clients.
• On Windows, the import location of the certificate/key pair can be configured using the F5AccessGuardServiceConfig.xml.
• If the certificate/key pair is to be imported to the F5AccessGuardService store, you must install the F5AccessGuardService first.

macOS

• We recommend that you deploy the certificate/key pair to the System Keychain on macOS clients.
• Import the certificate/key pair to System.keychain (the /Library/Keychains/System.keychainfile).
• Before deploying the certificate/key pair to the System keychain, the F5AccessGuardService must be installed.
• The F5AccessGuardService daemon requires explicit allow permissions to the key in System.keychain because the System keychain is locked. Because the F5AccessGuardService is running as a daemon, there are no user interface prompts to unlock the keychain. If you do not allow access to the application, signing for system health data will fail without any notifications.

Allow access to F5AccessGuardService while importing the .pfx/.p12 file to the System keychain

sudo security import <_path to .p12/.pfx file_> -P <_.p12/.pfx file password_> -f pkcs12 -T /Library/F5Networks/F5AccessGuardService/F5AccessGuardService -k /Library/Keychains/System.keychain

Note: This command imports the .p12/.pfx file to the /Library/Keychains/System.keychain and allows permission to /Library/F5Networks/F5AccessGuardService/F5AccessGuardService to access it. For this to be effective, the service must be installed first.

Allow access to the F5AccessGuardService binary using the Keychain Access app

1. Open the Keychain Access app and highlight the System keychain. Select the Certificates category.
2. Expand the keychain item for the certificate that was imported. Upon expanding, you will see the key associated with the certificate.
3. Double click on the key item and on the info window, select the Access Control tab.
4. Click the plus symbol (+) and navigate to /Library/F5Networks/F5AccessGuardService, then select F5AccessGuardService.

If F5 Access Guard was previously installed, then the key’s ACL may already contain the F5AccessGuardService entry. This existing entry must be explicitly removed by selecting it and clicking the minus (-) symbol. Access will then be allowed as listed in the task above.

After updating or changing the F5AccessGuardService binary (through auto-update or other means), access to the new /Library/F5Networks/F5AccessGuardService/F5AccessGuardService binary must be explicitly allowed for the imported keychain item. Otherwise, the service can not unlock the keychain. Because the service is running as a daemon, no UI is shown and the certificate signing will fail silently.

To avoid this, you can either delete the old identity keychain item and import a new one using the security commandline utility or you can update the existing keychain item to allow access to the F5AccessGuardService binary using the Keychain Access app.

Restart the F5AccessGuardService daemon needs after this to use the updated identity. To restart the daemon, use the launchctl command-line utility.

Configure the service

You configure the service with an XML configuration file. Use the following reference to create and configure the file.

Important: The XML configuration file is not created automatically, and must be manually created. Any modifications to the file will be automatically loaded by the service.

Configuration File Schema Elements

This table lists the XML tags, values, descriptions, and default values.

Configure software checks

Use the software attribute type to specify the types of software on the client for which information will be collected and presented to the server for continuous client checks.

Note: You need only specify the type of data to collect, not the specific software packages.

Configure file checks

Use the hash attribute to calculate the hash of the file. By default, no hash is calculated.

Supported hash algorithms

• md5
• sha256
• sha384
• sha512

Update Oesis inspectors

Oesis inspectors can be automatically updated on BIG-IP 14.1 or newer.

To configure automatic updates add the following to the service configuraton file:

  <Update>
    <Software>https://my.server.org/public/download/</Software>
  </Update>

Replace my.server.org with the address of your BIG-IP APM virtual server.

Hosting the Oesis inspectors update on external server

1. Update the client configuration with the proper URI:

   Copy

   <?xml version="1.0" encoding="utf-8"?>
   <SystemHealthConfig>
     <Version>1.0</Version>
     <Update>
       <Software>https://some.server.com/location/</Software>
     </Update>
     ...

2. Upload the following files from BIG-IP to your https server:

   Copy

   public/download/OesisInspector.cab
   public/download/OesisInspector.cab.ver
   public/download/mac_oesisInspector.tar.ver
   public/download/mac_oesisInspector.tar.md5
   public/download/mac_oesisInspector.tar

   You have to repeat this step with each update to these files.

Certificate store types for Windows

Use the store attribute type to specify the certificate store location.

Configuration file schema

This topic gives an example of a configuration file schema.

<xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="SystemHealthConfig">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="Version">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="1.0"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="LogLevel" minOccurs="0" maxOccurs="1">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:enumeration value="trace"/>
              <xs:enumeration value="info"/>
              <xs:enumeration value="warning"/>
              <xs:enumeration value="error"/>
              <xs:enumeration value="critical"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="Update" minOccurs="0" maxOccurs="1">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:anyURI" name="Software"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Signing">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="CAPI" minOccurs="0" maxOccurs="1">
                <xs:complexType>
                  <xs:sequence>
                    <xs:choice minOccurs="1" maxOccurs="2">
                      <xs:element type="xs:string" name="Subject"/>
                      <xs:element type="xs:string" name="Issuer"/>
                    </xs:choice>
                    <xs:element name="Store">
                      <xs:complexType>
                        <xs:simpleContent>
                          <xs:extension base="xs:string">
                            <xs:attribute name="type">
                              <xs:simpleType>
                                <xs:restriction base="xs:string">
                                  <xs:enumeration value="system"/>
                                  <xs:enumeration value="service"/>
                                </xs:restriction>
                              </xs:simpleType>
                            </xs:attribute>
                          </xs:extension>
                        </xs:simpleContent>
                      </xs:complexType>
                    </xs:element>
                  </xs:sequence>
                </xs:complexType>
              </xs:element>
              <xs:element type="xs:string" name="CertFile" minOccurs="0" maxOccurs="1"/>
              <xs:element type="xs:string" name="KeyFile" minOccurs="0" maxOccurs="1"/>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Config">
          <xs:complexType>
            <xs:sequence>
              <xs:element type="xs:string" name="Servers"/>
              <xs:element name="CheckInterval">
                <xs:simpleType>
                  <xs:restriction base="xs:integer">
                    <xs:minInclusive value="0"/>
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
              <xs:element name="SignInterval">
                <xs:simpleType>
                  <xs:restriction base="xs:integer">
                    <xs:minInclusive value="0"/>
                  </xs:restriction>
                </xs:simpleType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
        <xs:element name="Checks">
          <xs:complexType>
            <xs:sequence>
              <xs:element name="Software" minOccurs="0" maxOccurs="15">
                <xs:complexType>
                  <xs:attribute name="type">
                    <xs:simpleType>
                      <xs:restriction base="xs:string">
                        <xs:enumeration value="av"/>
                        <xs:enumeration value="fw"/>
                        <xs:enumeration value="hd"/>
                        <xs:enumeration value="pm"/>
                        <xs:enumeration value="ha"/>
                        <xs:enumeration value="p2p"/>
                      </xs:restriction>
                    </xs:simpleType>
                  </xs:attribute>
                </xs:complexType>
              </xs:element>
              <xs:element name="Process" minOccurs="0" maxOccurs="15">
                <xs:complexType>
                  <xs:attribute name="name" type="xs:string" />
                </xs:complexType>
              </xs:element>
              <xs:element name="File" minOccurs="0" maxOccurs="15">
                <xs:complexType>
                  <xs:attribute name="name" type="xs:string" />
                  <xs:attribute name="hash">
                    <xs:simpleType>
                      <xs:restriction base="xs:string">
                        <xs:enumeration value="md5"/>
                        <xs:enumeration value="sha256"/>
                        <xs:enumeration value="sha384"/>
                        <xs:enumeration value="sha512"/>
                      </xs:restriction>
                    </xs:simpleType>
                  </xs:attribute>
                </xs:complexType>
              </xs:element>
            </xs:sequence>
          </xs:complexType>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

Configuration file example for macOS

This topic gives an example of a configuration file for macOS.

<?xml version="1.0" encoding="utf-8"?>
 <SystemHealthConfig>
 <Version>1.0</Version>
 <Update>
 	<Software>https://your.server.org/public/download</Software>
 </Update>
 <Signing>
    <CAPI>
        <Subject>*.f5.com</Subject>
        <Issuer>CA Intermediate *</Issuer>
    </CAPI>
 </Signing>
 <Config>
 	<Servers>*://server.example.com/*,*://*.domain.com/*</Servers>
	<CheckInterval>3600</CheckInterval>
	<SignInterval>1800</SignInterval>
 </Config>
 <Checks>
 	<Software type="av"/>
 	<Software type="fw"/>
 	<File name="/usr/bin/python" hash="sha256"/>
 	<Process name="Terminal"/>
 </Checks>
 </SystemHealthConfig>

Configuration file example for Windows

This topic gives an example of a configuration file for Windows.

<?xml version="1.0" encoding="utf-8"?>
 <SystemHealthConfig>
 <Version>1.0</Version>
 <Update>
 	<Software>https://your.server.org/public/download</Software>
 </Update>
 <Signing>
    <CAPI>
        <Subject>*.f5.com</Subject>
        <Issuer>CA Intermediate *</Issuer>
        <Store type="system">AccessGuard</Store>
    </CAPI>
 </Signing>
 <Config>
 	<Servers>*://server.example.com/*,*://*.domain.com/*</Servers>
	<CheckInterval>3600</CheckInterval>
	<SignInterval>1800</SignInterval>
 </Config>
 <Checks>
 	<Software type="av"/>
 	<Software type="fw"/>
 	<File name="C:\file.txt" hash="md5"/>
 	<File name="C:\file2.txt" hash="sha512"/>
 	<Process name="cmd.exe"/>
 </Checks>
 </SystemHealthConfig>   
       

Install the browser extension

A browser extension is required. This browser extension is available for Firefox and Chrome browsers. The extension obtains the posture results via Native Messaging for the browser from the F5 Access Guard Native Messaging app. See Chrome native messaging and Firefox native messaging information for more details.

Manual installation for Chrome

1. In the Chrome browser, browse to https://chrome.google.com/webstore/detail/f5-access-guard/kdgpgkeanjobofhdmhgnpeknppelfain.
2. Click Add to Chrome.

Manual installation for Firefox

1. In the Firefox browser, browse to https://addons.mozilla.org/en-US/firefox/addon/f5-access-guard/.
2. Click Add to Firefox.

Automatic installation for Chrome

Use the instructions provided by Google to Automatically install apps and extensions.

Automatic installation for Firefox

Uses the instructions provided by Mozilla for Deploying Firefox with extensions.

Create and test a configuration

Using Access Guided Configuration, create a test configuration.

As a prerequisite, you should have configured clients using the information in this document. You must also have a server to which you can test access, and the IP address to that server.

Creating a test configuration

1. On the BIG-IP system, go to Access > Guided Configuration.

2. Click Zero Trust.

3. Click Identity Aware Proxy.

4. Click Next.

5. Type a Configuration Name.

6. Select the Enable F5 Posture Check box.

7. For the CA Trust Certificate, select the CA bundle you uploaded to the BIG-IP previously.

8. In the Posture Settings area, click Add.

9. In the Name box, type a name for the posture check.

10. In the Platforms area, select the browsers you want to support for Windows and macOS, and select the checks you want to run. Note that these checks should be the same checks that you specified to send from the browsers in the Configuration file. See Configure the service for more information.

11. Click Done, then click Save & Next.

12. Specify the virtual server Destination Address.

13. Click Save & Next.

14. Specify the Authentication Properties, based on your configuration.

15. Click Save, then click Save & Next.

16. Enable and configure Multi-factor authentication, if required, then click Save & Next.

17. Enable and configure Single Sign-On, if required, then click Save & Next.

18. To add an Application, configure the name, FQDN, and Pool Configuration for the application.

19. To add subpaths, health monitors, change the load balancing method, or add pool members, click Show Advanced Setting.

20. Click Save, then click Save & Next.

21. To add one or more application groups, click Enable Application Groups, then configure the application groups.

22. Click Save & Next.

23. On the Contextual Access Properties screen, configure the Resource Type (Application or Application Group), the Resource, the Posture to use, and the Primary Authentication method.

24. If you want to enable step-up authentication based on triggers such as the HTTP method, geographic location, or IP reputation, click Enable Step Up Authentication, and configure the settings.

25. Click Save, then click Save & Next.

26. Configure Customization messages, if required.

27. Click Save & Next.

28. Click Deploy to deploy the Zero Trust Identity Aware Proxy configuration.

To test the configuration, attempt to make a connection from a client machine you have configured to the server or application you specified.

Troubleshoot the configuration

Troubleshooting

• The system time on the BIG-IP and on the client must be in sync. If the system time on the client is ahead by ~5 minutes, any access policies will fail.

• There may be a delay when a configuration file is created or changed for the configuration to take effect. To enforce the configuration immediately, you can restart the service.

• Specify LogLevel in the configuration file to get more or less verbose logging. Possible values: trace, info, warning, error and critical; trace is the most verbose (mostly for troubleshooting) and critical is the least.

  Specify trace to get the browser extension logs in the native messaging host logs.

  The default level is info.

• Examine logs on the client, generated by the service and the native messaging host. If the native messaging host logs are missing, make sure the browser is launching it properly.

  On Windows, the service logs are located at:

  Copy

  %WINDIR%/temp/F5AccessGuardService.log

  On macOS, the service logs are located at:

  Copy

  /Library/Logs/F5Networks/F5AccessGuardService.log

  On Windows, the native messaging host logs are located at:

  Copy

  %TEMP%\F5AccessGuardNativeMessaging.log where %TEMP% is user temp folder.

  On macOS, the native messaging host logs are located at:

  Copy

  ~/Library/Logs/F5Networks/F5AccessGuardNativeMessaging.log

  Note: The log files may have numbers appended for rotation purposes.

• For Chrome troubleshooting, see https://developer.chrome.com/apps/nativeMessaging#native-messaging-debugging. For Firefox troubleshooting see https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging#Troubleshooting.

• The client injects special HTTP headers in web requests made to URLs that match the pattern specified in <Servers>. To view the data sent via the HTTP header, enable trace logging and view the service log file. The data can also be viewed in the F5 Access Guard browser extension’s console in Chrome or Firefox. The data logged in the extension’s console is without the CMS header and trailer.

Base64 encoded CMS signed data

-----BEGIN CMS-----
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
-----END CMS-----

To check the contents of the above base64 encoded data, copy the data into a file and use the following command:

openssl asn1parse -in <file path> -inform pem

To verify the signature of the signed data against the cert bundle with intermediate CA and root CA, run the following commands:

cat intermediate.crt root.crt > bundle.pem
openssl cms -verify -in <file path> -out signeddata.txt -inform PEM -CAfile bundle.pem
cat signeddata.txt

signeddata.txt will include the plain text data that was signed.