Leverage F5 BIG-IP APM and Azure AD Conditional Access Easy button
Integrating F5 BIG-IP APM’s Identity Aware Proxy (IAP) with Microsoft EntraID (Previously called AzureAD) Conditional Access enables fine-grained, adaptable, zero trust access to any application, regardless of location and authentication method, with continuous monitoring and verification.
APM-DHCP Access Policy Example and Detailed Instructions
Prepared with Mark Quevedo, F5 Principal Software Engineer May, 2020 Sectional Navigation links Important Version Notes || Installation Guide || What Is Going On Here? || Parameters You Set In Your APM Access Policy || Results of DHCP Request You Use in Access Policy || Compatibility Tips and Troubleshooting Introduction Ordinarily you assign an IP address to the “inside end” of an APM Network Tunnel (full VPN connection) from an address Lease Pool, from a static list, or from an LDAP or RADIUS attribute. However, you may wish to assign an IP address you get from a DHCP server. Perhaps the DHCP server manages all available client addresses. Perhaps it handles dynamic DNS for named client workstations. Or perhaps the DHCP server assigns certain users specific IP addresses (for security filtering). Your DHCP server may even assign client DNS settings as well as IP addresses. APM lacks DHCP address assignment support (though f5's old Firepass VPN had it ). We will use f5 iRules to enable DHCP with APM. We will send data from APM session variables to the DHCP server so it can issue the “right” IP address to each VPN tunnel based on user identity, client info, etc. Important Version Notes Version v4c includes important improvements and bug fixes. If you are using an older version, you should upgrade. Just import the template with “Overwrite existing templates” checked, then “reconfigure” your APM-DHCP Application Service—you can simply click “Finished” without changing any options to update the iRules in place. Installation Guide First install the APM-DHCP iApp template (file DHCP_for_APM.tmpl). Create a new Application Service as shown (choose any name you wish). Use the iApp to manage the APM-DHCP virtual servers you need. (The iApp will also install necessary iRules.) You must define at least one APM-DHCP virtual server to receive and send DHCP packets. Usually an APM-DHCP virtual server needs an IP address on the subnet on which you expect your DHCP server(s) to assign client addresses. You may define additional APM-DHCP virtual servers to request IP addresses on additional subnets from DHCP. However, if your DHCP server(s) support subnet-selection (see session.dhcp.subnet below) then you may only need a single APM-DHCP virtual server and it may use any IP that can talk to your DHCP server(s). It is best to give each APM-DHCP virtual server a unique IP address but you may use an BIG-IP Self IP as per SOL13896 . Ensure your APM and APM-DHCP virtual servers are in the same TMOS Traffic Group (if that is impossible set TMOS db key tmm.sessiondb.match_ha_unit to false). Ensure that your APM-DHCP virtual server(s) and DHCP server(s) or relay(s) are reachable via the same BIG-IP route domain. Specify in your IP addresses any non-zero route-domains you are using (e.g., “192.168.0.20%3”)—this is essential. (It is not mandatory to put your DHCP-related Access Policy Items into a Macro—but doing so makes the below screenshot less wide!) Into your APM Access Policy, following your Logon Page and AD Auth (or XYZ Auth) Items (etc.) but before any (Full/Advanced/simple) Resource Assign Item which assigns the Network Access Resource (VPN), insert both Machine Info and Windows Info Items. (The Windows Info Item will not bother non-Windows clients.) Next insert a Variable Assign Item and name it “DHCP Setup”. In your “DHCP Setup” Item, set any DHCP parameters (explained below) that you need as custom session variables. You must set session.dhcp.servers. You must also set session.dhcp.virtIP to the IP address of an APM-DHCP virtual server (either here or at some point before the “DHCP_Req” iRule Event Item). Finally, insert an iRule Event Item (name it “DHCP Req”) and set its Agent ID to DHCP_req. Give it a Branch Rule “Got IP” using the expression “expr {[mcget {session.dhcp.address}] ne ""}” as illustrated. You must attach iRule ir-apm-policy-dhcp to your APM virtual server (the virtual server to which your clients connect). Neither the Machine Info Item nor the Windows Info Item is mandatory. However, each gathers data which common DHCP servers want to see. By default DHCP_req will send that data, when available, to your DHCP servers. See below for advanced options: DHCP protocol settings, data sent to DHCP server(s), etc. Typically your requests will include a user identifier from session.dhcp.subscriber_ID and client (machine or connection) identifiers from other parameters. The client IP address assigned by DHCP will appear in session.dhcp.address. By default, the DHCP_req iRule Event handler will also copy that IP address into session.requested.clientip where the Network Access Resource will find it. You may override that behavior by setting session.dhcp.copy2var (see below). Any “vendor-specific information” supplied by the DHCP server 1 (keyed by the value of session.dhcp.vendor_class) will appear in variables session.dhcp.vinfo.N where N is a tag number (1-254). You may assign meanings to tag numbers. Any DNS parameters the DHCP server supplies 2 are in session.dhcp.dns_servers and session.dhcp.dns_suffix. If you want clients to use those DNS server(s) and/or DNS default search domain, put the name of every Network Access Resource your Access Policy may assign to the client into the session.dhcp.dns_na_list option. NB: this solution does not renew DHCP address leases automatically, but it does release IP addresses obtained from DHCP after APM access sessions terminate. 3 Please configure your DHCP server(s) for an address lease time longer than your APM Maximum Session Timeout. Do not configure APM-DHCP virtual servers in different BIG-IP route domains so they share any part of a DHCP client IP range (address lease pool). For example, do not use two different APM-DHCP virtual servers 10.1.5.2%6 and 10.1.5.2%8 with one DHCP client IP range 10.1.5.10—10.1.5.250. APM-DHCP won’t recognize when two VPN sessions in different route domains get the same client IP from a non-route-domain-aware DHCP server, so it may not release their IP’s in proper sequence. This solution releases DHCP address leases for terminated APM sessions every once in a while, when a new connection comes in to the APM virtual server (because the BIG IP only executes the relevant iRules on the “event” of each new connection). When traffic is sparse (say, in the middle of the night) there may be some delay in releasing addresses for dead sessions. If ever you think this solution isn’t working properly, be sure to check the BIG IP’s LTM log for warning and error messages. DHCP Setup (a Variable Assign Item) will look like: Put the IP of (one of) your APM-DHCP virtual server(s) in session.dhcp.virtIP. Your DHCP server list may contain addresses of DHCP servers or relays. You may list a directed broadcast address (e.g., “172.16.11.255”) instead of server addresses but that will generate extra network chatter. To log information about DHCP processing for the current APM session you may set variable session.dhcp.debug to true (don’t leave it enabled when not debugging). DHCP Req (an iRule Event Item) will look like: Note DHCP Req branch rules: If DHCP fails, you may wish to warn the user: (It is not mandatory to Deny access after DHCP failure—you may substitute another address into session.requested.clientip or let the Network Access Resource use a Lease Pool.) What is going on here? We may send out DHCP request packets easily enough using iRules’ SIDEBAND functions, but it is difficult to collect DHCP replies using SIDEBAND. 4 Instead, we must set up a distinct LTM virtual server to receive DHCP replies on UDP port 67 at a fixed address. We tell the DHCP server(s) we are a DHCP relay device so replies will come back to us directly (no broadcasting). 5 For a nice explanation of the DHCP request process see http://technet.microsoft.com/en-us/library/cc940466.aspx. At this time, we support only IPv4, though adding IPv6 would require only toil, not genius. By default, a DHCP server will assign a client IP on the subnet where the DHCP relay device (that is, your APM-DHCP virtual server) is homed. For example, if your APM-DHCP virtual server’s address were 172.30.4.2/22 the DHCP server would typically lease out a client IP on subnet 172.30.4.0. Moreover, the DHCP server will communicate directly with the relay-device IP so appropriate routes must exist and firewall rules must permit. If you expect to assign client IP’s to APM tunnel endpoints on multiple subnets you may need multiple APM-DHCP virtual servers (one per subnet). Alternatively, some but not all DHCP servers 6 support the rfc3011 “subnet selection” or rfc3527 “subnet/link-selection sub-option” so you can request a client IP on a specified subnet using a single APM-DHCP virtual server (relay device) IP which is not homed on the target subnet but which can communicate easily with the DHCP server(s): see parameter session.dhcp.subnet below. NOTE: The subnet(s) on which APM Network Access (VPN) tunnels are homed need not exist on any actual VLAN so long as routes to any such subnet(s) lead to your APM (BIG-IP) device. Suppose you wish to support 1000 simultaneous VPN connections and most of your corporate subnets are /24’s—but you don’t want to set up four subnets for VPN users. You could define a virtual subnet—say, 172.30.4.0/22—tell your DHCP server(s) to assign addresses from 172.30.4.3 thru 172.30.7.254 to clients, put an APM-DHCP virtual server on 172.30.4.2, and so long as your Layer-3 network knows that your APM BIG-IP is the gateway to 172.30.4.0/22, you’re golden. When an APM Access Policy wants an IP address from DHCP, it will first set some parameters into APM session variables (especially the IP address(es) of one or more DHCP server(s)) using a Variable Assign Item, then use an iRule Event Item to invoke iRule Agent DHCP_req in ir apm policy dhcp. DHCP_req will send DHCPDISCOVERY packets to the specified DHCP server(s). The DHCP server(s) will reply to those packets via the APM-DHCP virtual-server, to which iRule ir apm dhcp must be attached. That iRule will finish the 4-packet DHCP handshake to lease an IP address. DHCP_req handles timeouts/retransmissions and copies the client IP address assigned by the DHCP server into APM session variables for the Access Policy to use. We use the APM Session-ID as the DHCP transaction-ID XID and also (by default) in the value of chaddr to avert collisions and facilitate log tracing. Parameters You Set In Your APM Access Policy Required Parameters session.dhcp.virtIP IP address of an APM-DHCP virtual-server (on UDP port 67) with iRule ir-apm-dhcp. This IP must be reachable from your DHCP server(s). A DHCP server will usually assign a client IP on the same subnet as this IP, though you may be able to override that by setting session.dhcp.subnet. You may create APM-DHCP virtual servers on different subnets, then set session.dhcp.virtIP in your Access Policy (or branch) to any one of them as a way to request a client IP on a particular subnet. No default. Examples (“Custom Expression” format): expr {"172.16.10.245"} or expr {"192.0.2.7%15"} session.dhcp.servers A TCL list of one or more IP addresses for DHCP servers (or DHCP relays, such as a nearby IP router). When requesting a client IP address, DHCP packets will be sent to every server on this list. NB: IP broadcast addresses like 10.0.7.255 may be specified but it is better to list specific servers (or relays). Default: none. Examples (“Custom Expression” format): expr {[list "10.0.5.20" "10.0.7.20"]} or expr {[list "172.30.1.20%5"]} Optional Parameters (including some DHCP Options) NOTE: when you leave a parameter undefined or empty, a suitable value from the APM session environment may be substituted (see details below). The defaults produce good results in most cases. Unless otherwise noted, set parameters as Text values. To exclude a parameter entirely set its Text value to '' [two ASCII single-quotes] (equivalent to Custom Expression return {''} ). White-space and single-quotes are trimmed from the ends of parameter values, so '' indicates a nil value. It is best to put “Machine Info” and “Windows Info” Items into your Access Policy ahead of your iRule Event “DHCP_req” Item (Windows Info is not available for Mac clients beginning at version 15.1.5 as they are no longer considered safe). session.dhcp.debug Set to 1 or “true” to log DHCP-processing details for the current APM session. Default: false. session.dhcp.firepass Leave this undefined or empty (or set to “false”) to use APM defaults (better in nearly all cases). Set to “true” to activate “Firepass mode” which alters the default values of several other options to make DHCP messages from this Access Policy resemble messages from the old F5 Firepass product. session.dhcp.copy2var Leave this undefined or empty (the default) and the client IP address from DHCP will be copied into the Access Policy session variable session.requested.clientip, thereby setting the Network Access (VPN) tunnel’s inside IP address. To override the default, name another session variable here or set this to (Text) '' to avert copying the IP address to any variable. session.dhcp.dns_na_list To set the client's DNS server(s) and/or DNS default search domain from DHCP, put here a Custom Expression TCL list of the name(s) of the Network Access Resource(s) you may assign to the client session. Default: none. Example: expr {[list "/Common/NA" "/Common/alt-NA"]} session.dhcp.broadcast Set to “true” to set the DHCP broadcast flag (you almost certainly should not use this). session.dhcp.vendor_class Option 60 A short string (32 characters max) identifying your VPN server. Default: “f5 APM”. Based on this value the DHCP server may send data to session.dhcp.vinfo.N (see below). session.dhcp.user_class Option 77 A Custom Expression TCL list of strings by which the DHCP server may recognize the class of the client device (e.g., “kiosk”). Default: none (do not put '' here). Example: expr {[list "mobile" "tablet"]} session.dhcp.client_ID Option 61 A unique identifier for the remote client device. Microsoft Windows DHCP servers expect a representation of the MAC address of the client's primary NIC. If left undefined or empty the primary MAC address discovered by the Access Policy Machine Info Item (if any) will be used. If no value is set and no Machine Info is available then no client_ID will be sent and the DHCP server will distinguish clients by APM-assigned ephemeral addresses (in session.dhcp.hwcode). If you supply a client_ID value you may specify a special code, a MAC address, a binary string, or a text string. Set the special code “NONE” (or '') to avoid sending any client_ID, whether Machine Info is available or not. Set the special code “XIDMAC” to send a unique MAC address for each APM VPN session—that will satisfy DHCP servers desiring client_ID‘s while averting IP collisions due to conflicting Machine Info MAC’s like Apple Mac Pro’s sometimes provide. A value containing twelve hexadecimal digits, possibly separated by hyphens or colons into six groups of two or by periods into three groups of four, will be encoded as a MAC address. Values consisting only of hexadecimal digits, of any length other than twelve hexits, will be encoded as a binary string. A value which contains chars other than [0-9A-Fa-f] and doesn't seem to be a MAC address will be encoded as a text string. You may enclose a text string in ASCII single-quotes (') to avert interpretation as hex/binary (the quotes are not part of the text value). On the wire, MAC-addresses and text-strings will be prefixed by type codes 0x01 and 0x00 respectively; if you specify a binary string (in hex format) you must include any needed codes. Default: client MAC from Machine Info, otherwise none. Example (Text value): “08-00-2b-2e-d8-5e”. session.dhcp.hostname Option 12 A hostname for the client. If left undefined or empty, the short computer name discovered by the APM Access Policy Windows Info Item (if any) will be used. session.dhcp.subscriber_ID Sub-option 6 of Option 82 An identifier for the VPN user. If undefined or empty, the value of APM session variable session.logon.last.username will be used (generally the user's UID or SAMAccountName). session.dhcp.circuit_ID Sub-option 1 of Option 82 An identifier for the “circuit” or network endpoint to which client connected. If left undefined or empty, the IP address of the (current) APM virtual server will be used. session.dhcp.remote_ID Sub-option 2 of Option 82 An identifier for the client's end of the connection. If left undefined or empty, the client’s IP address + port will be used. session.dhcp.subnet Option 118 Sub-option 5 of Option 82 The address (e.g., 172.16.99.0) of the IP subnet on which you desire a client address. With this option you may home session.dhcp.virtIP on another (more convenient) subnet. MS Windows Server 2016 added support for this but some other DHCP servers still lack support. Default: none. session.dhcp.hwcode Controls content of BOOTP htype, hlen, and chaddr fields. If left undefined or empty, a per-session value optimal in most situations will be used (asserting that chaddr, a copy of XID, identifies a “serial line”). If your DHCP server will not accept the default, you may set this to “MAC” and chaddr will be a locally-administered Ethernet MAC (embedding XID). When neither of those work you may force any value you wish by concatenating hexadecimal digits setting the value of htype (2 hexits) and chaddr (a string of 0–32 hexits). E.g., a 6-octet Ethernet address resembles “01400c2925ea88”. Most useful in the last case is the MAC address of session.dhcp.virtIP (i.e., a specific BIG-IP MAC) since broken DHCP servers may send Layer 2 packets directly to that address. Results of DHCP Request For Use In Access Policy session.dhcp.address <-- client IP address assigned by DHCP! session.dhcp.message session.dhcp.server, session.dhcp.relay session.dhcp.expires, session.dhcp.issued session.dhcp.lease, session.dhcp.rebind, session.dhcp.renew session.dhcp.vinfo.N session.dhcp.dns_servers, session.dhcp.dns_suffix session.dhcp.xid, session.dhcp.hex_client_id, session.dhcp.hwx If a DHCP request succeeds the client IP address appears in session.dhcp.address. If that is empty look in session.dhcp.message for an error message. The IP address of the DHCP server which issued (or refused) the client IP is in session.dhcp.server (if session.dhcp.relay differs then DHCP messages were relayed). Lease expiration time is in session.dhcp.expires. Variables session.dhcp.{lease, rebind, renew} indicate the duration of the address lease, plus the rebind and renew times, in seconds relative to the clock value in session.dhcp.issued (issued time). See session.dhcp.vinfo.N where N is tag number for Option 43 vendor-specific information. If the DHCP server sends client DNS server(s) and/or default search domain, those appear in session.dhcp.dns_servers and/or session.dhcp.dns_suffix. To assist in log analysis and debugging, session.dhcp.xid contains the XID code used in the DHCP request. The client_ID value (if any) sent to the DHCP server(s) is in session.dhcp.hex_client_id. The DHCP request’s htype and chaddr values (in hex) are concatenated in session.dhcp.hwx. Compatibility Tips and Troubleshooting Concern Response My custom parameter seems to be ignored. You should set most custom parameters as Text values (they may morph to Custom Expressions). My users with Apple Mac Pro’s sometimes get no DHCP IP or a conflicting one. A few Apple laptops sometimes give the Machine Info Item bogus MAC addresses. Set session.dhcp.client_ID to “XIDMAC“ to use unique per-session identifiers for clients. After a VPN session ends, I expect the very next session to reuse the same DHCP IP but that doesn’t happen. Many DHCP servers cycle through all the client IP’s available for one subnet before reusing any. Also, after a session ends APM-DHCP takes a few minutes to release its DHCP IP. When I test APM-DHCP with APM VE running on VMware Workstation, none of my sessions gets an IP from DHCP. VMware Workstation’s built-in DHCP server sends bogus DHCP packets. Use another DHCP server for testing (Linux dhcpd(8) is cheap and reliable). I use BIG-IP route domains and I notice that some of my VPN clients are getting duplicate DHCP IP addresses. Decorate the IP addresses of your APM-DHCP virtual servers, both in the iApp and in session.dhcp.virtIP, with their route-domain ID’s in “percent notation” like “192.0.2.5%3”. APM-DHCP is not working. Double-check your configuration. Look for errors in the LTM log. Set session.dhcp.debug to “true” before trying to start a VPN session, then examine DHCP debugging messages in the LTM log to see if you can figure out the problem. Even after looking at debugging messages in the log I still don’t know why APM-DHCP is not working. Run “tcpdump –ne -i 0.0 -s0 port 67” to see where the DHCP handshake fails. Are DISCOVER packets sent? Do any DHCP servers reply with OFFER packets? Is a REQUEST sent to accept an OFFER? Does the DHCP server ACK that REQUEST? If you see an OFFER but no REQUEST, check for bogus multicast MAC addresses in the OFFER packet. If no OFFER follows DISCOVER, what does the DHCP server’s log show? Is there a valid zone/lease-pool for you? Check the network path for routing errors, hostile firewall rules, or DHCP relay issues. Endnotes In DHCP Option 43 (rfc2132). In DHCP Options 6 and 15 (rfc2132). Prior to version v3h, under certain circumstances with some DHCP servers, address-release delays could cause two active sessions to get the same IP address. And even more difficult using [listen], for those of you in the back of the room. A bug in some versions of VMware Workstation’s DHCP server makes this solution appear to fail. The broken DHCP server sends messages to DHCP relays in unicast IP packets encapsulated in broadcast MAC frames. A normal BIG-IP virtual server will not receive such packets. As of Winter 2017 the ISC, Cisco, and MS Windows Server 2016 DHCP servers support the subnet/link selection options but older Windows Server and Infoblox DHCP servers do not. Supporting Files - Download attached ZIP File Here.
APM Configuration to Support Duo MFA using iRule
Overview BIG-IP APM has supported Duo as an MFA provider for a long time with RADIUS-based integration. Recently, Duo has added support for Universal Prompt that uses Open ID Connect (OIDC) protocol to provide two-factor authentication. To integrate APM as an OIDC client and resource server, and Duo as an Identity Provider (IdP), Duo requires the user’s logon name and custom parameters to be sent for Authentication and Token request. This guide describes the configuration required on APM to enable Duo MFA integration using an iRule. iRules addresses the custom parameter challenges by generating the needed custom values and saving them in session variables, which the OAuth Client agent then uses to perform MFA with Duo. This integration procedure is supported on BIG-IP versions 13.1, 14.1x, 15.1x, and 16.x. To integrate Duo MFA with APM, complete the following tasks: 1. Choose deployment type: Per-request or Per-session 2. Configure credentials and policies for MFA on the DUO web portal 3. Create OAuth objects on the BIG-IP system 4. Configure the iRule 5. Create the appropriate access policy/policies on the BIG-IP system 6. Apply policy/policies and iRule to the APM virtual server Choose deployment type APM supports two different types of policies for performing authentication functions. Per-session policies: Per-session policies provide authentication and authorization functions that occur only at the beginning of a user’s session. These policies are compatible with most APM use cases such as VPN, Webtop portal, Remote Desktop, federation IdP, etc. Per-request policies: Per-request policies provide dynamic authentication and authorization functionality that may occur at any time during a user’s session, such as step-up authentication or auditing functions only for certain resources. These policies are only compatible with Identity Aware Proxy and Web Access Management use cases and cannot be used with VPN or webtop portals. This guide contains information about setting up both policy types. Prerequisites Ensure the BIG-IP system has DNS and internet connectivity to contact Duo directly for validating the user's OAuth tokens. Configure credentials and policies for MFA on Duo web portal Before you can protect your F5 BIG-IP APM Web application with Duo, you will first need to sign up for a Duo account. 1. Log in to the Duo Admin Panel and navigate to Applications. 2. Click Protect an application. Figure 1: Duo Admin Panel – Protect an Application 3. Locate the entry for F5 BIG-IP APM Web in the applications list and click Protect to get the Client ID, Client secret, and API hostname. You will need this information to configure objects on APM. Figure 2: Duo Admin Panel – F5 BIG-IP APM Web 4. As DUO is used as a secondary authentication factor, the user’s logon name is sent along with the authentication request. Depending on your security policy, you may want to pre-provision users in Duo, or you may allow them to self-provision to set their preferred authentication type when they first log on. To add users to the Duo system, navigate to the Dashboard page and click the Add New... -> Add User button. A Duo username should match the user's primary authentication username. Refer to the https://duo.com/docs/enrolling-users link for the different methods of user enrollment. Refer to Duo Universal Prompt for additional information on Duo’s two-factor authentication. Create OAuth objects on the BIG-IP system Create a JSON web key When APM is configured to act as an OAuth client or resource server, it uses JSON web keys (JWKs) to validate the JSON web tokens it receives from Duo. To create a JSON web key: 1. On the Main tab, select Access > Federation > JSON Web Token > Key Configuration. The Key Configuration screen opens. 2. To add a new key configuration, click Create. 3. In the ID and Shared Secret fields, enter the Client ID and Client Secret values respectively obtained from Duo when protecting the application. 4. In the Type list, select the cryptographic algorithm used to sign the JSON web key. Figure 3: Key Configuration screen 5. Click Save. Create a JSON web token As an OAuth client or resource server, APM validates the JSON web tokens (JWT) it receives from Duo. To create a JSON web token: 1. On the Main tab, select Access > Federation > JSON Web Token > Token Configuration. The Token Configuration screen opens. 2. To add a new token configuration, click Create. 3. In the Issuer field, enter the API hostname value obtained from Duo when protecting the application. 4. In the Signing Algorithms area, select from the Available list and populate the Allowed and Blocked lists. 5. In the Keys (JWK) area, select the previously configured JSON web key in the allowed list of keys. Figure 4: Token Configuration screen 6. Click Save. Configure Duo as an OAuth provider APM uses the OAuth provider settings to get URIs on the external OAuth authorization server for JWT web tokens. To configure an OAuth provider: 1. On the Main tab, select Access > Federation > OAuth Client / Resource Server > Provider. The Provider screen opens. 2. To add a provider, click Create. 3. In the Name field, type a name for the provider. 4. From the Type list, select Custom. 5. For Token Configuration (JWT), select a configuration from the list. 6. In the Authentication URI field, type the URI on the provider where APM should redirect the user for authentication. The hostname is the same as the API hostname in the Duo application. 7. In the Token URI field, type the URI on the provider where APM can get a token. The hostname is the same as the API hostname in the Duo application. Figure 5: OAuth Provider screen 8. Click Finished. Configure Duo server for APM The OAuth Server settings specify the OAuth provider and role that Access Policy Manager (APM) plays with that provider. It also sets the Client ID, Client Secret, and Client’s SSL certificates that APM uses to communicate with the provider. To configure a Duo server: 1. On the Main tab, select Access > Federation > OAuth Client / Resource Server > OAuth Server. The OAuth Server screen opens. 2. To add a server, click Create. 3. In the Name field, type a name for the Duo server. 4. From the Mode list, select how you want the APM to be configured. 5. From the Type list, select Custom. 6. From the OAuth Provider list, select the Duo provider. 7. From the DNS Resolver list, select a DNS resolver (or click the plus (+) icon, create a DNS resolver, and then select it). 8. In the Token Validation Interval field, type a number. In a per-request policy subroutine configured to validate the token, the subroutine repeats at this interval or the expiry time of the access token, whichever is shorter. 9. In the Client Settings area, paste the Client ID and Client secret you obtained from Duo when protecting the application. 10. From the Client's ServerSSL Profile Name, select a server SSL profile. Figure 6: OAuth Server screen 11. Click Finished. Configure an auth-redirect-request and a token-request Requests specify the HTTP method, parameters, and headers to use for the specific type of request. An auth-redirect-request tells Duo where to redirect the end-user, and a token-request accesses the authorization server for obtaining an access token. To configure an auth-redirect-request: 1. On the Main tab, select Access > Federation > OAuth Client / Resource Server > Request. The Request screen opens. 2. To add a request, click Create. 3. In the Name field, type a name for the request. 4. For the HTTP Method, select GET. 5. For the Type, select auth-redirect-request. 6. As shown in Figure 7, specify the list of GET parameters to be sent: request parameter with value depending on the type of policy For per-request policy: %{subsession.custom.jwt_duo} For per-session policy: %{session.custom.jwt_duo} client_id parameter with type client-id response_type parameter with type response-type Figure 7: Request screen with auth-redirect-request (Use “subsession.custom…” for Per-request or “session.custom…” for Per-session) 7. Click Finished. To configure a token-request: 1. On the Main tab, select Access > Federation > OAuth Client / Resource Server > Request. The Request screen opens. 2. To add a request, click Create. 3. In the Name field, type a name for the request. 4. For the HTTP Method, select POST. 5. For the Type, select token-request. 6. As shown in Figure 8, specify the list of POST parameters to be sent: client_assertion parameter with value depending on the type of policy For per-request policy: %{subsession.custom.jwt_duo_token} For per-session policy: %{session.custom.jwt_duo_token} client_assertion_type parameter with value urn:ietf:params:oauth:client-assertion-type:jwt-bearer grant_type parameter with type grant-type redirect_uri parameter with type redirect-uri Figure 8: Request screen with token-request (Use “subsession.custom…” for Per-request or “session.custom…” for Per-session) 7. Click Finished. Configure the iRule iRules gives you the ability to customize and manage your network traffic. Configure an iRule that creates the required sub-session variables and usernames for Duo integration. Note: This iRule has sections for both per-request and per-session policies and can be used for either type of deployment. To configure an iRule: 1. On the Main tab, click Local Traffic > iRules. 2. To create an iRules, click Create. 3. In the Name field, type a name for the iRule. 4. Copy the sample code given below and paste it in the Definition field. Replace the following variables with values specific to the Duo application: <Duo Client ID> in the getClientId function with Duo Application ID. <Duo API Hostname> in the createJwtToken function with API Hostname. For example, https://api-duohostname.com/oauth/v1/token. <JSON Web Key> in the getJwkName function with the configured JSON web key. Note: The iRule ID here is set as JWT_CREATE. You can rename the ID as desired. You specify this ID in the iRule Event agent in Visual Policy Editor. when ACCESS_POLICY_AGENT_EVENT { if { [ACCESS::policy agent_id] eq "JWT_CREATE" } { set duo_uname [ACCESS::session data get "session.logon.last.username"] # Inline logic for creating JWT set header "{\"alg\":\"HS512\",\"typ\":\"JWT\"}" set exp [expr {[clock seconds] + 900}] set client_id "<Duo Client ID>" set redirect_uri "https://[ACCESS::session data get session.server.network.name]/oauth/client/redirect" set payload "{\"response_type\": \"code\",\"scope\":\"openid\",\"exp\":${exp},\"client_id\":\"${client_id}\",\"redirect_uri\":\"${redirect_uri}\",\"duo_uname\":\"${duo_uname}\"}" set jwt_duo [ACCESS::oauth sign -header $header -payload $payload -alg HS512 -key "<JSON Web Key>"] ACCESS::session data set session.custom.jwt_duo $jwt_duo # JWT Token creation set aud "<Duo API Hostname>" set jti [string range [clock seconds] 0 31] set token_payload "{\"sub\": \"${client_id}\",\"iss\":\"${client_id}\",\"aud\":\"${aud}\",\"exp\":${exp},\"jti\":\"${jti}\"}" set jwt_duo_token [ACCESS::oauth sign -header $header -payload $token_payload -alg HS512 -key "<JSON Web Key>"] ACCESS::session data set session.custom.jwt_duo_token $jwt_duo_token } } when ACCESS_PER_REQUEST_AGENT_EVENT { if { [ACCESS::perflow get perflow.irule_agent_id] eq "JWT_CREATE" } { set duo_uname [ACCESS::session data get "session.logon.last.username"] set header "{\"alg\":\"HS512\",\"typ\":\"JWT\"}" set exp [expr {[clock seconds] + 900}] set client_id "<Duo Client ID>" set redirect_uri "https://[ACCESS::session data get session.server.network.name]/oauth/client/redirect" set payload "{\"response_type\": \"code\",\"scope\":\"openid\",\"exp\":${exp},\"client_id\":\"${client_id}\",\"redirect_uri\":\"${redirect_uri}\",\"duo_uname\":\"${duo_uname}\"}" set jwt_duo [ACCESS::oauth sign -header $header -payload $payload -alg HS512 -key "<JSON Web Key>"] ACCESS::perflow set perflow.custom $jwt_duo # JWT Token creation set aud "<Duo API Hostname>" set jti [string range [clock seconds] 0 31] set token_payload "{\"sub\": \"${client_id}\",\"iss\":\"${client_id}\",\"aud\":\"${aud}\",\"exp\":${exp},\"jti\":\"${jti}\"}" set jwt_duo_token [ACCESS::oauth sign -header $header -payload $token_payload -alg HS512 -key "<JSON Web Key>"] ACCESS::perflow set perflow.scratchpad $jwt_duo_token } } Note: iRule updated 11/27/2024 to eliminate CMP demotion. Figure 9: iRule screen 5. Click Finished. Create the appropriate access policy/policies on the BIG-IP system Per-request policy Skip this section for a per-session type deployment The per-request policy is used to perform secondary authentication with Duo. Configure the access policies through the access menu, using the Visual Policy Editor. The per-request access policy must have a subroutine with an iRule Event, Variable Assign, and an OAuth Client agent that requests authorization and tokens from an OAuth server. You may use other per-request policy items such as URL branching or Client Type to call Duo only for certain target URIs. Figure 10 shows a subroutine named duosubroutine in the per-request policy that handles Duo MFA authentication. Figure 10: Per-request policy in Visual Policy Editor Configuring the iRule Event agent The iRule Event agent specifies the iRule ID to be executed for Duo integration. In the ID field, type the iRule ID as configured in the iRule. Figure 11: iRule Event agent in Visual Policy Editor Configuring the Variable Assign agent The Variable Assign agent specifies the variables for token and redirect requests and assigns a value for Duo MFA in a subroutine. This is required only for per-request type deployment. Add sub-session variables as custom variables and assign their custom Tcl expressions as shown in Figure 12. subsession.custom.jwt_duo_token = return [mcget {perflow.scratchpad}] subsession.custom.jwt_duo = return [mcget {perflow.custom}] Figure 12: Variable Assign agent in Visual Policy Editor Configuring the OAuth Client agent An OAuth Client agent requests authorization and tokens from the Duo server. Specify OAuth parameters as shown in Figure 13. In the Server list, select the Duo server to which the OAuth client directs requests. In the Authentication Redirect Request list, select the auth-redirect-request configured earlier. In the Token Request list, select the token-request configured earlier. Some deployments may not need the additional information provided by OpenID Connect. You could, in that case, disable it. Figure 13: OAuth Client agent in Visual Policy Editor Per-session policy Configure the Per Session policy as appropriate for your chosen deployment type. Per-request: The per-session policy must contain at least one logon page to set the username variable in the user’s session. Preferably it should also perform some type of primary authentication. This validated username is used later in the per-request policy. Per-session: The per-session policy is used for all authentication. A per-request policy is not used. Figures 14a and 14b show a per-session policy that runs when a client initiates a session. Depending on the actions you include in the access policy, it can authenticate the user and perform actions that populate session variables with data for use throughout the session. Figure 14a: Per-session policy in Visual Policy Editor performs both primary authentication and Duo authentication (for per-session use case) Figure 14b: Per-session policy in Visual Policy Editor performs primary authentication only (for per-request use case) Apply policy/policies and iRule to the APM virtual server Finally, apply the per-request policy, per-session policy, and iRule to the APM virtual server. You assign iRules as a resource to the virtual server that users connect. Configure the virtual server’s default pool to the protected local web resource. Apply policy/policies to the virtual server Per-request policy To attach policies to the virtual server: 1. On the Main tab, click Local Traffic > Virtual Servers. 2. Select the Virtual Server. 3. In the Access Policy section, select the policy you created. 4. Click Finished. Figure 15: Access Policy section in Virtual Server (per-request policy) Per-session policy Figure 16 shows the Access Policy section in Virtual Server when the per-session policy is deployed. Figure 16: Access Policy section in Virtual Server (per-session policy) Apply iRule to the virtual server To attach the iRule to the virtual server: 1. On the Main tab, click Local Traffic > Virtual Servers. 2. Select the Virtual Server. 3. Select the Resources tab. 4. Click Manage in the iRules section. 5. Select an iRule from the Available list and add it to the Enabled list. 6. Click Finished.APM Advanced Customization Examples with Modern Template, v15.1+
Introduction This guide will walk through how the logon, webtop, and other UI pages are created by APM, how it works, and some examples.The new APM modern template has an updated look in both mobile and desktop browsers. It uses the popular Preact framework to provide a consistent and familiar end user experience. How to activate the new customization system New policies created in 15.1 and later default to the new Modern template. Existing policies made before 15.1 continue to use the Standard template. When creating a new access policy: You can see the customization types applied to all access policies in the Per-Session access policy menu: Customization Sections Basic, General, and Advanced Customization APM has different ways to customize, depending on the desired complexity. Some administrators simply want to change colors, while others would prefer to completely rewrite the APM user-facing HTML and CSS so they have similar branding to other corporate web properties. As is typical with CSS, style customizations can be applied simultaneously with later style changes overriding earlier ones. Basic Customization Simple customization settings such as images, titles, captions, and colors are applied to resources and policies using Basic Customization. The tables and screenshot below detail the settings. Elements in Basic Customization Header/Footer/Title Header Image for Desktop (Max height: 60px) Header Image for Mobile (Max height: 30px) Layout Settings Maximum viewport width for applying small (mobile) screen styles (px) Browser width for mobile clients Minimum viewport width for applying large (desktop) screen styles (px) Browser width for desktop clients Colors (see image for sections) Active Links and Buttons Color Footer Background Color Form Background Color Header Color Page Background Color Solid Button Text Color Text Color Top Strip Color General Customization General Customization offers a more advanced tree view of the Basic Customization settings as well as text options for user-facing messages. Like Basic customization, the settings are applied individually to each access policy and policy item via the item’s XML file specified in the cache-path parameter of the associated customization group configuration object. To use General Customization Create the policies and/or resources you would like to customize. Find them in the tree view. Make the changes. Perform the standard 3-step save process: Save Draft, Save, then Apply the access policy. You use General Customization to apply changes to the informational text strings and error messages that are displayed to users. Browse the configuration tree to see the available customization areas. The settings are divided into Branding and Text. Text are the localized messages that are displayed to the end users, including associated HTML. User-facing status and text messages can be selected in the Text tab. Branding options are about page styling, colors, fonts, and the like. These are selected in the Branding tab. Special General Options APM customization has a few non-branding and non-text special options in the configuration tree. Disable all external scripts and styles The new Modern customization includes a new resource loader feature. This feature loads all added CSS and JS resources dynamically, including 3 rd party external code. You use this option like a “Revert” to restore the default branding in case there is some unknown trouble. If enabled, it disables loading of all external CSS and JS, including the APM-hosted user-XXXX.js and user-XXXX.css files. External Javascript / CSS You can now easily add external javascript references, for libraries such as JQuery that you would like your users to load from an external CDN. Historically this would present a security problem because the CDN content may be vulnerable to malicious injection. APM uses the W3C subresource integrity feature(https://www.w3.org/TR/SRI/) mechanism to ensure that the external files are not tampered. You can also specify external scripts manually in user-XXXX.js, but using the inbuilt APM script-loader mechanism allows us to trap loading errors and disable all external scripts globally, in case of any problems (see the previous section). To use this feature: Find the checksum* and URL of your resource. jQuery makes this very simple: It’s directly on their CDN page. Alternatively, you can compute them using srihash.org. Place the values into External Scripts / Styles. Save, Apply the access policy, and visit the access policy virtual. *Note*: APM’s end-user pages are built using Preact with built-in libraries, so don't load another copy of Preact using this mechanism. See the Advanced Examples section below for usage ideas. If the checksum is incorrect the stock APM javascript will function correctly, but the external resource will not be loaded and the browser will produce a “Failed to find a valid digest in the integrity attribute for resource ‘xxxxxx’” error in the console similar to this screenshot: * Supported checksum mechanisms are SHA-256, SHA-384, or SHA-512. Advanced Customization Use Advanced Customization to edit or place code directly into the files that are referenced from the primary APM user-facing HTML. Common settings are available which load on all pages, along with separate CSS and JS for each policy item that is present in the policy. Generally, the CSS/JS for each policy item load after the common settings so later settings will override earlier ones. You must first add policy items to customize before customizing them. This is a customization tree view before and after adding Logon Page to access policy: Before After Operation of Advanced Customization With Advanced Customization, you can do essentially any styling you want using standard CSS. Advanced Customization has some common settings, agent settings, and some special settings. After making any change, Save Draft, then Save., then Apply the access policy. Common settings These two files (user-common.css and user-common.js) are loaded on all* APM user-facing pages, including policy evaluation (logon, message, etc), webtop, and logout. Use these if you want to change a page style in all areas. For example, perhaps we always want to hide the header and footer and add a background image. To do that, we can simply add some CSS to user-common.css to set a few properties targeting the apmui-header, apmui-main, and apmui-footer CSS selectors. Example: logon page customization Hide header and footer, and add a picture: *Note*: You should usually make logon-specific changes on the logon page rather than “common”, since the webtop places some GUI links in apmui-header. Hiding the header removes access to these links! You can use user-common.js to load a tracker such as Google Analytics. Example: Google Analytics Customization Types There are two broad categories for the customization of APM objects: Resources are Assigned during per-session access policy execution. They include customizable icons, captions, and descriptions that are visible on the APM full webtop (sometimes called a portal). OAuth Client App OAuth Scope App Tunnel Network Access Remote Desktop SAML Web App (Portal Access) Webtop Link Webtop Section Non-Resources each have different configuration properties General Framework Installation EPS Logout (Ending Denied) Error message Decision Box Confirm/Continue Ending Denied Message Box Oauth Authz Webtop Screenshots *Example*: Simple resource customization of a webtop link resource End-User view from APM webtop: Troubleshooting Tips: Configuration Structure Resource customization settings, text strings, and image files are stored as interdependent configuration and file objects. When troubleshooting, check the following configuration areas. This diagram represents the dependencies: This table represents the item details, and troubleshooting tips: NOTE: To create resource customization using scripting or automation, they must be created all at once using a TMSH transaction rather than individually because of the interdependency between resources, profiles, policies, policy items, agents, and customization groups. To get started, use the GUI to create a policy you like, then review the configuration objects defined in tmsh list apm. The objects inter-referred-to must be copied into a transaction. equivalent create apm xxxx commands inside of a transaction. For detail on transactions with APM policies, see tmsh help apm policy access-policy tmsh help cli transaction HTML Rendering Details Access profiles, Per Request Policies and other objects (customized independently from an access profile) share similar syntax and structure. Each object has customization settings. Access Profiles have multiple groups of customization settings. Every time you change customization, it generates a set of files that are combined to form the user-displayed page. Settings (color, font, text, and so on) for the header and footer can be defined in access profile customization. Settings for the location and alignment of the content area can also be defined in access profile customization. Settings for resources displayed in the APM Webtop can be defined in the resource's configuration area (see payroll example above). APM Sandbox / Image Hosting To place images or other files in APM for convenient access by end users, use the Hosted Content feature. On a BIG-IP system, on the Main tab, click Access > Webtops > Hosted Content > Manage Files. Upload an image file. Click Upload >> Manage Access, and make sure the checkbox for your access policy attached to the virtual server is selected. Access the file at the location indicated in the Publicly Accessible URI column. General Examples Execute external javascript code after Logon Page browser rendering is complete. This example can be placed into user-logon.js to use the D3 library to display a small pop-up message. Additional code can be inserted for custom functions. define(["require", "exports", "tslib", "module", "apmui/page/logon/View"], function (require, exports, tslib_1, module, View_1) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); requirejs.config({ map: { 'apmui/master/View': { 'apmui/page/logon/View': module.id, }, }, }); /* Replacement View component */ var CustomLogonView = /** @class */ (function (_super) { tslib_1.__extends(CustomLogonView, _super); function CustomLogonView() { return _super !== null && _super.apply(this, arguments) || this; } CustomLogonView.prototype.componentDidMount = function () { _super.prototype.componentDidMount.call(this); requirejs(['https://d3js.org/d3.v6.min.js'], function (d3) { // Place your code inside this function d3.select("form").append("span") .text("Hello from D3 library"); }); }; return CustomLogonView; }(View_1.default)); exports.default = CustomLogonView; }); Execute local javascript code inside Logon Page. This example can be placed into user-logon.js to perform custom actions. define(["require", "exports", "tslib", "module", "apmui/page/logon/View"], function (require, exports, tslib_1, module, View_1) { "use strict"; Object.defineProperty(exports, "__esModule", { value: true }); requirejs.config({ map: { 'apmui/master/View': { 'apmui/page/logon/View': module.id, }, }, }); /* Replacement View component */ var CustomLogonView = /** @class */ (function (_super) { tslib_1.__extends(CustomLogonView, _super); function CustomLogonView() { return _super !== null && _super.apply(this, arguments) || this; } CustomLogonView.prototype.componentDidMount = function () { _super.prototype.componentDidMount.call(this); alert('PLACE CUSTOM CODE HERE'); }; return CustomLogonView; }(View_1.default)); exports.default = CustomLogonView; }); Advanced Examples These use TypeScript and preact You should be familiar with these technologies and their usage. To use these examples, you need a standard TypeScript/NodeJS+NPM build environment. This can be most easily achieved by using Linux, Microsoft Windows Subsystem for Linux (WSL), or Mac, then installing NodeJS which includes NPM. The examples are attached to this article as a ZIP archive. Download and decompress this file to a suitable location on your workstation. Read README.md from the package. Each example here assumes you have already downloaded the package and run npm install; npm run build. The compilation result is placed in the dist directory. For each one of the examples, you simply copy the user-xxxx.css and user-xxxx.js files into the correct object in Advanced Customization. To make changes to these examples, modify the files in src, then npm run build, as specified in README.md. Example 1: Decision box with more options By default, the APM Decision Box has only two choices. We can use this advanced customization example to append additional choices. Follow this procedure: Add a decision box to your access policy. Navigate to customization-examples/dist/decisionBox-more-options and copy the contents of user-decision.js to the appropriate area in Advanced Customization. Click Save Draft, Save, and apply the access policy. As a user, navigate to the decision box on the APM virtual server. Now the decision box has 4 options rather than two. The option and icon detail are in the example user-decision.ts source file: The result: value is the raw POST data, which is transferred from the client browser when the my.policy page is submitted. It must match an agent expression in the branch rules defined for the decision box object. As with all other agents, the branch rules must be defined in the policy-item configuration so that the additional branches are available in the VPE for use: Once these additional branch rules are defined, they can be added to the VPE flow: When a user makes a choice, it appears in log files thusly: To host your own icons, you can use the APM sandbox hosting feature, discussed elsewhere in this doc. Example 2: Logon box custom component This example adds a custom Preact component to the Logon Box. Add a Logon Page to your access policy, then copy the example dist code into your user-logon.js and user-logon.css files. Output: Example 3: Logon custom view This is an example of how to obtain a JSON-formatted dump of data available programmatically. Add the code from logon-custom-view to your APM policy files, then visit the APM virtual. You will see JSON data that provides the detailed data available. Example 4: PIN Pad replaces standard forms logon page This is an example of an alternative method of rendering a standard forms logon page with a polymorphic virtual PIN pad. It uses Preact and CSS to achieve this result. Note: A similar result with a virtual keyboard is possible as well, using other modules available via npm. This requires Preact development. As with the other examples, compile the TypeScript and place the dist’s user-logon.css and user-logon.js into the APM’s advanced customization area for your logon agent. The result when visiting this logon page is illustrated in this screenshot: Example 5: Validation of input fields logon-validate-domain contains a sample that has an example of input field validation: The input validation logic can be changed with the following TypeScript: This kind of validation logic can be extended for almost any purpose. Example 6: Pin resource to top of webtop Recently-used-resources implements a mechanism that uses local storage to track how many times a resource has been clicked. It also creates a new webtop section that displays most-clicked-on resources. You must have a full webtop and multiple resources assigned to the user (any type is fine). Use this example like the others: Copy the dist directory files user-webtop.css and user-webtop.js to the advanced customization object and click Save Draft, then Save, and apply the access policy. Note that you may have to clear BIG-IP or browser cache to see the update. Take a few minutes to examine the browser's Local Storage contents while clicking various favorites assigned to the user. Example 7: Pin resources on full webtop Most application portals offer some kind of system to save often-used resources at the top of the list. This example uses HTML5 Browser Local Storage to save the user’s resources and render them at the top of the webtop application portal. You must assign a full webtop and multiple resources to the user. Use this example like the others: Copy the dist directory files user-webtop.css and user-webtop.js to the advanced customization object and click Save Draft, then Save, and apply the access policy. Note that you may have to clear BIG-IP or browser cache to see the update. Afterwards, logon as a user to the webtop and click the corner pin icon to add the resource to Pinned Resources. Try to log out and back in and see that the resource(s) are saved. Check the browser developer tools to query the local storage contents. Examples Conclusion We hope these examples are helpful to performing customization of APM web pages. Please let us know of any further examples that you would like to share! Request For Examples We have received the following requests for examples and hope to add these soon. Let us know if you can contribute! Simplest way to add an HTML link and text into the logon page Simplest way to add a select box to a logon page Example virtual keyboard logon page Attributions / Licensing / Support Status Support Status: F5 Support cannot provide assistance with TypeScript, JavaScript, or Preact coding or web development. To validate the operation of any of these examples, standard web development practices should be used. F5 code: These examples include code produced by F5 intended to showcase the possibilities of the v15.1.0 APM customization system and can be used by any APM customer. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3 rd Party Code: As with most open source software, each module in this example includes a separate license (MIT, CC, etc). Before using any of these in a production environment, please review the licensing requirements for each NPM package in node_modules. Media: Beach scene used in customization examples: Stones in the Beach By Xavierfsc - Own work, CC BY 4.0, https://commons.wikimedia.org/w/index.php?curid=84430607
APM Cookbook: SAML IdP Chaining
As an APM subject mater expert at F5 I often find myself in situations where a customer or colleague needs an example of a particular configuration. While most of these requests are easily handled with a call or WebEx I'm a firm believer in sharing knowledge through documentation.. and I don't like getting calls at 3 AM. If you're like me you grew up with the O'Reilly Cookbook series which served as a great reference document for various development or server configuration tasks. My goal is to create a similar reference resource here on DevCentral for those one-off scenarios where a visual example may help your complete your task. For the first APM Cookbook series I'll discuss SAML IdP chaining. Overview Security Assertion Markup Language, more commonly known as SAML, is a popular federated authentication method that provides web based single sign-on. One of the key security advantages to SAML is the reduction in username/password combinations that a user has remember... or in my experience as a security engineer the number of passwords written on a post-it note stuck to their monitor. There are two major services in a SAML environment: IdP - Identity Provider SP - Service Provider The identity provider is the SAML service that authenticates the user and passes an assertion to then service providers proving the user's identity. F5's APM performs both IdP and SP services and allows customers to easily deploy federated authentication in their environment. In more complex scenarios you may run across a requirement where multiple SAML IdPs need to be chained together. This comes up from time to time when customers have contractors that utilize federated authentication for authorization to corporate resources. Example For our configuration we have the Globex Corporation that uses APM to authenticate uses to Office 365. Globex hire contractors from Acme Corp. who authenticate using the Acme Corp. ADFS environment. However, since Office 365 is configured to authenticate against the Globex APM we need to convert the Acme Corp. SAML assertion into a Globex SAML assertion, which is known as IdP chaining. The step ladder for this process is shown below: 1. User requests https://outlook.com/globex.com 2 - 3. Office 365 redirects user to idp.globex.com 3 - 4. idp.globex.com determines user is a contractor and redirect user to sts.acme.com 5 - 8. User authenticates using Acme credentials and is then redirect back to idp.globex.com 9. idp.globex.com consumes the Acme SAML assertion and creates a Globex SAML assertion 10. User is redirected back to Office 365 11 - 12. Office 365 consumes the Globex SAML assertion and displays the user's mail Configuration To configure your APM SAML IdP to accept incoming assertion from sts.acme.com we need to create an external SP connector. Under the Access Policy -> SAML -> BIG-IP as SP configuration section: 1. Create a new SAML SP Service 2. Export the SP metadata and configure sts.acme.com accordingly (follow your IdP vendor's documentation) 3. Click the External IdP Connectors menu at the top 4. Click the dropdown arrow on the create button and choose From Metadata (import the metadata from sts.acme.com) 5. Bind the Local SP service to the external IdP connector Now that idp.globex.com and sts.acme.com are configured to trust one another we need to configure the APM IdP to consume the sts.acme.com SAML assertion. The IdP's Visual Policy Editor should look similar to the image below: 1. The Decision Box asks the user what company they're with. This is a simple example but more elaborate home realm discovery techniques can be used. 2. The SAML Auth box is configured to consume the sts.acme.com assertion 3. Since we no longer have a login form on the IdP we need to set a few APM session variables: session.logon.last.username = Session Variable session.saml.last.identity session.logon.last.logonname = Session Variable session.saml.last.identity 4. Create an Advanced Resource Assign that matches your existing IdP Advance Resource Assign. Conclusion This particular post was a little longwinded due to the steps required but overall is a fairly simple configuration. So the next time someone asks if your F5 can do IdP chaining you can confidently reply "Yes and I know how to do that".
Yubikey Authentication Modes and Azure AD integration via the APM
Introduction The Yubikey ( https://www.yubico.com/) supports three major functions, authentication, signing and encryption. As far as authentication goes, it supports a list of the following mechanisms. OTP (one-time password) Yubikey OTP (Time based OTP) OATH HOTP (HMAC based OTP) FIDO U2F (Universal 2 nd Factor) FIDO2 PIV (Smartcard) Each of the above-mentioned protocols has its own set of requirements and is therefore not universally supported everywhere. OTP OTP is probably the simplest, with a one-time password being used, typically as the 2 nd factor. However, it is also the weakest, as it does not mitigate against MITM attacks. E.g., A fake site impersonating a legitimate site can trick the user into entering the OTP and subsequently forwards it to the real site. All Yubikey’s by default have manufacture assigned secrets registered with Yubico’s own validation servers. Yubico provides a tool that allows you to re-program the key, giving it a different secret. However, the new secret has to be uploaded to Yubico’s validation servers ( https://upload.yubico.com/ ) otherwise OTP will stop working. Yubikey OTP integrates with a large number of services (e.g., Gmail, LastPass). When a service receives an OTP, it reaches out to Yubico for validation. In the case of Okta, the secrets can be uploaded directly into Okta and validation happens within Okta. FIDO U2F FIDO U2F or U2F for short, mitigates MITM. This method requires the user to register the authenticator (e.g., Yubikey) with the application (e.g., Gmail) first, during which a key pair is generated by the authenticator, and the public key is sent and stored on the application. Once the registration is complete, the user can then use the authenticator as the 2 nd factor. In the case of Gmail, once the user’s credentials are verified, the user touches the Yubikey for 2 nd factor. No code is entered by the user. FIDO2 FIDO2 enables passwordless authentication. Once the Yubikey is registered with an application (e.g., Azure Portal) for FIDO2 authentication, the user touches the Yubikey, optionally provides a PIN code for the key, logs straight in. – no username is entered FIDO2 is an evolution of U2F and is dependent upon WebAuthn (client API implemented within the browser) and CTAP2 (authenticator API that enables FIDO2-capable devices to interface to external/roaming authenticators over Bluetooth, USB or Near field communication (NFC)). Per FIDO Alliance ( https://fidoalliance.org/fido2/fido2-web-authentication-webauthn/#:~:text=WebAuthn%20is%20currently%20supported%20in,Windows%2010%20and%20Android%20platforms ), browser support for U2F and WebAuthn are shown below. PIV YubiKey can also present itself as a PIV smartcard that contains a client certificate. APM Integration There are a number of articles on DevCentral that cover programming the APM to receive the Yubikey OTP and then send it over to Yubico’s validation servers via a side band connection for OTP verification. My particular use case is to leverage an IDaaS (e.g., Azure AD) as an IDP and use the APM as the SP. My choice of integration is via OIDC, but SAML is an equally valid option. Since authentication is offloaded to Azure AD, both the OTP and FIDO2 passwordless authentication methods are now available. Azure AD does not support U2F. Azure AD and User Configuration OTP If Yubikey is used for OTP, Azure AD needs to have MFA enabled, a ‘Conditional Access’ policy is created to ‘Require multi-factor authentication’ for your selected apps. This process is documented by Microsoft ( https://docs.microsoft.com/en-us/azure/active-directory/authentication/tutorial-enable-azure-mfa ). The user must also add an authenticator app via self-registration ( https://mysignins.microsoft.com/ ), be sure to click on the highlighted, this allows you to enrol the ‘Yubico Authenticator’ ( https://www.yubico.com/products/services-software/download/yubico-authenticator/ ). The Yubico Authenticator works with the Yubikey to generate the OTP. Yubico argues that it is more secure as unlike a soft authenticator, the secrets are not saved within the authenticator itself, but rather in a secure element within the Yubikey. Note ‘Touch your Yubikey’, which is needed before an OTP is generated. The OTP method does not impose special requirements on the browsers, which means it works on any browsers, as well as on the APM Edge client, which leverages certain browser functions FIDO2 With FIDO2 based passwordless authentication, the ‘FIDO2 Security Key’ option within the Azure AD (e.g., under Security) has to be enabled first. Again, the user goes through self-registration ( https://mysignins.microsoft.com/ ) prior to the Yubikey becoming available. I have tried different browsers on the Mac, the only browsers that work are Chrome and Edge. Milage may vary in Windows. If FIDO2 works, the highlighted option will appear. In the case of Azure AD, a PIN is required (configured over the self-registration process). Once it’s entered, the user logs in after touching the Yubikey. At this time, the latest (v7210) APM Edge client’s embedded browser for login does not work with FIDO2, likely due to WebAuthn not being supported. If the user uses a supported browser, passwordless authentication should work, after which a webtop is presented.
Improve BIG-IP APM VPN speed with TLS dynamic record size
After successfully setting up BIG-IP APM network access, and running it for sometime, you may be looking for ways to optimize VPN speed for your users. This article discusses one way you can do that. Feature Description Beginning in BIG-IP 12.1.0, the Client SSL profile includes a feature that enables dynamic record size in TLS. When applied to a F5 BIG-IP Access Policy Manager (APM) network access VPN TLS virtual server, this can improve VPN speeds for your users. It has been found that certain protocols, notably HTTP, show better client response times using this method. For more information on the Allow Dynamic Record Sizing setting down to the packet level, refer to the following resources The About dynamic record sizing section of the BIG-IP System: SSL Administration manual. Boosting TLS Performance with Dynamic Record Sizing on BIG-IP on DevCentral. SSL Profiles Part 11: TLS Optimization on DevCentral. Important: Dynamic record size is a TLS enhancement and does not apply to BIG-IP APM network access DTLS virtual servers. Do not enable dynamic record size on DTLS. When you want to optimize network performance, you must allocate time to tune each configuration to match the requirements specific to your environment. Additionally, note that configuration changes that improve performance may increase BIG-IP system resource (CPU, memory) usage. Testing dynamic record size on VPN speeds Having discussed the theory behind the feature, we will now perform tests to see how it affects VPN speeds. Network bandwidth can vary depending on many factors, for instance, peak vs non-peak hours. When more users are connected to a VPN, download speeds can decrease significantly. It is therefore important to establish a baseline network bandwidth and download speed at the beginning: Baseline AWS environment Windows Client (Seattle) -- VPN --> BIG-IP APM (Oregon) --local LAN--> Apache and iperf servers AWS environment: BIG-IP APM 17.1.0 VE on AWS (F5 BIG-IP VE - ALL modules, m5.xlarge, 1 Gbps, AWS) located in us-west-2 Oregon. Note: Ensure you use at least the recommended size (m5.xlarge) and at least 1Gbps on AWS to make sure there are no bandwidth and resource limits. Windows client in located in Seattle Using iperf3 to measure network bandwidth Using curl to download a 377MB apmclient.iso Optional: You can optionally test using the developer tools on your browser. I used firefox; as the results did not differ significantly from curl. They are not included in this article. Baseline test results These are measured with all default settings on BIG-IP APM and dynamic record sizing not enabled: curl download results Average download speed: 4950k C:\Windows\system32>curl -k -o null https://10.0.128.23/apmclient.iso % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 377M 100 377M 0 0 4950k 0 0:01:18 0:01:18 --:--:-- 4988k iperf3 results Network bandwidth: 4873 KB/sec c:\Users\klau\Desktop\iperf-3.1.3-win64>iperf3.exe -c 10.0.128.24 --get-server-output -i 1 -f K -R Connecting to host 10.0.128.24, port 5201 Reverse mode, remote host 10.0.128.24 is sending [ 4] local 10.0.128.31 port 61284 connected to 10.0.128.24 port 5201 [ ID] Interval Transfer Bandwidth [ 4] 0.00-1.00 sec 4.33 MBytes 4434 KBytes/sec [ 4] 1.00-2.00 sec 4.67 MBytes 4785 KBytes/sec [ 4] 2.00-3.00 sec 4.86 MBytes 4977 KBytes/sec [ 4] 3.00-4.00 sec 4.77 MBytes 4878 KBytes/sec [ 4] 4.00-5.00 sec 4.72 MBytes 4834 KBytes/sec [ 4] 5.00-6.00 sec 4.78 MBytes 4898 KBytes/sec [ 4] 6.00-7.00 sec 4.87 MBytes 4989 KBytes/sec [ 4] 7.00-8.00 sec 4.81 MBytes 4925 KBytes/sec [ 4] 8.00-9.00 sec 4.71 MBytes 4823 KBytes/sec [ 4] 9.00-10.00 sec 4.82 MBytes 4934 KBytes/sec - - - - - - - - - - - - - - - - - - - - - - - - - [ ID] Interval Transfer Bandwidth Retr [ 4] 0.00-10.00 sec 48.0 MBytes 4919 KBytes/sec 9 sender [ 4] 0.00-10.00 sec 47.6 MBytes 4873 KBytes/sec receiver Server output: [...] [ 5] 0.00-10.04 sec 48.0 MBytes 4900 KBytes/sec 9 sender Test 1: Enabling dynamic record size from baseline Comparing with baseline results after enabling dynamic record size Baseline: Dynamic record size disabled dynamic record size enabled Percentage improvement curl average download, k 4950 5272 6.51% iperf3 network bandwidth, KBytes/sec 4873 5138 5.44% While this may not appear to be too high on the AWS cloud, there is also received feedback from customers that they see greater improvements in environments, especially in cases where the end-to-end latencies increase. Implementation strategy and recommendations As you plan to introduce this in your environment, take note of the following recommendations: Every environment is unique Many factors can affect network performance. This can range from VLAN settings (For example. MTU), TCP settings, intermediate network device throttling, and so on. You must perform testing in your own environment before enabling the feature. Implement the feature incrementally for a selected group of users. There are different ways to do this. For example, use an iRule to redirect users based on a URL, to a separate virtual server using a different Client SSL profile that has the feature enabled. Refer to SSL::allow_dynamic_record_sizing on Clouddocs. Monitor BIG-IP system logs and resource usage After you enable dynamic record size, make sure that your BIG-IP system continues to function as expected by monitoring the following monitor /var/log/ltm and /var/log/apm log files monitor BIG-IP CPU and memory usage. For example, you can select Dashboard on the Configuration utility, generating a QKview and analyze it in iHealth and so on. For more information, refer to K71764661: Understanding BIG-IP CPU usage and K16419: Overview of BIG-IP memory usage Verify and analyze SSL statistics Use the tmsh command in K41057430: Enhanced SSL profile statistics and check for failures. The SSL Dynamic Record Sizes section should also indicate use of large record sizes. Boosting TLS Performance with Dynamic Record Sizing on BIG-IP Conclusion There are a variety of different ways to improve VPN speeds, and this article describes just one. For other options and considerations, refer to K31143831: VPN for business continuity | Chapter 5: Optimizing Network Access VPN.OWASP Tactical Access Defense Series: Broken Authentication and BIG-IP APM
The threat of broken authentication poses a significant risk to organizations, potentially leading to unauthorized access and data breaches. In the face of this formidable challenge, F5's Access Policy Manager (APM) emerges as a robust and indispensable solution. By seamlessly integrating advanced authentication mechanisms and comprehensive access controls, F5 BIG-IP APM stands as a stalwart guardian against the vulnerabilities associated with broken authentication. This article explores the pivotal role played by BIG-IP APM in fortifying authentication protocols, mitigating risks, and ensuring a resilient defense against unauthorized access, ultimately safeguarding the integrity and security of sensitive data in today's dynamic digital environment. Broken Authentication Authentication mechanism is an exposed target due to the nature of this function, as authentication is the first point of entry to any platform. The difficulty to exploit authentication weaknesses differs based on how the authentication platform is secured. In the current digital era the security perimeters are very fluid, and so are the trust boundries for our authentication platforms those require more cautions from the developers and security architects regarding authentication flows. Not only we need to protect authentication endpoints and flows, but also some overlooked items like forget and reset password endpoints. How can we consider endpoint to be vulnerable? Credential stuffing. Brute force attacks targetting users' accounts. Weak Passwords. Sensitive details in the URL (passwords, Tokens). Allow users sensitive actions without confirmation. No validation for the tokens authenticity. Accept unsigned or weak jwt tokens. No validation for jwt expiration. Use of plain-text, non-encrypted or non-hashed passwords. Use of weak encryption algorithms. Endpoint can access each other without proper authentication. Use weak or predictable tokens for intra-endpoint authentication. Broken Authentication Examples Making use of GraphQL query patching to bypass API ratelimiting and brute force user's login. POST /graphql [ {"query":"mutation{login(username:\"victim\",password:\"password\"){token}}"}, {"query":"mutation{login(username:\"victim\",password:\"123456\"){token}}"}, {"query":"mutation{login(username:\"victim\",password:\"qwerty\"){token}}"}, ... {"query":"mutation{login(username:\"victim\",password:\"123\"){token}}"}, ] Update / modify user's sensitive information without API authorization token. PUT /account Authorization: Bearer <token> { "newpassword": "<new_password>" } BIG-IP APM and Broken Authentication We start with creating our Per-Request policy, this policy works in a different way than the per-session policy, as the flow will be evaluted on a per-request basis, making sure to consider variations throught the session life-time. Below are some of the key benefits: Wide range of Authentication, SSO, and MFA mechanisms to properly identify the initiating machine or user. Ability to integrate with 3rd parties to provide additional enforcement decisions based on the organization's policy. Ability to apply endpoint checks on the client side before session initiation. This goes to BIG-IP in general, the ability to apply custom traffic control on both of the traffic sides, Client and Server. The ability to create whitelist / blacklist for API Access tokens, JSON Web Tokens ID (JTI) or a different element based on the used authentication method, below example steps for JWT: Extract JTI value from Access token. Add JTI value to whether Allow/Block lists. Related Content F5 BIG-IP Access Policy Manager | F5 Introduction to OWASP API Security Top 10 2023 OWASP Top 10 API Security Risks – 2023 - OWASP API Security Top 10 API Protection Concepts OWASP Tactical Access Defense Series: How BIG-IP APM Strengthens Defenses Against OWASP Top 10 OWASP Tactical Access Defense Series: Broken Object Level Authorization and BIG-IP APM F5 Hybrid Security Architectures (Part 5 - F5 XC, BIG-IP APM, CIS, and NGINX Ingress Controller)Crafting Secure Paths: The Intricacies of VPN Solutions on BIG-IP APM
Introduction In this article we are exploring Virtual Private Networks (VPN) solutions on F5 BIG-IP Access Policy Manager (APM), In today's digital landscape, secure connectivity is paramount, and BIG-IP APM stands at the forefront, offering a diverse array of VPN options to suit various needs. In this article, we'll delve into the world of BIG-IP APM VPNs, from their different flavors to the tight integration with other modules that enrich the overall solution. Join us as we unravel the complexities, uncover the nuances, and discover how F5 Networks empowers organizations to craft robust, tailored VPN solutions for their unique requirements. BIG-IP APM VPN Solutions VPN is a mean to connect trusted sites over untrusted medium, a user to a corporate portal, branch to main office or between different data centeres. What makes VPN solutions unique with BIG-IP APM is not just the VPN element but the whole ecosystem within your hands, with multiple Multi-Factor Authenticaiton (MFA) and Single Sign-On (SSO) supported protocols. In addition to tight integration with different modules in BIG-IP. All this gives you as Solution Architect the flexibility to come up with different solutions that suits organizations security posture and expand well in the future for any new requirements. IPSEC VPN You can configure an IPsec tunnel to secure traffic that traverses a wide area network (WAN), from a BIG-IP system to third-party device. You start by configuring an IKE peer to negotiate Phase 1 Internet Security Association and Key Management Protocol (ISAKMP) security associations for the secure channel between two systems. You can also configure a custom traffic selector and a custom IPsec policy that use this secure channel to generate IPsec Tunnel mode (Phase 2) security associations (SAs). While IPSEC is configured via BIG-IP LTM, I've added this one here to cover the different VPN solutions, interesting set of articles already published covering different use cases and troubleshooting items for IPSEC VPN via BIG-IP. BIG-IP to Azure Dynamic IPsec Tunneling Securing ExpressRoute with the BIG-IP and IPsec Simple BIG-IP to BIG-IP, On-prem to Public Cloud IPsec Configuration Guide Understanding IPSec IKEv1 negotiation on Wireshark Understanding IPSec IKEv2 negotiation on Wireshark Passthrough IPSec with AFM SSL VPN Because an SSL VPN uses standard web browsers and technologies, it gives users secure remote access to enterprise applications without requiring the installation and maintenance of separate client software on each user’s computer. Most SSL VPNs also integrate with multiple authentication mechanisms. With the growth of the remote workforce, SSL VPNs are critical to keeping employees connected to the work applications they need—and for IT to ensure that only authorized users gain access. SSL VPNs provide a secure way for your workforce, contractors, and partners worldwide to gain access to sensitive information from virtually any computer or device. Furthermore, they give IT full, granular control over data access. SSL VPNs are becoming more common in the workplace, and the learning curve to implement and use them is minimal. Below are some of the use cases and education resources for VPN deployments via BIG-IP APM. Deploying a VPN on the BIG-IP APM Creating a SSL VPN Using F5 Full Webtop F5 VPN Client from Raspberry Pi SSL VPN Split Tunneling and Office 365 Scaling SSL VPN using BIG-IP Local Traffic Manager (LTM) Rate Limiting SSL VPN User Traffic VPN Split Tunneling: The Benefits and Risks SSL VPN Split Tunneling and Office 365 Remote Desktop Protocol (RDP) using an SSL VPN VPN Access with MFA using Edge Client 7.2.1 and APM 16.0 Connect to the F5 VPN with BIG-IP Edge Client How to optimize SSL VPN connections when BIG-IP is reaching 100% CPU Per-App VPN The Per-Application (Per-App) VPN feature makes sure that specific mobile applications and their data remain secure and protected, and only data relevant from the application is sent to the internal network. With the Per-App VPN capabilities of the BIG-IP APM, combined with a mobile device management (MDM) solution, enterprise organizations can be sure only authenticated and authorized mobile users are able to access and send data to the organization from approved mobile applications or mobile containers. Per-App VPN deploys using an existing MDM solution. Depending on the authentication in use, Per-App VPN can offer a seamless or relatively simple way to access internal resources. You can apply per-user bandwidth policies and ACLs to make sure that users comply with network use policies. Detailed user activity auditing is also possible with ACL logging or solutions based on iRules. You must create the following BIG-IP components for this implementation: A connectivity profile An application tunnel profile (Java and per-App VPN) An MDM-enrolled mobile device An MDM-deployed application BIG-IP Edge Client 2.0.1+ for L3 and Per-App VPN Application tunnel An application tunnel provides secure, application-level TCP/IP connections from the client to the internal network. Application tunnels use iSession, an F5 proprietary protocol for transport. Application tunnels can be started using native Windows binary components or with a browser-based Java applet on Windows, Mac, and Linux platforms. Per-user session-level bandwidth policy and ACLs can be applied to application tunnels. You must create the following BIG-IP components for this implementation: A connectivity profile A full webtop An application tunnel resource An access policy that assigns a webtop and an application tunnel resource Related content Configuring a Per-App VPN Using F5 App Tunnels Deploying a VPN on the BIG-IP APM Creating a SSL VPN Using F5 Full Webtop F5 VPN Client from Raspberry Pi SSL VPN Split Tunneling and Office 365 Scaling SSL VPN using BIG-IP Local Traffic Manager (LTM) How to optimize SSL VPN connections when BIG-IP is reaching 100% CPU BIG-IP to Azure Dynamic IPsec Tunneling Understanding IPSec IKEv1 negotiation on Wireshark Understanding IPSec IKEv2 negotiation on Wireshark Passthrough IPSec with AFM K08200035: Use cases | BIG-IP APM operations guide Configuring IPsec in Tunnel Mode between a Remote Device and BIG-IP using Dynamic Template
APM Cookbook: Single Sign On (SSO) using Kerberos
To get the APM Cookbook series moving along, I’ve decided to help out by documenting the common APM solutions I help customers and partners with on a regular basis. Kerberos SSO is nothing new, but seems to stump people who have never used Kerberos before. Getting Kerberos SSO to work with APM is straight forward once you have the Active Directory components configured. Overview I have a pre-configured web service (IIS 7.5/Sharepoint 2010) that is configured for Windows Authentication, which will send a “Negotiate” in the header of the “401 Request for Authorization”. Make sure the web service is configured to send the correct header before starting the APM configuration by accessing the website directly and viewing the headers using browser tools. In my example, I used the Sharepoint 2010/2013 iApp to build the LTM configuration. I’m using a single pool member, sp1.f5.demo (10.10.30.2) listening on HTTP and the Virtual Server listening on HTTPS performing SSL offload. Step 1 - Create a delegation account on your domain 1.1 Open Active Directory Users and Computers administrative tool and create a new user account. User logon name: host/apm-kcd.f5.demo User logon name (pre-Windows 2000): apm-kcd Set the password and not expire 1.2 Alter the account and set the servicePrincipcalName. Run setspn from the command line: setspn –A host/apm-kcd.f5.demo apm-kcd A delegation tab will now be available for this user. Step 2 - Configure the SPN 2.1 Open Active Directory Users and Computers administrative tool and select the user account created in the previous step. Edit the Properties for this user Select the Delegation tab Select: Trust this user for delegation to specified services only Select: Use any authentication protocol Select Add, to add services. Select Users or Computers… Enter the host name, in my example I will be adding HTTP service for sp1.f5.demo (SP1). Select Check Names and OK Select the http Service Type and OK 2.2 Make sure there are no duplicate SPNs and run setspn –x from the command line. Step 3 - Check Forward and Reverse DNS DNS is critical and a missing PTR is common error I find when troubleshooting Kerberos SSO problems. From the BIG-IP command line test forward and reverse records exist for the web service using dig: # dig sp1.f5.demo ;; QUESTION SECTION: ;sp1.f5.demo. IN A ;; ANSWER SECTION: sp1.f5.demo. 1200 IN A 10.10.30.2 # dig -x 10.10.30.2 ;; QUESTION SECTION: ;2.30.10.10.in-addr.arpa. IN PTR ;; ANSWER SECTION: 2.30.10.10.in-addr.arpa. 1200 IN PTR sp1.f5.demo. Step 4 - Create the APM Configuration In this example I will use a Logon Page to capture the user credentials that will be authenticated against Active Directory and mapped to the SSO variables for the Kerberos SSO. 4.1 Configure AAA Server for Authentication Access Policy >> AAA Servers >> Active Directory >> “Create” Supply the following: Name: f5.demo_ad_aaa Domain Name: f5.demo Domain Controller: (Optional – BIG-IP will use DNS to discover if left blank) Admin Name and Password Select “Finished" to save. 4.2 Configure Kerberos SSO Access Policy >> SSO Configurations >> Kerberos >> “Create” Supply the following: Name: f5.demo_kerberos_sso Username Source: session.sso.token.last.username User Realm Source: session.ad.last.actualdomain Kerberos Realm: F5.DEMO Account Name: apm-kcd (from Step 1) Account Password & Confirm Account Password (from Step1) Select “Finished” to save. 4.3 Create an Access Profile and Policy We can now bring it all together using the Visual Policy Editor (VPE). Access Policy >> Access Profiles >> Access Profile List >> “Create” Supply the following: Name: intranet.f5.demo_sso_ap SSO Configuration: f5.demo_kerberos_sso Languages: English (en) Use the default settings for all other settings. Select “Finished” to save. 4.4 Edit the Access Policy in the VPE Access Policy >> Access Profiles >> Access Profile List >> “Edit” (intranet.f5.demo_sso_ap) On the fallback branch after the Start object, add a Logon Page object. Leave the defaults and “Save”. On the fallback branch after the Logon Page object, add an AD Auth object. Select the Server Select “Save” when your done. On the Successful branch after the AD Auth object, add a SSO Credential Mapping object. Leave the defaults and “Save”. On the fallback branch after the SSO Credential Mapping, change Deny ending to Allow. The finished policy should look similar to this: Don't forget to “Apply Access Policy”. Step 5 – Attach the APM Policy to the Virtual Server and Test 5.1 Edit the Virtual Server Local Traffic >> Virtual Servers >> Virtual Server List >> intranet.f5.demo_vs Scroll down to the Access Policy section and select the Access Profile. Select “Update” to save. 5.2 Test Open a browser, access the Virtual Server URL (https://intranet.f5.demo in my example), authenticate and verify the client is automatically logged on (SSO) to the web service. To verify Kerberos SSO has worked correctly, check /var/log/apm on APM by turning on debug. You should see log events similar to the ones below when the BIG-IP has fetched a Kerberos Ticket. info websso.1[9041]: 014d0011:6: 33186a8c: Websso Kerberos authentication for user 'test.user' using config '/Common/f5.demo_kerberos_sso' debug websso.1[9041]: 014d0018:7: sid:33186a8c ctx:0x917e4a0 server address = ::ffff:10.10.30.2 debug websso.1[9041]: 014d0021:7: sid:33186a8c ctx:0x917e4a0 SPN = HTTP/sp1.f5.demo@F5.DEMO debug websso.1[9041]: 014d0023:7: S4U ======> ctx: 33186a8c, sid: 0x917e4a0, user: test.user@F5.DEMO, SPN: HTTP/sp1.f5.demo@F5.DEMO debug websso.1[9041]: 014d0001:7: Getting UCC:test.user@F5.DEMO@F5.DEMO, lifetime:36000 debug websso.1[9041]: 014d0001:7: fetched new TGT, total active TGTs:1 debug websso.1[9041]: 014d0001:7: TGT: client=apm-kcd@F5.DEMO server=krbtgt/F5.DEMO@F5.DEMO expiration=Tue Apr 29 08:33:42 2014 flags=40600000 debug websso.1[9041]: 014d0001:7: TGT expires:1398724422 CC count:0 debug websso.1[9041]: 014d0001:7: Initialized UCC:test.user@F5.DEMO@F5.DEMO, lifetime:36000 kcc:0x92601e8 debug websso.1[9041]: 014d0001:7: UCCmap.size = 1, UCClist.size = 1 debug websso.1[9041]: 014d0001:7: S4U ======> - NO cached S4U2Proxy ticket for user: test.user@F5.DEMO server: HTTP/sp1.f5.demo@F5.DEMO - trying to fetch debug websso.1[9041]: 014d0001:7: S4U ======> - NO cached S4U2Self ticket for user: test.user@F5.DEMO - trying to fetch debug websso.1[9041]: 014d0001:7: S4U ======> - fetched S4U2Self ticket for user: test.user@F5.DEMO debug websso.1[9041]: 014d0001:7: S4U ======> trying to fetch S4U2Proxy ticket for user: test.user@F5.DEMO server: HTTP/sp1.f5.demo@F5.DEMO debug websso.1[9041]: 014d0001:7: S4U ======> fetched S4U2Proxy ticket for user: test.user@F5.DEMO server: HTTP/sp1.f5.demo@F5.DEMO debug websso.1[9041]: 014d0001:7: S4U ======> OK! Conclusion Like I said in the beginning, once you know how Kerberos SSO works with APM, it’s a piece of cake!
