4.1. Managing Forward Proxy Authentication

4.1.1. What it is

To enable and enforce authentication for user access to external resources, SSL Orchestrator integrates with the F5 Access Policy Manager (APM) module to provide seamless and robust access controls. The explicit and transparent forward proxy topologies allow you to simply attach a corresponding APM access policy to enable.

As stated throughout this guide, security devices are opaque to the surrounding environment. This is an especially important consideration for authentication, as an inline HTTP proxy service, for example, might require user identity information. As a protected service, users cannot (and should not) directly authenticate to an inline security device. Therefore, to provide user identity information to this service, authentication must be performed at the SSL Orchestrator topology and a “delegate” token passed to the inline security device. Configuration of delegate token authentication offload is covered later in this chapter.

Finally, no conversation about forward proxy authentication would be complete without talking about NTLM and Kerberos as the primary mechanisms used to authenticate outbound traffic. These protocols are often referred to as “transparent”, as within the proper environment, the browser user agent will handle the authentication challenge and response on the user’s behalf, thus the user does not see it.

In this module, we will cover five different topics in the following order:

  • Explicit forward proxy authentication
  • Transparent forward proxy authentication (captive portal)
  • Delegate token authentication offload
  • Forward proxy authentication with NTLM
  • Forward proxy authentication with Kerberos

4.1.2. How to build it: Explicit forward proxy authentication

Explicit forward proxy (web) authentication employs a “407-based” mechanism, whereby the explicit proxy prompts the client for identity using an HTTP 407 challenge-response. Modern browsers support “Windows Integrated” protocols, including Basic, NTLM, and Kerberos for 407-based authentication (so explicit proxy is also limited to these). The configuration steps below will use a local database authentication method to simplify and focus on the mechanics of the SSL Orchestrator integration. Follow these steps to get a better understanding of those mechanics, then jump to the NTLM and Kerberos sections as required. Enabling explicit proxy authentication in SSL Orchestrator includes the following steps:

Optionally create the Local DB instance and any Local DB user accounts to authenticate users for testing, but other identity management services may also be defined. Please see relevant APM documentation for the specific configuration steps needed for other authentication methods.

Create an SWG-Explicit access policy - explicit proxy authentication is defined as an access policy of type SWG-Explicit.


Access Profile User Input
Explicit Proxy
Name Provide a unique name.
Profile Type Select SWG-Explicit.
Profile Scope Select Profile.
User Identification Method Select IP Address.
Language Select the preferred language.
Visual Policy Editor

This policy will typically contain an HTTP 407 Response agent, as well as some form of authentication, which could be HTTP Basic, NTLM or Kerberos. The following shows a very simple Basic authentication policy to APM LocalDB. Complete the access policy creation. In the list of access profiles, click the Edit link for the just-created policy to open the Visual Policy Editor. Create a policy similar to the graphic below.

  • HTTP 407 Response agent
    • Properties
      • Basic Auth Realm: enter some string
      • HTTP Auth Level: Basic
    • Branch Rules
      • Remove the Negotiate branch
  • LocalDB Auth
    • LocalDB Instance: select a LocalDB instance
../_images/image36.png

Figure 36: 407-based auth policy

Click the Apply Access Policy link in the top left corner to deploy this access policy.


Create or edit an Explicit Proxy SSL Orchestrator topology and attach the SWG-Explicit access policy - to attach the SWG-Explicit access policy to SSL Orchestrator, create or edit an Explicit proxy SSL Orchestrator topology. On the Interception Rules page from within the SSL Orchestrator UI, for your new or existing topology, select this policy under the Access Profile option.

To test the above Basic authentication configuration, use one of the following techniques:

  • Open a browser and configure its proxy settings to point to the SSL Orchestrator explicit proxy topology IP address and port. Depending on the method of authentication configured in the SWG-Explicit access profile, an authentication prompt may be visible (Basic) or “transparent” (NTLM/Kerberos).


  • If command-line cURL is available, cuRL to an external resource. For cURL, include the explicit proxy address and client credentials. View the cURL help for more information on presenting user authentication at the command line. The following example shows how to present Basic authentication:

curl - -proxy 10.1.10.150:3128 - -proxy-basic - -proxy-user ‘bob:pass’ https://www.example.com

4.1.3. How to build it: Transparent forward proxy authentication (Captive Portal)

In a traditional transparent forward proxy, the client/user is unaware of the proxys existence. Client traffic is routed through the proxy. To authenticate users accessing the Internet through a transparent proxy, there are generally two options:

  • Direct - where the proxy inserts integrated authentication challenged (i.e. NTLM/Kerberos/Basic) directly in the path of outbound traffic. This implies that clients would get challenged for local authentication when going to remote Internet sites which are typically disabled by default in most browsers and would need to be enabled. While a few proxies support this authentication mode, it is not terribly practical or secure.


  • Captive Portal - where the proxy redirects new user sessions to a separate authentication site. The authentication site provides the necessary authentication challenge, then redirects the user back through the proxy. A session is then tracked by virtue of some unique client attribute. Though they may not call it captive portal, all mainstream proxy products support captive portal authentication and is the primary mode for authentication in transparent proxy scenarios. Captive portal authentication also has a distinct advantage over explicit proxy authentication in that it supports more than just integrated authentication (i.e. NTLM/Kerberos/Basic). A captive portal can, for example, support login pages, client certificate, and federated authentication.


Note: It is also worth noting that any transparent proxy authentication mechanism requires cleartext access to the user traffic. The users first request to the Internet must be over HTTP, if not decrypting, so that the proxy can insert the direct challenge or HTTP redirect to a captive portal. SSL Orchestrator generally solves this problem as a function of automatically decrypting outbound flows.

Transparent proxy captive portal authentication essentially flows like this:

  • A new client opens a browser and attempts to connect to a remote Internet site (ex. “www.google.com”). We will call this the “Origin URL”.


  • The transparent proxy detects no session for this client, so it inserts an HTTP redirect to its captive portal authentication service. Since this is a separate site, the redirect must convey some information about the client, specifically the origin URL. This is provided in the query string of the redirect.


  • The client accesses the captive portal, does some form of authentication, and is then redirected back to the origin URL.


  • The client makes a second request to the origin URL through the transparent proxy and is permitted.


The configuration steps below will use a local database authentication method to simplify and focus on the mechanics of the SSL Orchestrator integration. Follow these steps to get a better understanding of those mechanics, then follow the NTLM and Kerberos sections as required. The configuration of transparent proxy captive portal authentication requires two separate per-session access profiles  one attached to the SSL Orchestrator transparent proxy configuration, and one attached to a separate virtual server configured to support the authentication process. The following describes a minimal configuration using an APM LocalDB user account and login page. As stated previously, this can also support integrated NTLM/Kerberos/Basic authentication, login pages, client certificates and federation, and can rely on Active Directory, LDAP, and other identity management services through APM.

Optionally, create the Local DB instance and any Local DB user accounts to authenticate users for testing, but other identity management services may also be defined. Please see relevant APM documentation for the specific configuration steps needed for other authentication methods.

Create an SWG-Transparent access profile. This profile will be attached to the separate captive portal “login” virtual server.


SWG-Transparent Access Profile User Input
Profile Type Select SWG-Transparent.
Profile Scope SSL Orchestrator introduces a new profile scope (Named) for captive portal authentication that must match between it and the SWG-Transparent access profile. Select Named.
Named Scope Enter a unique name here to represent the “authentication domain” shared between the two access profiles. For this lab, use something like “SSLO”.
Customization Type For captive portal this must be set to “Standard”.
Captive Portal Leave this as disabled. It is only enabled in the SSL Orchestrator access profile.
Language Select the desired language.
Visual Policy Editor

Complete the access profile creation. In the list of access profiles, click the Edit link for the just-created policy to open the Visual Policy Editor. Create a policy similar to the graphic below.

../_images/image37.png

Figure 37: Captive portal auth policy


Create a new SSL Orchestrator access profile. Captive portal authentication requires a separate access profile configuration not created directly within the SSL Orchestrator workflow.


SSL Orchestrator Access Profile User Input
Profile Type Select SSL Orchestrator.
Profile Scope SSL Orchestrator introduces a new profile scope (Named) for captive portal authentication that must match between it and the SWG-Transparent access profile. Select Named .
Named Scope Enter the same name you used in the SWG-Transparent profile so this setting matches across both profiles.
Customization Type For captive portal this must be set to “Standard”.
Captive Portal Set this to enabled.
Primary Authentication URI This is the URL that the SSL Orchestrator transparent proxy will redirect new users to, represented by and resolving to the separate virtual server instance and SWG-Transparent access profile. This would be a full URL, example: https://login.f5labs.com
Language Select the desired language.
Note: An SSL Orchestrator access profile does not have an editable visual policy.

Create a client SSL profile. This will be needed by the captive portal login virtual server to handle incoming HTTPS communications. It should match the login URL defined in the Primary Authentication URI setting.

Create a virtual server. This virtual server will define the captive portal login instance that handles user authentication. Transparent proxy traffic will be redirected to this virtual server (so also ensure that the Captive Portal URL specified in the SSL Orchestrator access profile resolves to this virtual server’s IP address). The following minimal settings for this virtual server are below:


Authentication Virtual Server User Input
Type Select Standard.
Destination Address/Mask Enter an IP address accessible to the client. This is the IP address that the specified Primary Authentication URI should DNS resolve to.
Service Port Enter a port accessible to the client (ex 443).
HTTP Profile (Client) The default http profile is adequate here.
SSL Profile (Client) Select the previously created client SSL profile.
VLANs and Tunnel Traffic Select the client facing VLAN here.
Access Profile Select the SWG-Transparent access profile here.

Attach the new SSL Orchestrator access profile to the transparent proxy topology. In the SSL Orchestrator UI, click on the relevant transparent forward proxy topology or create a new one. On the Interception Rule page, under Access Profile, select the new SSL Orchestrator access profile. Complete the topology workflow and (re)deploy.

Test the captive portal. On attempting to access an Internet site, a new user should be redirected to the login page defined in the SWG-Transparent access profile. Once authenticated, the user will be redirected back to the proxy and gain access to the origin URL content.

../_images/image38.png

Figure 38: Captive portal logon page


Note that when selecting a new access profile, a banner warning will be displayed above, stating, “If Access Profile is not topology specific the user cannot change the Log Settings in a topology deployment flow”. As log settings are now topology specific, SSL Orchestrator applies the selected options on the Log Settings page to the built-in SSL Orchestrator access profile only. When a different access profile is selected, the Log Settings options are disabled for editing. To re-acquire logging for the SSLO topology, create a new logging profile under Access –> Overview –> Event Logs –> Settings:


Access Logging Profile User Input
General Enable both options (as required).
Access System Logs Select the /Common/sys-sslo-publisher and select desired logging settings for each object.
URL Request Logs Select the /Common/sys-sslo-publisher and minimally enable “Blocked” and “Confirmed” events (as required).
Access Profiles Select the new SSL Orchestrator access profile. The SWG-Transparent access profile can also be selected (as required).


4.1.4. How to build it: Delegate token authentication offload

Delegate token authentication is the method for offloading authentication onto the F5 Access Policy Manager (APM) for forward proxy traffic and passing authenticated user information to an inline security device via an alternate “token”. As security devices in the SSL Orchestrator service chain are opaque to the outside world, authentication directly to the inline security device is prohibited. Delegate authentication allows the SSL Orchestrator to provide all of the necessary user identity information to the inline device in an X-Authenticated-User HTTP header and is simple to configure.

Attach an APM access profile to the respective SSL Orchestrator topology as described in the previous sections.

Enable the Authentication Offload option in an Inline HTTP service configuration.

../_images/image39.png

Figure 39: Authentication Offload

With this option enabled, the authenticated user logon name will be passed to the inline HTTP service in the X-Authenticated-User HTTP header (and removed on the other side of the security device).



4.1.5. How to build it: Forward proxy authentication with NTLM

NTLM authentication is a challenge-response authentication mechanism that enables a client to cryptographically prove knowledge of its account password. While not an exhaustive treatise on the NTLM protocol, the flow basically looks similar to the following:

  • NTLM relies on knowledge of passwords. And yet, passwords are never stored. Instead, hashes are created to represent those passwords. When talking about ciphers used and cryptographic strength of NTLM, it usually has to do with the manner in which encrypted hashes are created so that they are unique and “collision proof”.


  • When a client wants to access a server, it must first send its username to the server.


  • The server then generates a random number (called a “challenge”) and sends that to the client.


  • The client then encrypts this challenge with the hash of its password and returns that to the server. This is the “response”.


  • The server sends the username, the challenge sent to the client, and the client’s response to a domain controller.


  • The domain controller retrieves a copy of the client’s password hash from its database and uses this to encrypt the challenge. It then compares the encrypted challenge to the response from the client. If they’re the same, it proves the client knows its password, thus authentication is successful.

It is important to note here, in comparison to Kerberos, that NTLM requires the server to verify the clients authenticity, which generally places additional load on both the server and the domain controller. NTLM is also less flexible in the types of ciphers that it can employ. That said, NTLM authentication, at least for clients and servers in a Windows domain, is typically much simpler to configure and support than Kerberos. It can also be simpler for some non-Windows clients (i.e. Mac, Linux) to support. To begin the NTLM configuration, follow these steps as needed:


NTLM Authentication User Input
Satisfy licensing prerequisites In order to perform authentication for forward proxy in SSL Orchestrator, the F5 Access Policy manager (APM) feature must be licensed for the required access session count.
Satisfy F5 BIG-IP prerequisites

In order to process NTLM tokens, the F5 BIG-IP must have the following prerequisite settings:

  • Ensure DNS settings point to the domain DNS server(s). Ensure that the F5 BIG-IP can resolve both the domain controller name as well as the domain name itself.


  • Ensure all parties are synchronized based on time. Configure system NTP settings to point to a domain controller or other reliable time source. This can also be done quickly from the command line while testing. However, it is advisable to configure NTP settings (permanently) via the UI or TMSH.

/etc/init.d/ntpd stop

ntpdate <IP of domain controller> /etc/init.d/ntpd start

Satisfy domain prerequisites

Configure the following on the domain controller:

  • Minimally create DNS A records for the explicit proxy or captive portal URL. While it is not completely necessary, clients should use a fully qualified name to access an explicit proxy or captive portal authentication URL in order to perform NTLM authentication.
Satisfy client prerequisites

Configure the following on the client machines:

  • Clients should be joined to the domain in order to participate in NTLM authentication. If the user is not logged in as a domain user on a domain-joined workstation, at best authentication to the proxy will result in a popup dialog to enter credentials. To enable transparent authentication, ensure that the user is logged in under a domain account on a domain-joined machine.


  • For NTLM (and Kerberos) authentication, modern browsers require that you specify the URLs that require integrated authentication, to prevent credential attacks.


    • Internet Explorer must be configured to “trust” the proxy for authentication. Add the URL to IE’s Local Intranet Sites list. On a Microsoft Windows host, IE security settings will generally apply to the Chrome browser as well.


    • For Firefox, type about:config in the address bar, click the accept risk button, then modify the network. negotiate-auth. trusted-uris key to include the proxy URL.


Create an APM NTLM Machine Account. In the APM UI, under Access –> Authentication –> NTLM –> Machine Account, click the Create button to create a new NTLM machine account.


NTLM Machine Account User Input
Machine Account Name Enter a locally significant name for the NTLM Machine Account.
Domain FQDN This is the fully qualified name of the domain. Ensure that DNS is configured correctly and that the F5 BIG-IP can resolve this domain name.
Domain Controller FQDN (Optional) – This is the fully qualified name of a domain controller.
Admin User/Password Enter the name and password of a domain administrator with rights to add machines to the domain.

Assuming this succeeds, verify the existence of the new machine account in the domain. If it does not succeed, check DNS and time settings.

Create an APM NTLM Auth configuration. In the APM UI, under Access –> Authentication –> NTLM –> NTLM Auth Configuration, click the Create button to create a new NTLM Auth Configuration.


NTLM Auth Configuration User Input
Machine Account Name Enter a locally significant name for the NTLM Auth Configuration.
Domain Controller FQDN List This is a list of domain controllers that can be used to process NTLM requests.

Create an SWG-Explicit or SWG-Transparent access profile as appropriate. In the APM UI, under Access –> Profiles / Policies –> Access Profiles (Per-Session Policies), click Create to create an access profile.


Access Profile User Input
Explicit Proxy
Name Provide a unique name.
Profile Type Select SWG-Explicit.
Profile Scope Select Profile.
User Identification Method Select Credentials.
NTLM Auth Configuration Select the previously created NTLM Auth Configuration.
Language Select the preferred language.
Visual Policy Editor

Complete the access profile creation. In the list of access profiles, click the Edit link for the just-created policy to open the Visual Policy Editor. Create a policy similar to the graphic below.

../_images/image40.png

Figure 40: NTLM Auth

Click the Apply Access Policy link in the top left corner to deploy this access policy.


Transparent Proxy (Captive Portal)
Name Provide a unique name.
Profile Type Select SWG-Transparent.
Profile Scope Select Named.
Named Scope Enter the same name you used in the SSL Orchestrator profile so this setting matches across both profiles.
User Identification Method Select Credentials.
NTLM Auth Configuration Select the previously created NTLM Auth Configuration.
Language Select the preferred language.
Visual Policy Editor
../_images/image40.png

Figure 41: NTLM Auth

Click the Apply Access Policy link in the top left corner to deploy this access policy.


Attach the access profile to an SSL Orchestrator topology configuration as described in the previous sections.

Test authenticate outbound access through the SSL Orchestrator forward proxy topology from a domain-joined machine, logged in as a domain user.



Troubleshooting

While this document cannot go into great detail on troubleshooting, there are a few options for dealing with NLTM authentication issues:

NTLM Troubleshooting User Input
Review

Review the following support article for additional information on NTLM troubleshooting:

https://support.f5.com/csp/article/K08915521

Ensure time sync Make sure that all parties, client, domain controller, and BIG-IP have the same time. NTLM is sensitive to time differences, so proper time is critical.
Create a debug logging publisher

A debug log publisher attached to the access policy will provide granular insight into the stages of authentication and any potential issues.

  • Under System -> Logs -> Configuration -> Log Publishers, click Create.

    • Name: arbitrary name
    • Destinations: local-syslog

  • Under Access -> Overview -> Event Logs -> Settings

    • General
      • Name: arbitrary name
      • Enable Access System Logs: checked
      • Enable URL Request Logs: checked
    • Access System Logs
      • Publisher: syslog debug publisher
      • Access Policy: debug
      • ECA: debug
    • URL Request Logs
      • Publisher: syslog debug publisher
      • Log Allowed Events: checked
      • Log Blocked Events: checked
      • Log Confirmed Events: checked
    • Access Profiles
      • Select desired access profile
  • Under Access -> Profiles / Policies, click on access policy, go to the Logs tab and replace current selected log with the debug publisher.

Remember to remove this debug log publisher from the access policy when done.

Restart services between testing

Should you need to make configuration changes, it is useful to restart services between tests:

  • Type the following from the BIG-IP command line:
bigstart restart nlad eca
General logging

Much of the above is geared to get you to this point: the ability to produce rich and informative logs. NTLM error messages are generally quite informative.

  • APM Debug Logging - With the debug syslog publisher in place, the F5 BIG-IP APM log will produce an enormous number of logs, including everything that happens inside the NTLM authentication policy. The volume of these authentication logs can be overwhelming, so its often useful to trim down what you are looking for. The following command will show just the specific Kerberos events:
tail -f / var/log/apm | grep -iE ‘ntlm|ntlmssp|negotiate’
  • Wireshark - Wireshark is also a fantastic tool for displaying and decoding NTLM traffic. The easiest way to get a packet capture into Wireshark is to first generate a tcpdump from the BIG-IP console:
tcpdump -lnnvvvi [VLAN] -s0 -w [file.pcap]

where [VLAN] will be the client-facing VLAN on the F5 BIG-IP, and [file.pcap] is the name of the file to export the capture to. In a forward proxy scenario, NTLM will be present inside the HTTP and Connect requests to the proxy. Once captured, copy the capture file to the machine running Wireshark and import to Wireshark. For ease of visibility, you can modify the display filter to only show NTLM traffic (which will be inside HTTP/Connect requests):

ntlm (or could be ‘ntlmssp’ depending on version)

If packets are visible with this filter applied, dive down into the packet payload to view the decoded NTLM data.

  • Tshark - If Wireshark is not an option, the command line tshark utility is also extremely useful. It too can filter on and decode NTLM data (but directly from the BIG-IP command line):
tshark -i [VLAN] -Y ‘ntlm’ -nVXs0

where -i [VLAN] is the client-facing VLAN on the F5 BIG-IP, -Y ‘ntlm’ is the display filter, and -nVXs0 is the set of options to make the output verbose. Again, ultimately you are looking here to verify that the client does indeed engage in an NTLM challenge-response.

Granular client-side testing

Command-line cURL is a great tool for testing explicit proxy communications. Depending on how it is compiled, it may also have NTLM authentication capabilities. Minimally, using cURL in this scenario will verify that SSL Orchestrator is configured correctly to process explicit or transparent proxy requests and that the access profile is correctly presenting an authentication challenge to the client.

Explicit proxy:

curl - -proxy 10.1.10.150:3128 - -proxy-ntlm - -proxy-user ‘bob:pass’ https://www.example.com
Verify Windows security patches

BIG-IP 15.0 introduced a new version of the nlad daemon. This might cause NTLMv2 authentication to fail if the domain controller does not have the most current security patches. See the following for additional information on this change:

https://cdn.f5.com/product/bugtracker/ID760141.html



4.1.6. How to build it: Forward proxy authentication with Kerberos

Kerberos is a cryptographic “ticketing” protocol. Meaning, access is granted to resources by virtue of encrypted tickets issued by a “key distribution center” (KDC - normally a domain controller). While not an exhaustive treatise on the Kerberos protocol, the flow basically looks like this:

  • The KDC is effectively both an authentication server and a database. In its database, it stores a copy of an encryption key it shares with every entity (principal) in the domain (realm). A principal is generally a user, host or service. A single host can contain many services, and thus, many individual principals and a unique cryptographic key for each.


  • A Kerberos client (normally a domain-joined user or machine) will request authentication to a KDC. This is the authentication service process, shortened to AS_REQ and AS_REP (for request and response). The method by which the client authenticates to the KDC is not important except that, upon successful authentication, the client is presented with a Ticket Granting Ticket (TGT). The TGT is a long-lasting cryptographic ticket that the client can use to request additional resources from the KDC.


  • At some point, the client may need access to some domain resource. To do that, it now generates a Ticket Granting Service request (TGS_REQ and TGS_REP) to the KDC. Armed with its TGT, the client makes a request for a service resource by name, its service principal name (SPN). The KDC then creates a ticket for that service, encrypts that ticket with the target principals key, and then encrypts again with the client’s key and then passes that back to the client.


  • The client uses its copy of its shared key to decrypt the outer layer. The remaining encrypted blob is then passed to the server in the application service request (AP_REQ and AP_REP). Assuming the service principal possesses the correct key to decrypt the new outer layer, it gains access to the ticket inside that provides all of the information it needs to satisfy the client’s request. In some cases, the KDC may include additional information in the ticket, including nonce and timestamps (to prevent replay), and privilege access control (PAC) data that could include permissions granted to the client.


The most important aspects of Kerberos, in comparison to NTLM, are that Kerberos never specifically requires a password (AS_REQ can use many different forms of authentication), and the service principal rarely, if ever, communicate with the KDC. In addition, Kerberos generally supports much stronger cryptography options than NTLM. In a forward proxy authentication scenario, the client will be presented with a 401 (transparent proxy) or 407 (explicit proxy) response if not authenticated. The client will then request access to the resource by principal name by calling the KDC (TGS_REQ) and then pass that ticket pack to the proxy in a subsequent request.

Follow these steps to configure Kerberos environment prerequisites:


Kerberos Prerequisites User Input
Satisfy licensing prerequisites In order to perform authentication for forward proxy in SSL Orchestrator, the F5 Access Policy Manager (APM) feature must be licensed for the required access session count.
Satisfy F5 BIG-IP prerequisites

In order to process Kerberos tickets, the F5 BIG-IP and all parties must be synchronized based on time. Configure system NTP settings to point to a domain controller or other reliable time source. This can also be done quickly from the command line while testing. However, it is advisable to configure NTP settings (permanently) via the UI or TMSH.

/etc/init.d/ntpd stop

ntpdate <IP of domain controller> /etc/init.d/ntpd start

Satisfy domain prerequisites Create DNS A (forward) and PTR (reverse) records for the fully qualified proxy hostname. Clients must use a fully qualified name in order to request a Kerberos ticket to that service principal. It will be easiest if the proxy’s fully qualified name includes the correct AD realm name as part of its name (ex. proxy.f5demo.local).
Step Create an AD user account to be used with APM Kerberos AAA. This AD account represents the proxy service’s Service Principal Name (SPN) and will hold the service’s Kerberos encryption key (ex. proxy).
Step

Issue the ktpass command from a domain computer to set the account’s service principal name and to export a keytab file. The keytab fie contains the principal’s encryption key that the Kerberos APM AAA profile will use to decrypt and validate service tickets. All of the following must be typed on one line but are broken out here for clarity:

ktpass

-princ [spn]@[REALM]

-mapuser [domain user short name]

-ptype KRB5_NT_PRINCIPAL

-crypto all

-pass ‘[user’s password]’

-out [file to output]

  • The spn is the service principal name and denoted by the service type (usually “HTTP/”) followed by the principal name. For example, assuming the proxy URL is proxy.f5demo.local, the service principal name for the proxy service would be HTTP/proxy.f5demo.local. The realm portion must be all uppercase. So, if the domain is f5demo.local, the full service principal name to enter here would be HTTP/ proxy.f5demo.local@F5DEMO. LOCAL.


  • The mapuser option represents the domain user short name. In this example it would be “F5DEMOproxy”.


  • The ptype option indicates the principal type. In this case it is a principal, so the type is KRB5_NT_PRINCIPAL.


  • The crypto option can take a multitude of options:

    • DES-CBC-CRC - used for legacy compatibility
    • DES-CBC-MD5 - also used for legacy compatibility
    • RC4-HMAC-NT - uses 128-bit encryption, but considered legacy
    • AES256-SHA1 - employs AES256-CTS-HMAC-SHA1-96 modern cryptography
    • AES128-SHA1 - employs AES128-CTS-HMAC-SHA1-96 modern cryptography
    • ALL - represents all of the above ciphers

  • The pass option is used to enter the mapped user’s password and should be encapsulated in single quotes (ex. -pass ‘password’).


  • The out option is the path and file name to export the resulting keytab file.

As an example:

ktpass -princ HTTP/proxy.f5demo.local@ F5DEMO.LOCAL -mapuser F5DEMOproxy -crypto rc4-hmac-nt -ptype KRB5_NT_PRINCIPAL -pass ‘password’ -out c:file.keytab

Note that rc4-hmac-nt should work on Windows 2016 and below AD environments unless alternate Kerberos cryptography preferences are configured. Consult additional documentation for specific crypto requirements as required.

Satisfy client prerequisites

Configure the following on the clients:

  • Users and desktop computers must be joined to the domain in order to participate in Kerberos authentication and users must be logged into client desktops using domain credentials.


  • For Kerberos authentication, modern browsers require that you specify the URLs that require integrated authentication to prevent credential attacks.


  • Internet Explorer must be configured to “trust” the proxy for authentication. Add the URL to IE’s Local Intranet Sites list. On a Microsoft Windows host, IE security settings will generally apply to the Chrome browser as well.


  • For Firefox, type about:config in the address bar, click the accept risk button, then modify the network.negotiate-auth. trusted-uris key to include the proxy URL.


Create an APM Kerberos AAA configuration. The AAA configuration holds the exported keytab and is ultimately responsible for decrypting and validating service tickets. In the APM UI, under Access -> Authentication -> Kerberos, click the Create button to create a new Kerberos AAA configuration.


Kerberos AAA Configuration User Input
SPN Format Select Kerberos 5 NT Principal.
Service Principal Name This is the full Service Principal Name (SPN) format of the proxy URL that the client will request a ticket for. (ex. HTTP/proxy.f5demo.local @F5DEMO.LOCAL).
Upload the exported keytab file from the ktpass command.

Create an SWG-Explicit or SWG-Transparent access profile as appropriate. The access policy is the primary “per-session” component of authentication. In the APM UI, under Access –> Profiles / Policies –> Access Profiles (Per-Session Policies), click the Create button to create a new SWG-Explicit access profile.


Access Profile User Input
Explicit Proxy
Name Provide a unique name.
Profile Type Select SWG-Explicit.
Profile Scope Select Profile.
User Identification Method Select IP Address.
Language Select the preferred language.
Visual Policy Editor

Complete the access profile creation. In the list of access profiles, click the Edit link for the just-created policy to open the Visual Policy Editor. Create a policy similar to the graphic below.

../_images/image42.png

Figure 42: 407 Auth

For the HTTP 407 Response agent, it may be optimal to remove options for Basic authentication. Set the HTTP Auth Level on the Properties tab to negotiate.

../_images/image43.png

Figure 43: HTTP 407 Response agent

On the Branch Rules tab, remove all but the negotiate branch.

../_images/image44.png

Figure 44: HTTP 407 Response branch rule

For the Variable Assignment agent, create a new session variable called session.server.network .name and assign it the proxy server name (as Text).

../_images/image45.png
../_images/image46.png

Figure 45/46: Variable Assignment agent

And for the Kerberos Auth agent, select the configured APM Kerberos AAA profile and ensure that Request Based Auth is disabled.

../_images/image47.png

Figure 47: Kerberos Auth agent

Click the Apply Access Policy link in the top left corner to deploy this access policy.

Transparent Proxy (Captive Portal)
Name Provide a unique name.
Profile Type Select SWG- Transparent.
Profile Scope Select Named.
Named Scope Enter the same name you used in the SSL Orchestrator profile so this setting matches across both profiles.
User Identification Method Select IP Address.
Language Select the preferred language.
Visual Policy Editor

Complete the access profile creation. In the list of access profiles, click the Edit link for the just-created policy to open the Visual Policy Editor. Create a policy similar to the graphic below.

../_images/image48.png

Figure 48: 401 Auth

For the HTTP 401 Response agent, it may be optimal to remove options for Basic authentication. Set the HTTP Auth Level on the Properties tab to negotiate.

../_images/image49.png

Figure 49: HTTP 401 Response branch rule

On the Branch Rules tab, remove all but the negotiate branch.

../_images/image44.png

Figure 50: HTTP 401 Response branch rule

For the Variable Assignment agent, create a new session variable called session.server. network.name and assign it the proxy server name (as Text).

../_images/image45.png
../_images/image46.png

Figure 51/52: Variable Assignment agent

And for the Kerberos Auth agent, select the configured APM Kerberos AAA profile and ensure that Request Based Auth is disabled.

../_images/image47.png

Figure 53: Kerberos Auth agent

Click the Apply Access Policy link in the top left corner to deploy this access policy.


Attach the access profile to an SSL Orchestrator topology configuration as described in the previous sections. Test authenticated outbound access through the SSL Orchestrator forward proxy topology from a domain-joined machine, logged in as a domain user.



Troubleshooting Kerberos Authentication

While this document cannot cover all aspects of Kerberos authentication troubleshooting, there are a few options for dealing with Kerberos authentication issues.


Kerberos Troubleshooting User Input
Review

Review the following support article for additional information on Kerberos troubleshooting:

https://support.f5.com/csp/article/K24065228

Ensure time sync Make sure that all parties, client, KDC, and BIG-IP have the same time. Kerberos tickets contain timestamps to prevent replay attacks, so the proper time is critical.
Create a debug logging publisher

A debug log publisher attached to the access policy will provide granular insight into the stages of authentication and any potential issues.

  • Under System -> Logs -> Configuration -> Log Publishers, click Create.

    • Name: arbitrary name
    • Destinations: local-syslog

  • Under Access -> Overview -> Event Logs -> Settings:

    • General
      • Name: arbitrary name
      • Enable Access System Logs: checked
      • Enable URL Request Logs: checked
    • Access System Logs
      • Publisher: syslog debug publisher
      • Access Policy: debug
    • URL Request Logs
      • Publisher: syslog debug publisher
      • Log Allowed Events: checked
      • Log Blocked Events: checked
      • Log Confirmed Events: checked
    • Access Profiles
      • Select desired access profile

  • Under Access -> Profiles / Policies, click on access policy, go to the Logs tab, and replace currently selected log with the debug publisher.

Remember to remove this debug log publisher from the access policy when done.

Clear caches between testing

Should you need to make configuration changes, it is important to clear authentication caches between tests.

  • On the client workstation, clear the collected Kerberos tickets:
klist purge
  • On the F5 BIG-IP, clear the active access sessions. In the UI, under Access –> Overview –> Active Sessions, select and delete any existing sessions.
  • Making changes to APM Kerberos AAA will also benefit from restarting the ‘rba’ service:
bigstart restart rba
Check for duplicate SPNs

A duplicate SPN means two entities (host or service) have the same principal name. As previously stated, the KDC is basically a database of encryption keys. If a client requests a ticket for a service, and the service principal name is shared by more than one entity, the resulting ticket may be encrypted with the wrong key. Modern Windows AD provides a command line utility to test for duplicate SPNs:

setspn -X [service-principal-name]
Check for correct version number

As Kerberos encryption keys get updated, the KDC will keep track of these changes with a key version number. It is therefore possible that a keytab that was extracted earlier may, at some point, differ from the “current” version of the key. This can be verified by examining both key version numbers.

  • In the BIG-IP UI, under Access -> Authentication -> Kerberos, click on the respective AAA configuration. Take noted of the KVNO value associated with the keys.
../_images/image54.png

Figure 54: Kerberos AAA Configuration

  • It is also possible to show the key version number directly from the keytab file. This can be performed from the F5 BIG-IP command line or may be possible on a Windows machine.

    klist -ekKt [file.keytab]

  • On a domain computer, issue the following ldifde command to export the account settings for the service (including its key version number). The entire command must be on one line but is broken out here for clarity.

    ldifde


    -f c:dump.txt


    -l dn,sAMAccountName,msds-keyversionnumber, serviceprincipalname,userprincipalname


    -p subtree


    -r “(serviceprincipalname=[HTTP/spn])”


    Note the [HTTP/spn] portion. Change this to the service principal name you are looking for (ex. HTTP/proxy.f5demo.local).


    It may also be necessary, in some environments to include a port:


    -t 3268

    If the service is found, it will export a text file. Open that text file to view the key version number.

    ../_images/image55.png

    Figure 55: LDIFDE Output

    The key number in the keytab, as visible in the APM Kerberos AAA profile, must match the version number from the ldifde export. If it does not, it will be necessary to export a new keytab.

General logging

Much of the above is geared to get you to this point: the ability to produce rich and informative logs. Kerberos has been around for a long time, and the error messages produced are often well-known and easy to fix. Here are a few tools you can use to generate useful Kerberos logs:

  • APM Debug Logging - With the debug syslog publisher in place, the F5 BIG-IP APM log will produce an enormous number of logs, including everything that happens inside the Kerberos authentication policy. The volume of these authentication logs can be overwhelming, so its often useful to trim down what you are looking for. The following command will show just the specific Kerberos events:
tail -f / var/log/apm | grep -iE ‘kerberos|negotiate|gss-api’

APM logs will generate industry-standard error messages for Kerberos failures.

  • Wireshark - Wireshark is also a fantastic tool for displaying and decoding Kerberos traffic. The easiest way to get a packet capture into Wireshark is to first generate a tcpdump from the BIG-IP console:
tcpdump -lnnvvvi [VLAN] -s0 -w [file.pcap]

where [VLAN] will be the client-facing VLAN on the F5 BIG-IP, and [file.pcap] is the name of the file to export the capture to. In a forward proxy scenario, Kerberos will be present inside the HTTP and Connect requests to the proxy. Once captured, copy the capture file to the machine running Wireshark and import to Wireshark. For ease of visibility, you can modify the display filter to only show Kerberos traffic (which will be inside HTTP/Connect requests):

kerberos

If packets are visible with this filter applied, dive down into the packet payload to view the decoded Kerberos ticket. In a forward proxy scenario, this will be an HTTP or Connect request with Kerberos ticket for the proxy service principal name (ex. HTTP/proxy.f5demo.local). Ultimately you are looking here to verify that the client does indeed pass a Kerberos ticket to the proxy, and that the SPN inside the ticket matches the SPN in the APM Kerberos AAA keytab.

  • Tshark - If Wireshark is not an option, the command line tshark utility is also extremely useful. It, too, can filter on and decode Kerberos tickets (but directly from the BIG-IP command line):
tshark -i [VLAN] -Y ‘kerberos’ -nVXs0

where -i [VLAN] is the client-facing VLAN on the F5 BIG-IP, -Y ‘kerberos’ is the display filter, and -nVXs0 is the set of options to make the output verbose. Again, ultimately you are looking here to verify that the client does indeed pass a Kerberos ticket to the proxy, and that the SPN inside the ticket matches the SPN in the APM Kerberos AAA keytab.

Granular client-side testing

When a domain-joined client makes a request for a Kerberos-protected resource, it has to handle keys. Specifically, the client minimally needs a Ticket Granting Ticket (TGT) which is gets from the KDC upon authenticating to the domain, and it needs a ticket for the target service. TGTs are generally long-lasting, so the client only needs to request this once every few hours. A service ticket will generally last for a few minutes. In either case, the client needs to store those tickets in a Kerberos cache to be able to re-use them. That cache can be viewed:

klist

This is an important utility, as it minimally shows if the client is able to fetch Kerberos tickets from the KDC. If a problem arises in the authentication process, one of the first steps should be to determine that the client is indeed getting a service ticket and that the ticket is for the correct service principal name.



Additional Kerberos Considerations

The following are procedures for additional (optional) use cases not mentioned above.

  • Merging keytab files

A keytab file will normally contain keys for a single service principal but can technically contain keys for multiple. The primary use case here might be to support multiple services from a single keytab. For example, different users (maybe regions of users) may access a single proxy interface but request service tickets from different KDCs. Having one keytab with all the necessary encryption keys allows the F5 BIG-IP to handle Kerberos authentication from multiple domains (realms) on a single proxy interface. The easiest way to merge keytab files is with the ktutil command. This can be performed directly from the F5 BIG-IP command line, a Windows machine, or any Linux host with the proper Kerberos tools.

ktutil

ktutil: rkt /path/to/file1.keytab

ktutil: rkt /path/to/file2.keytab

ktutil: rkt /path/to/file3.keytab

ktutil: wkt /path/to/new.keytab

ktutil: q

The above reads in multiple keytab files (rkt), writes to a new one (wkt), and then quits (q). Import this new keytab to the APM Kerberos AAA as previously documented.


  • Generating a keytab on a non-AD machine

There may be situations where it is not possible to generate a keytab from a domain-joined machine (for example, when domain administration is performed elsewhere and/or you do not have the rights on the domain to perform these actions). Minimally, someone must create a service account and provide it the correct service principal name (servicePrincipalName) attribute in the correct SPN-format:

where “fqdn-of-server” is the hostname of the proxy service in this case, and REALM is the fully qualified domain name in all uppercase. You must also know the password to this account to generate the keytab. Once you have all of this, you can create the keytab directly from the F5 BIG-IP command line or any Linux system with the proper Kerberos tools. One additional note: from Microsoft Windows 2008 and beyond, the way passwords are “salted” in the Active Directory has changed and is not generally supported by Linux-based Kerberos tools. This prohibits the Linux-created keytabs from supporting modern AES ciphers. RC4-HMAC, however, does not use a salt, so it is still a viable option for APM Kerberos authentication. When using this technique, also ensure that the domain account does not have the following set (checked):

  • This account supports Kerberos AES128 bit encryption
  • This account supports Kerberos AES256 bit encryption

You will also need access to the current key version number. This can be found by running the ldifde command as detailed earlier in the troubleshooting section. Armed with the account password, key version number, and service principal nam, to create a keytab from the BIG-IP command line, you can again rely on the trusty ktutil command:

ktutil

ktutil: addent -password -p HTTP/proxy.f5demo.local@F5DEMO.LOCAL -k 2 -e arcfour-hmac

Password for HTTP/proxy.f5demo.local@F5DEMO.LOCAL:

ktutil: wkt new.keytab

ktutil: q

where:

  • addent means “add entry”
  • -password means you will be providing the password
  • -p HTTP/proxy.f5demo.local@F5DEMO.LOCAL is the service principal name
  • -k 2 is the key version number
  • -e arcfour-hmac is the cipher

The above example only creates an RC4-HMAC key, as AES ciphers are not supported by this method and older DES keys are weak. This process will then create a keytab that can be copied off of the BIG-IP and imported into an APM Kerberos AAA configuration.