ADFS Proxy Replacement on F5 BIG-IP
BIG-IP Access Policy Manager can now replace the need for Web Application Proxy servers providing security for your modern AD FS deployment with MS-ADFSPIP support released in BIG-IP v13.1. This article will provide a one stop shop for you to gather information on the solution and leverage it in your environment. What is an AD FS Proxy? AD FS proxies are Windows servers that provide access to external users to the AD FS farm in the internal network. This is done on a server called a Web Application Proxy (WAP). More recent versions of Active Directory Federation Services require the proxy to support MS-ADFSPIP (ADFS Proxy Integration Protocol) which involves client certificate auth between proxy and AD FS, trust establishment, header injection, and more. As noted above, BIG-IP APM v13.1 has support for MS-ADFSPIP. You can see Microsoft’s notes on this and supported third party proxies here, noting that F5 is on the list. Here’s a typical ADFS deployment: So what does BIG-IP do for me? Glad you asked! Here’s an example of the single tier deployment architecture. You can also split these roles into a two tier architecture. As you can see, BIG-IP is taking the roles of both load balancer and the web application proxies protecting AD FS. In this diagram we’re adding additional security with Advanced WAF, DDoS, and Network Firewall services. You can see the F5/Microsoft announcement at Ignite hereabout this new feature. If you want to understand more about the architecture, check out John Wagnon’s awesome lightboard lesson here. How do I deploy it? There are a few ways to do it. The simplest is with the latest iApp template to help you deploy everything, available from https://downloads.f5.com. Make sure you’re using at least v1.2.0rc6. You can also get the related deployment guide here. If you want to deploy manually, there are instructions in the deployment guide. The support article here also covers basic deployment and how the pieces work. Who doesn’t love reading support articles? For the admin the new feature comes down to this amazing simple checkbox: Checking a box and entering credentials is WAY easier than deploying multiple Windows servers, configuring them as WAPs, establishing trust, then maintaining and securing them going forward. Access Policy Manager will maintain that trust, exchanging certificates automatically before they expire with AD FS. Note that no access profile is assigned above. If you want one to add more security flexibility then the access profile is supported as well. Check the deployment guide for requirements. If you don’t use one, no access sessions are used. Here’s a quick video explaining the solution and demoing deployment using the iApp. What else can I do? You can add more security using access profiles to add preauthentication, multifactor, etc. A basic access policy (with Azure MFA optional) is included in the iApp. Also included in the iApp is network firewall policy deployment. You can add Advanced WAF features like brute force, credential stuffing, bot protection, and more if desired too.
Understanding IPSec IKEv2 negotiation on Wireshark
Related Articles: Understanding IPSec IKEv1 negotiation on Wireshark 1 The Big Picture There are just 4 messages: Summary: IKE_SA_INIT: negotiate security parameters to protect the next 2 messages (IKE_AUTH) Also creates a seed key (known as SKEYSEED) where further keys are produced: SK_e (encryption): computed for each direction (one for outbound and one for inbound) to encrypt IKE_AUTH messages SK_a (authentication): computed for each direction (one for outbound and one for inbound) to hash (using HMAC) IKE_AUTH messages SK_d (derivation): handed to IPSec to generate encryption and optionally authentication keys for production traffic IKE_AUTH: negotiates security parameters to protect production traffic (CHILD_SA) More specifically, the IPSec protocol used (ESP or AH - typically ESP as AH doesn't support encryption),the Encryption algorithm (AES128? AES256?) and Authentication algorithm (HMAC_SHA256? HMAC_SHA384?). 2 IKE_SA_INIT First the Initiator sends aSecurity Association—>Proposal—>Transform,Transform... payloads which contains the required security settings to protectIKE_AUTHphase as well as to generate the seed key (SK_d) for production traffic (child SA): In this case here the Initiator only sent one option for Encryption, Integrity, Pseudo-Random Function (PRF) and Diffie Hellman group so there are only 4 corresponding transforms but there could be more. Responder picked the 4 available security options also confirmed inSecurity Association—>Proposal—>Transform,Transform… payloads as seen above. 3 IKE_AUTH These are immediately applied to next 2IKE_AUTHmessages as seen below: The above payload is Encrypted using SK_e and Integrity-protected using SK_a (these keys are different for each direction). The firstIKE_AUTHmessage negotiates the security parameters for production traffic (child SAs), authenticates each side and informs what is the source/destination IP/Port that is supposed to go through IPSec tunnel: Now, lastIKE_AUTHmessage sent by Responder confirms which security parameters it picked (Security Associationmessage), repeats the sameTraffic Selectormessages (if correctly configured) and sends hash of message using pre-master key (Authenticationmessage) Note that I highlighted 2 Notify messages. TheINITIAL_CONTACTsignals to Initiator that this is the onlyIKE_SAcurrently active between these peers and if there is any otherIKE_SAit should be terminated in favour of this one. TheSET_WINDOW_SIZEis a flow control mechanism introduced in IKEv2 that allows the other side to send as many outstanding requests as the other peer wants within the window size without receiving any message acknowledging the receipt. From now on, if additional CHILD_SAs are needed, a message calledCREATE_CHILD_SAcan be used to establish additional CHILD_SAs It can also be used to rekeyIKE_SAwhereNotificationpayload is sent of typeREKEY_SAfollowed byCREATE_CHILD_SAwith new key information so new SA is established and old one is subsequently deleted.
APM variable assign examples
Problem this snippet solves: APM variable assign is a powerful tool to manipulate APM variable during policy evaluation supporting tcl code. On Devcentral answers, there are lots of variable assignment done with irule event ACCESS_POLICY_AGENT_EVENT. these snippets show how to do the same as irule without irule event. Note : I wrote most of codes, some others are from threads I found in DevCentral Answers section. How to use this snippet: create a variable assign box in VPE, then Add new entry In left side, let custom variable / unsecure default choice set the new variable name (or name of the variable you want to change the value). you should use bold value above tcl code. for timeout changes, you must use bold value above tcl code. In expression : let custom expression default choice paste provided code Username / Domain management session.logon.last.username extract CN from certificate subject and set it in username variable set subject [split [mcget {session.ssl.cert.subject}] ",="]; foreach {name value} $subject { if {[string trim $name] equals "CN"} { return [string trim $value]; } } session.logon.last.username combine username and domain variables expr{"[mcget{session.logon.last.domain}]\\[mcget{session.logon.last.username}]"} session.logon.last.ntdomain extract NT domain name from logon name if { [mcget {session.logon.last.username}] contains "\\" } { set username [string tolower [mcget {session.logon.last.logonname}]]; return [string range $username 0 [expr {[string first "\\" $username] -1}] ]; } else { return {} } one-line code expr {[set username [string tolower [mcget {session.logon.last.logonname}]]] contains "\\" ? [string range $username 0 [expr {[string first "\\" $username] -1}] ] : "" } session.logon.last.domain static assignment from ntdomain switch[stringtolower[mcget{session.logon.last.ntdomain}]]{ "domain1"{return "domain1.local"} "domain2"{return "domain2.local"} default{return "default.local" } } session.logon.last.username Extract username name from logonname (full username from logon page even if split domain from username is checked) setusername[stringtrim[mcget{session.logon.last.logonname}]]; if{$usernamecontains"\\"}{ return[stringrange$username[expr{[stringfirst"\\"$username]+1}]end]; }else{return$username} session.logon.last.upn Extract UPN value from Certificate X509Extension setextension[stringtolower[mcget{session.ssl.cert.x509extension}]]; return[stringrange$extension[expr{[stringfirst"othername:upn<"$extension]+14}][expr{[stringlast">"$extension]-1}]]; session timeout management session.inactivity_timeout Change inactivity session timeout based on a checkbox on the logon page (logon variable trusted) if { [mcget {session.logon.last.trusted}] == 1 } { return {5400} } else { return {1800} } one-line code (5400 seconds if condition before ? success, 1800 seconds else) expr { [mcget {session.logon.last.trusted}] == 1 ? {5400} : {1800}} session.inactivity_timeout Change inactivity session timeout based on client type (iOS, Android and WindowsPhone : half of inactivity timeout configured in profile parameters) expr { [mcget {session.client.platform}] == "WindowsPhone" || [mcget {session.client.platform}] == "Android" || [mcget {session.client.platform}] == "iOS" ? [mcget {session.inactivity_timeout}]/2 : [mcget {session.inactivity_timeout}] } session.max_session_timeout force to close the session à 17:00 expr { [clock scan "17:00"] - [mcget {session.user.starttime}] } session.max_session_timeout After a AD query which retreive attribute logonHours, force to close the session when user at the end of allowed logon hours set maximumSessionSeconds 604800 if {[set logonHours [mcget {session.ad.last.attr.logonHours}]] != "" && $logonHours != "FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF"} { #convert string to binary string binary scan [binary format H* $logonHours] b* logon_hours_binary_string # evaluate the number of seconds from last sunday set time_from_sunday [expr {[clock seconds] - [clock scan "last sunday"]}]; # search in string next hours with 0 value set current_index [expr {$time_from_sunday / 3600}]; # convert the index to number of seconds from last sunday if {[set next_denied_index [string first 0 $logon_hours_binary_string$logon_hours_binary_string $current_index]] == $current_index } {return 0} # evaluate number on seconds to disconnect time return [expr { $next_denied_index*3600 - $time_from_sunday}] } else { return $maximumSessionSeconds} Windows Info session.windows_info_os.last.fqdn search and return FQDN hostname in computer names list after windows Info Box foreach x [split [mcget {session.windows_info_os.last.computer}] "|"] { if { $x ends_with ".f5demo.lab" } { return $x } } session.windows_info_os.last.computer_name search FQDN hostname in computer names list after windows Info Box, then return shortname (without domain name) foreach x [split [mcget {session.windows_info_os.last.computer}] "|"] { if { $x ends_with ".f5demo.lab" } { return [lindex [split $x "."] 0] } } Machine cert To allow machine certificate revocation validation, add a variable assign with 2 following variables before OCSP or CRLDP boxes. session.ssl.cert.whole store machine certificate as it was user certificate expr {[mcget {session.check_machinecert.last.cert.cert}]} session.ssl.cert.certissuer store machine certificate issuer as it was user certificate issuer expr {[mcget {session.check_machinecert.last.cert.issuer}]} HTTP auth returned cookie parsing session.custom.http_auth_mycookie extract from HTTP auth cookie list the cookie value of mycookie expr { [lindex [regexp -inline {mycookie=([^;\\\r]*)} [mcget session.http.last.response_cookie]] 1] } replace portal or network access Webtop by full webtop if unsupported resource are assigned Webtop can be: Portal webtop : define an internal web server as home page Network access Webtop : start automatically Network access when connected Full Webtop : display all assigned ressources in one page hosted on the F5. Some customers want to assign different webtop based on assigned ressources. one portal ressource only -> portal webtop one Network access ressource only -> Network Access ressource more than one portal ressource -> Full webtop more than one Network access ressource -> Full webtop RDP, Application tunnel, SAML ressources assigned -> Full Webtop In Advanced ressource assign, the last assigned webtop is applied to the session. If the user is assigned non portal ressource (ex : RDP) and portal webtop, he will not be allowed to connect. session.assigned.webtop this code code is used if portal or network access webtop are assigned and number of resources is supported only with full webtop set fullwt /Common/wt-Full; set wt [mcget {session.assigned.webtop}]; set pa [llength [mcget {session.assigned.resources.pa}]]; set at [llength [mcget {session.assigned.resources.at}]]; set na [llength [mcget {session.assigned.resources.na}]]; set rd [llength [mcget {session.assigned.resources.rd}]]; set saml [llength [mcget {session.assigned.resources.saml}]]; if {$rd || $at || $saml || ([expr { $pa + $na }] > 1)} {set wt $fullwt}; unset fullwt; unset pa; unset at; unset na; unset rd; unset saml; return $wt; one-line code. Don't forget to replace "/Common/wt-Full" with your own webtop full in expression. expr { [llength [concat [mcget {session.assigned.resources.rd}] [mcget {session.assigned.resources.at}] [mcget {session.assigned.resources.atsaml}]]] || [llength [concat [mcget {session.assigned.resources.pa}] [mcget {session.assigned.resources.na}]]] >1 ? "/Common/wt-Full" : [mcget {session.assigned.webtop}]} Same condition for Advanced resource Assign condition. This condition doesn't match with previous rules in the same Advanced resource assign. must be in a dedicated resource assign box. expr { [llength [concat [mcget {session.assigned.resources.rd}] [mcget {session.assigned.resources.at}] [mcget {session.assigned.resources.atsaml}]]] || [llength [concat [mcget {session.assigned.resources.pa}] [mcget {session.assigned.resources.na}]]] >1} For Kerberos SSO when working with Kerberos SSO, 2 variable sources must be set: username : must be equal to user sAMAccountName domain : must be equal to user FQDN domain When working on access policy with multiple SSO method depending on the URI, Host header or some other parameters, you may have conflict on default SSO variables. For example, for Exchange : activesync SSO profile is basic with username format is NTDOMAIN\username Autodiscover SSP profile can be NTLM with username format is username domain format is NTDOMAIN OWA SSO profile can be kerberos with username : must be equal to user sAMAccountName domain : must be equal to user FQDN domain like DOMAIN.LOCAL (different than NT Domain) default SSO variables are : session.sso.token.last.username session.sso.token.last.password session.logon.last.domain to support multiple SSO on the same Access policy, I recommende to set new variables based on previous AD Query session.krbsso.username expr {[mcget {session.ad.last.attr.sAMAccountName}]} session.krbsso.domain expr {[mcget {session.ad.last.actualdomain}]} Code : No code
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. Note: The variables used in the below example are global, which may affect your performance. Refer to the K95240202: Understanding iRule variable scope article for further information on global variables, and determine if you use a local variable for your implementation. proc randAZazStr {len} { return [subst [string repeat {[format %c [expr {int(rand() * 26) + (rand() > .5 ? 97 : 65)}]]} $len]] } proc getClientId { return <Duo Client ID> } proc getExpiryTime { set exp [clock seconds] set exp [expr $exp + 900] return $exp } proc getJwtHeader { return "{\"alg\":\"HS512\",\"typ\":\"JWT\"}" } proc getJwkName { return <JSON Web Key> #e.g. return "/Common/duo_jwk" } proc createJwt {duo_uname} { set header [call getJwtHeader] set exp [call getExpiryTime] set client_id [call getClientId] set redirect_uri "https://" set redirect [ACCESS::session data get "session.server.network.name"] append redirect_uri $redirect append redirect_uri "/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 [call getJwkName] ] return $jwt_duo } proc createJwtToken { set header [call getJwtHeader] set exp [call getExpiryTime] set client_id [call getClientId] set aud "<Duo API Hostname>/oauth/v1/token" #Example: set aud https://api-duohostname.com/oauth/v1/token set jti [call randAZazStr 32] set payload "{\"sub\": \"${client_id}\",\"iss\":\"${client_id}\",\"aud\":\"${aud}\",\"exp\":${exp},\"jti\":\"${jti}\"}" set jwt_duo [ ACCESS::oauth sign -header $header -payload $payload -alg HS512 -key [call getJwkName] ] return $jwt_duo } when ACCESS_POLICY_AGENT_EVENT { set irname [ACCESS::policy agent_id] if { $irname eq "JWT_CREATE" } { set ::duo_uname [ACCESS::session data get "session.logon.last.username"] ACCESS::session data set session.custom.jwt_duo [call createJwt $::duo_uname] ACCESS::session data set session.custom.jwt_duo_token [call createJwtToken] } } when ACCESS_PER_REQUEST_AGENT_EVENT { set irname [ACCESS::perflow get perflow.irule_agent_id] if { $irname eq "JWT_CREATE" } { set ::duo_uname [ACCESS::session data get "session.logon.last.username"] ACCESS::perflow set perflow.custom [call createJwt $::duo_uname] ACCESS::perflow set perflow.scratchpad [call createJwtToken] } } 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-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. Anormal 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.Two-Factor Authentication With Google Authenticator And APM
Introduction Two-factor authentication (TFA) has been around for many years and the concept far pre-dates computers. The application of a keyed padlock and a combination lock to secure a single point would technically qualify as two-factor authentication: “something you have,” a key, and “something you know,” a combination. Until the past few years, two-factor authentication in its electronic form has been reserved for high security environments: government, banks, large companies, etc. The most common method for implementing a second authentication factor has been to issue every employee a disconnected time-based one-time password hard token. The term “disconnected” refers to the absence of a connection between the token and a central authentication server. A “hard token” implies that the device is purpose-built for authentication and serves no other purpose. A soft or “software” token on the other hand has other uses beyond providing an authentication mechanism. In the context of this article we will refer to mobile devices as a soft tokens. This fits our definition as the device an be used to make phone calls, check email, surf the Internet, all in addition to providing a time-based one-time password. A time-based one-time password (TOTP) is a single use code for authenticating a user. It can be used by itself or to supplement another authentication method. It fits the definition of “something you have” as it cannot be easily duplicated and reused elsewhere. This differs from a username and password combination, which is “something you know,” but could be easily duplicated by someone else. The TOTP uses a shared secret and the current time to calculate a code, which is displayed for the user and regenerated at regular intervals. Because the token and the authentication server are disconnected from each other, the clocks of each must be perfectly in sync. This is accomplished by using Network Time Protocol (NTP) to synchronize the clocks of each device with the correct time of central time servers. Using Google Authenticator as a soft token application makes sense from many angles. It is low cost due to the proliferation of smart phones and is available from the “app store” free of charge on all major platforms. It uses an open standard (defined by RFC 4226), which means that it is well-tested, understood, secure. Calculation as you will later see is well-documented and relatively easy to implement in your language of choice (iRules in our case). This process is explained in the next section. This Tech Tip is a follow-up to Two-Factor Authentication With Google Authenticator And LDAP. The first article in this series highlighted two-factor authentication with Google Authenticator and LDAP on an LTM. In this follow-up, we will be covering implementation of this solution with Access Policy Manager (APM). APM allows for far more granular control of network resources via access policies. Access policies are rule sets, which are intuitively displayed in the UI as flow charts. After creation, an access policy is applied to a virtual server to provide security, authentication services, client inspection, policy enforcement, etc. This article highlights not only a two-factor authentication solution, but also the usage of iRules within APM policies. By combining the extensibility of iRules with the APM’s access policies, we are able to create virtually any functionality we might need. Note: A 10-user fully-featured APM license is included with every LTM license. You do not need to purchase an additional module to use this feature if you have less than 10 users. Calculating The Google Authenticator TOTP The Google Authenticator TOTP is calculated by generating an HMAC-SHA1 token, which uses a 10-byte base32-encoded shared secret as a key and Unix time (epoch) divided into a 30 second interval as inputs. The resulting 80-byte token is converted to a 40-character hexadecimal string, the least significant (last) hex digit is then used to calculate a 0-15 offset. The offset is then used to read the next 8 hex digits from the offset. The resulting 8 hex digits are then AND’d with 0x7FFFFFFF (2,147,483,647), then the modulo of the resultant integer and 1,000,000 is calculated, which produces the correct code for that 30 seconds period. Base32 encoding and decoding were covered in my previous Tech Tip titled Base32 Encoding And Decoding With iRules . The Tech Tip details the process for decoding a user’s base32-encoded key to binary as well as converting a binary key to base32. The HMAC-SHA256 token calculation iRule was originally submitted by Nat to the Codeshare on DevCentral. The iRule was slightly modified to support the SHA-1 algorithm, but is otherwise taken directly from the pseudocode outlined in RFC 2104. These two pieces of code contribute the bulk of the processing of the Google Authenticator code. The rest is done with simple bitwise and arithmetic functions. Triggering iRules From An APM Access Policy Our previously published Google Authenticator iRule combined the functionality of Google Authenticator token verification with LDAP authentication. It was written for a standalone LTM system without the leverage of APM’s Visual Policy Editor. The issue with combining these two authentication factors in a single iRule is that their functionality is not mutually exclusive or easily separable. We can greatly reduce the complexity of our iRule by isolating functionality for Google Authenticator token verification and moving the directory server authentication to the APM access policy. APM iRules differ from those that we typically develop for LTM. iRules assigned to LTM virtual server are triggered by events that occur during connection or payload handling. Many of these events still apply to an LTM virtual server with an APM policy, but do not have perspective into the access policy. This is where we enter the realm of APM iRules. APM iRules are applied to a virtual server exactly like any other iRule, but are triggered by custom iRule event agent IDs within the access policy. When the access policy reaches an iRule event, it will trigger the ACCESS_POLICY_AGENT_EVENT iRule event. Within the iRule we can execute the ACCESS::policy agent_id command to return the iRule event ID that triggered the event. We can then match on this ID string prior to executing any additional code. Within the iRule we can get and set APM session variables with the ACCESS::session command, which will serve as our conduit for transferring variables to and from our access policy. A visual walkthrough of this paragraph is shown below. iRule Trigger Process Create an iRule Event in the Visual Policy Editor Specify a Name for the object and an ID for the Custom iRule Event Agent Create an iRule with the ID referenced and assign it to the virtual server 1: when ACCESS_POLICY_AGENT_EVENT { 2: if { [ACCESS::policy agent_id] eq "ga_code_verify" } { 3: # get APM session variables 4: set username [ACCESS::session data get session.logon.last.username] 5: 6: ### Google Authenticator token verification (code omitted for brevity) ### 7: 8: # set APM session variables 9: ACCESS::session data set session.custom.ga_result $ga_result 10: } 11: } Add branch rules to the iRule Event which read the custom session variable and handle the result Google Authenticator Two-Factor Authentication Process Two-Factor Authentication Access Policy Overview Rather than walking through the entire process of configuring the access policy from scratch, we’ll look at the policy (available for download at the bottom of this Tech Tip) and discuss the flow. The policy has been simplified by creating macros for the redundant portions of the authentication process: Google Authenticator token verification and the two-factor authentication processes for LDAP and Active Directory. The “Google Auth verification” macro consists of an iRule event and 5 branch rules. The number of branch rules could be reduced to just two: success and failure. This would however limit our diagnostic capabilities should we hit a snag during our deployment, so we added logging for all of the potential failure scenarios. Remember that these logs are sent to APM reporting (Web UI: Access Policy > Reports) not /var/log/ltm. APM reporting is designed to provide per-session logging in the user interface without requiring grepping of the log files. The LDAP and Active Directory macros contain the directory server authentication and query mechanisms. Directory server queries are used to retrieve user information from the directory server. In this case we can store our Google Authenticator key (shared secret) in a schema attribute to remove a dependency from our BIG-IP. We do however offer the ability to store the key in a data group as well. The main portion of the access policy is far simpler and easier to read by using macros. When the user first enters our virtual server we look at the Landing URI they are requesting. A first time request will be sent to the “normal” logon page. The user will then input their credentials along with the one-time password provided by the Google Authenticator token. If the user’s credentials and one-time password match, they are allowed access. If they fail the authentication process, we increment a counter via a table in our iRule and redirect them back to an “error” logon page. The “error” logon page notifies them that their credentials are invalid. The notification makes no reference as to which of the two factors they failed. If the user exceeds the allowed number of failures for a specified period of time, their session will be terminated and they will be unable to login for a short period of time. An authenticated user would be allowed access to secured resources for the duration of their session. Deploying Google Authenticator Token Verification This solution requires three components (one optional) for deployment: Sample access policy Google Authenticator token verification iRule Google Authenticator token generation iRule (optional) The process for deploying this solution has been divided into four sections: Configuring a AAA server Login to the Web UI of your APM From the side panel select Access Policy > AAA Servers > Active Directory, then the + next to the text to create a new AD server Within the AD creation form you’ll need to provide a Name, Domain Controller, Domain Name, Admin Username, and Admin Password When you have completed the form click Finished Copy the iRule to BIG-IP and configure options Download a copy of the Google Authenticator Token Verification iRule for APM from the DevCentral CodeShare (hint: this is much easier if you “edit” the wiki page to display the source without the line numbers and formatting) Navigate to Local Traffic > iRules > iRule List and click the + symbol Name the iRule '”google_auth_verify_apm,” then copy and paste the iRule from the CodeShare into the Definition field At the top of the iRule there are a few options that need to be defined: lockout_attempts - number of attempts a user is allowed to make prior to being locked out temporarily (default: 3 attempts) lockout_period - duration of lockout period (default: 30 seconds) ga_code_form_field - name of HTML form field used in the APM logon page, this field is define in the "Logon Page" access policy object (default: ga_code_attempt) ga_key_storage - key storage method for users' Google Authenticator shared keys, valid options include: datagroup, ldap, or ad (default: datagroup) ga_key_ldap_attr - name of LDAP schema attribute containing users' key ga_key_ad_attr - name of Active Directory schema attribute containing users' key ga_key_dg - data group containing user := key mappings Click Finished when you’ve configured the iRule options to your liking Import sample access policy From the Web UI, select Access Policy > Access Profiles > Access Profiles List In the upper right corner, click Import Download the sample policy for Two-Factor Authentication With Google Authenticator And APM and extract the .conf from ZIP archive Fill in the New Profile Name with a name of your choosing, then select Choose File, navigate to the extracted sample policy and Open Click Import to complete the import policy The sample policy’s AAA servers will likely not work in your environment, from the Access Policy List, click Edit next to the imported policy When the Visual Policy Editor opens, expand the macro (LDAP or Active Directory auth) that describe your environment Click the AD Auth object, select the AD server from the drop-down that was defined earlier in the AAA Servers step, then click Save Repeat this process for the AD Query object Assign sample policy and iRule to a virtual server From the Web UI, select Local Traffic > Virtual Servers > Virtual Server List, then the create button (+) In the New Virtual Server form, fill in the Name, Destination address, Service Port (should be HTTPS/443), next select an HTTP profile and anSSL Profile (Client). Next you’ll add a SNAT Profile if needed, an Access Profile, and finally the token verification iRule Depending on your deployment you may want to add a pool or other network connectivity resources Finally click Finished At this point you should have a function virtual server that is serving your access policy. You’ll now need to add some tokens for your users. This process is another section on its own and is listed below. Generating Software Tokens For Users In addition to the Google Authenticator Token Verification iRule for APM we also wrote a Google Authenticator Soft Token Generator iRule that will generate soft tokens for your users. The iRule can be added directly to an HTTP virtual server without a a pool and accessed directly to create tokens. There are a few available fields in the generator: account, pre-defined secret, and a QR code option. The “account” field defines how to label the soft token within the user’s mobile device and can be useful if the user has multiple soft token on the same device (I have 3 and need to label them to keep them straight). A 10-byte string can be used as a pre-defined secret for conversion to a base32-encoded key. We will advise you against using a pre-defined key because a key known to the user is something they know (as opposed to something they have) and could be potentially regenerate out-of-band thereby nullifying the benefits of two-factor authentication. Lastly, there is an option to generate a QR code by sending an HTTPS request to Google and returning the QR code as an image. While this is convenient, this could be seen as insecure since it may wind up in Google’s logs somewhere. You’ll have to decide if that is a risk you’re willing to take for the convenience it provides. Once the token has been generated, it will need to be added to a data group on the BIG-IP: Navigate to Local Traffic > iRules > Data Group Lists Select Create from the upper right-hand corner if the data group does not yet exist. If it exists, just select it from the list. Name the data group “google_auth_keys” (data group name can be changed in the beginning section of the iRule) The type of data group will be String Type the “username” into the String field and paste the “Google Authenticator key” into the Value field Click Add and the username/key pair should appear in the list as such: user := ONSWG4TFOQYTEMZU Click Finished when all your username/key pairs have been added. Your user can scan the QR code or type it into their device manually. After they scan the QR code, the account name should appear along with the TOTP for the account. The image below is how the soft token appears in the Google Authenticator iPhone application: Once again, do not let the user leave with a copy of the plain text key. Knowing their key value will negate the value of having the token in the first place. Once the key has been added to the BIG-IP, the user’s device, and they’ve tested their access, destroy any reference to the key outside the BIG-IPs data group.If you’re worried about having the keys in plain text on the BIG-IP, they can be encrypted with AES or stored off-box in LDAP and only queried via secure connection. This is beyond the scope of this article, but doable with iRules. Code Google Authenticator Token Verification iRule for APM – Documentation and code for the iRule used in this Tech Tip Google Authenticator Soft Token Generator iRule – iRule for generating soft tokens for users Sample Access Policy: Two-Factor Authentication With Google Authenticator And APM – APM access policy Reference Materials RFC 4226 - HOTP: An HMAC-Based One-Time Password Algorithm RFC 2104 - HMAC: Keyed-Hashing for Message Authentication RFC 4648 - The Base16, Base32, and Base64 Data Encodings SOL3122: Configuring the BIG-IP system to use an NTP server using the Configuration utility – Information on configuring time servers Configuration Guide for BIG-IP Access Policy Manager – The “big book” on APM configurations Configuring Authentication Using AAA Servers – Official F5 documentation for configuring AAA servers for APM Troubleshooting AAA Configurations – Extra help if you hit a snag configuring your AAA server
Azure Active Directory and BIG-IP APM Integration
Introduction Security is one of the primary considerations for organizations in determining whether or not to migrate applications to the public cloud. The problem for organizations with applications in the cloud, in a data center, managed, or as a service, is to create a cost-effective hybrid architecture that produces secure application access and a great experience that allows users to access apps easily, have consistent user experiences, and enjoy easy access with single-sign-on (SSO) tied to a central identity and authentication strategy. Some applications are not favorable to modernization. There are applications that are not suited for, or incapable of, cloud migration. Many on-premises apps do not support modern authentication and authorization, including standards and protocols such as SAML, OAuth, or OpenID Connect (OIDC). An organization may not have the staff talent or time to perform application modernization for their on-premises apps. With thousands of apps in use daily, hosted in all or any combination of these locations, how can organizations ensure secure, appropriate user access without requiring users to login in multiple times? In addition, how can organizations terminate user access to each application without having to access each app individually? By deploying Microsoft Azure Active Directory, Microsoft’s comprehensive cloud-based identity platform, along with F5’s trusted application access solution, Access Policy Manager (APM), organizations are able to federate user identity, authentication, and authorization and bridge the identity gap between cloud-based (IaaS), SaaS, and on-premises applications. Figure 1Secure hybrid application access This guide discusses the following use cases: ·Users use single sign-on to access applications requires Kerberos-based authentication. ·Users use single sign-on to access applications requires header-based authentication. Microsoft Azure Active Directory and F5 BIG-IP APM Design For organizations with a high security demand with low risk tolerance, the need to keep all aspects of user authentication on premise is required. The Microsoft Azure Active Directory and F5 BIG-IP APM solution integrates directly into AAD configured to work cooperatively with an existing Kerberos based, header based or variety of authentication methods. The solution has these components: •BIG-IP Access Policy Manager (APM) •Microsoft Domain Controller/ Active Directory (AD) •Microsoft Azure Active Directory (AAD) •Application (Kerberos-/header-based authentication) Figure 2APM bridge SAML to Kerberos/header authentication components Figure 3APM bridge SAML to Kerberos authentication process flow Deploying Azure Active Directory and BIG-IP APM integration The joint Microsoft and F5 solution allow legacy applications incapable of supporting modern authentication and authorization to interoperate with Azure Active Directory. Even if an app doesn’t support SAML, and only is able to support header- or Kerberos-based authentication, it can still be enabled with single sign-on (SSO) and support multi-factor authentication (MFA) through the F5 APM and Azure Active Directory combination. Azure Active Directory as an IDaaS delivers a trusted root of identity to APM creating a bridge between modern and legacy applications, delivering SSO and securing the app with MFA. Adding F5 from the gallery To configure the integration of BIG-IP APM into Azure AD, you need to add F5 from the gallery to your list of managed SaaS apps. Sign-on to theAzure portalusing either a work or school account, or a personal Microsoft account. On the left navigation pane, select theAzure Active Directoryservice. Navigate toEnterprise Applicationsand then selectAll Applications. To add new application, selectNew application. In theAdd from the gallerysection, typeF5in the search box. SelectF5from results panel and then add the app. Wait a few seconds while the app is added to your tenant. Configuring Microsoft Azure Active Directory Configure and test Azure AD SSO with F5 using a test user calledA.Vandelay. For SSO to work, you need to establish a link relationship between an Azure AD user and the related user in F5. To configure and test Azure AD SSO with F5, complete the following building blocks: Configure Azure AD SSO - to enable your users to use this feature. Create an Azure AD test user - to test Azure AD single sign-on with A.Vandelay. Assign the Azure AD test user - to enable A.Vandelay to use Azure AD single sign-on. Configure Azure AD SSO Follow these steps to enable Azure AD SSO in the Azure portal. In theAzure portal, on theF5application integration page, find theManagesection and selectsingle sign-on. On theSelect a single sign-on methodpage, selectSAML. On theSet up single sign-on with SAMLpage, click the edit/pen icon forBasic SAML Configurationto edit the settings. On theBasic SAML Configurationsection, if you wish to configure the application inIDPinitiated mode, enter the values for the following fields: In theIdentifiertext box, type a URL using the following pattern:https://<YourCustomFQDN>.f5.com/ In theReply URLtext box, type a URL using the following pattern:https://<YourCustomFQDN>.f5.com/ ClickSet additional URLsand perform the following step if you wish to configure the application inSPinitiated mode: In theSign-on URLtext box, type a URL using the following pattern:https://<YourCustomFQDN>.f5.com/ Note These values are for only used for illustration. Replace these them with the actual Identifier, Reply URL and Sign-on URL. Refer to the patterns shown in theBasic SAML Configurationsection in the Azure portal. On theSet up single sign-on with SAMLpage, in theSAML Signing Certificatesection, findFederation Metadata XMLand selectDownloadto download the certificate and save it on your computer. On theSet up F5section, copy the appropriate URL(s) based on your requirement. Create an Azure AD test user In this section, you'll create a test user in the Azure portal called A.Vandelay. From the left pane in the Azure portal, selectAzure Active Directory, selectUsers, and then selectAll users. SelectNew userat the top of the screen. In theUserproperties, follow these steps: In theNamefield, enterA.Vandelay. In theUser namefield, enter the username@companydomain.extension. For example,A.Vandelay@contoso.com. Select theShow passwordcheck box, and then write down the value that's displayed in thePasswordbox. ClickCreate. Assign the Azure AD test user In this section, you'll enable A.Vandelay to use Azure single sign-on by granting access to F5. In the Azure portal, selectEnterprise Applications, and then selectAll applications. In the applications list, selectF5. In the app's overview page, find theManagesection and selectUsers and groups. SelectAdd user, then selectUsers and groupsin theAdd Assignmentdialog. In theUsers and groupsdialog, selectA.Vandelayfrom the Users list, then click theSelectbutton at the bottom of the screen. If you're expecting any role value in the SAML assertion, in theSelect Roledialog, select the appropriate role for the user from the list and then click theSelectbutton at the bottom of the screen. In theAdd Assignmentdialog, click theAssignbutton. Configure F5 BIG-IP APM Configure your on-premise applications based on the authentication type. Configure F5 single sign-on for Kerberos-based application Open your browser and access BIG-IP. You need to import the Metadata Certificate into the F5 (Kerberos) which will be used later in the setup process. Go toSystem > Certificate Management > Traffic Certificate Management >> SSL Certificate List. Click onImportof the right-hand corner. Additionally you also need anSSL Certificatefor the Hostname (Kerbapp.superdemo.live), in this example we used Wildcard Certificate. Go to –F5 BIG-IP Click Access > Guided Configuration > Federation > SAML Service Provider. Specify theEntity ID(same as what you configured on the Azure AD Application Configuration). Create a new Virtual Server, Specify theDestination Address. Choose theWild Card Certificate(orCertyou uploaded for the Application) that we uploaded earlier and theAssociated Private Key. Upload the ConfigurationMetadataand Specify a newName for SAML IDP Connectorand you will also need to specify the Federation Certificate that was uploaded earlier. Create NewBackend App Pool, specify theIP Address(s)of the Backend Application Servers. UnderSingle Sign-on Settings, chooseKerberosand SelectAdvanced Settings. The request needs to be created inuser@domain.suffix. Under theusername sourcespecifysession.saml.last.attr.name.http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname. Refer Appendix for complete list of variables and values. Account Name Is the F5 Delegation Account Created ( Check F5 Documentation). Under Endpoint Checks Properties , click Save & Next. Under Timeout Settings, leave default settings and click Save & Next. Review Summaryand click onDeploy. Configure F5 single sign-on for Header-based application Open your browser and access BIG-IP. You need to import the Metadata Certificate into the F5 (Header Based) which will be used later in the setup process. Go toSystem > Certificate Management > Traffic Certificate Management >> SSL Certificate List. Click onImportof the right-hand corner. Additionally you also need anSSL Certificatefor the Hostname (headerapp.superdemo.live), in this example we used Wildcard Certificate. Go to –F5 (Header Based) BIG-IP Click Access > Guided Configuration > Federation > SAML Service Provider. Specify theEntity ID(same as what you configured on the Azure AD Application Configuration). Create a new Virtual Server, Specify theDestination Address,Redirect Portis Optional. Choose theWild Card Certificate(orCertyou uploaded for the Application) that we uploaded earlier and theAssociated Private Key. Upload the ConfigurationMetadataand Specify a newName for SAML IDP Connectorand you will also need to specify the Federation Certificate that was uploaded earlier. Create NewBackend App Pool, specify theIP Address(s)of the Backend Application Servers. Under Single Sign-on, ChooseHTTP header-based. You can add other Headers based on your application. See the Appendix for the list of SAMLSession Variables. Under Endpoint Checks Properties , click Save & Next. Under Timeout Settings, leave default settings and click Save & Next. Review Summaryand click onDeploy. Resources BIG-IP Knowledge Center BIG-IP APM Knowledge Center Configuring Single Sign-On with Access Policy Manager Summary By centralizing access to all your applications, you can manage them more securely. Through the F5 BIG-IP APM and Azure AD integration, you can centralize and use single sign-on (SSO) and multi-factor authentication for on-premise applications. Validated Products and Versions Product BIG-IP APM Version 15.0APM 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-pathparameter 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 wouldlike 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 Preactwith 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 useuser-common.jsto load a tracker such as Google Analytics. Example: Google Analytics Customization Types There are two broad categories for the customization of APM objects: Resources areAssigned 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-Resourceseach 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 syntaxand 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 forresourcesdisplayed 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, clickAccess > 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 thePublicly Accessible URIcolumn. 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 Preactcomponent 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 Preactand 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 Preactdevelopment. 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 Preactcoding 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=84430607What is BIG-IP APM?
tl;dr - BIG-IP APM provides granular access controls to discreet applications and networks supporting 2FA and federated identity management. Providing application access is a complicated process. You have distributed users, insecure clients, and unknown devices all vying for connectivity to your trusted applications.What's an admin to do in order to protect investments and still provide easy access anywhere? F5'sBIG-IP Access Policy Manager (APM) provides multiple services to protect and manage access to your applications. APM is available on hardware, in the cloud, or as a virtual appliance and provides access control wherever your applications live. APM offers: Identity Federation and SSO - Creates a single point of policy-based access for cloud and on premise/private applications with MFA support. Client and Web-based SSL VPN Access - Policy-based access to network VPN service through web-plugins or clients on mobile and desktop operating systems. Web Portal Access to Applications - Open web applications to users instead of opening up your network. Great for contractors and remote workers who don't need full VPN tunnels. Desktop Application and VDI Support - Policy-based access to virtualized applications through a single, consolidated gateway along with native VDI support and a customizable, web portal. Access Policy Deployment and Management Solutions - Using the visual policy editor, administrators create highly customizable security policesallowing granular control over application and network access. Secure Web Gateway Proxy Services - Provides web-based malware protection and URL filtering through Secure Web Gateway Services. Policy Access Made Easy (or complex if you want) I said policy-based a lot, didn't I? Well, I repeat myself because it's an important part of access management. You want the right users accessing the right apps... right? The Visual Policy Editor allows administrators granular control over who has what access to individual applications, instead of full network access. Below is an example of a basic SAML access policy using Active Directory to not only initiate allowed authentication but the queries AD to determine if the user is allowed to access to selected SaaS resources assigned to this policy. BIG-IP APM also integrates withother F5 solutions to aid in application and user security. BIG-IP Application Security Manager (ASM) - Include web application firewall functionality allowing your application security visibility into who's using it (and if they should be). Software Web Gateway (SWG) - Combined with APM, you can create access controlled URL categorization. Combining APM with SWGallows for greater transparency and control to your users browsing and application access. BIG-IQ - Centralize your policy management, distribution, and access monitoring into one location. BIG-IQ becomes your window into your vast BIG-IP APM network. BIG-IP APM offers a lot of flexibility for user access and security control but don't just take my word for it. This article provides you a very general overview of what APM is and what is can do for you. Follow the below links to see real scenarios of APM in use and learn more about why access control and security is a good thing. And as alwaysif you have questions or comments drop us a line! On DevCentral: Strong Authentication Two-Factor Authentication - Remote Desktop Gateway Configuration Examples: BIG-IP APM as SAML IdP for AWS Two-Factor Authentication: Captive Portal On F5.com: Getting Started with BIG-IP Access Policy Manager (APM)
SSL VPN Split Tunneling and Office 365
UPDATE: Apr 9, 2020 A colleague, Vinicius M. , put together a Configuration guide: Optimizing Office 365 traffic on Remote Access through VPNs when using BIG-IP APM.pdf As we shift to a much larger remote workforce than ever before, additional strains are being placed on the remote access infrastructure of many organizations around the world. Over the past several weeks we have seen organizations adapt quickly, and as it relates to APM, implement split tunneling configurations to specifically allow Office 365 traffic to egress a client's local interface instead of the corporate network via the VPN tunnel. Microsoft publishes their Office 365 endpoints (URLs & IPs) via an API but occasionally they make changes and keeping on top of those changes can be an administrative nightmare. To make the ongoing maintenance of the Network Access Lists / split tunneling configuration as seamless as possible, I’ve adapted a Python script (see GitHubRepo) we commonly use for SSL Orchestrator deployments to fetch Office 365 endpoints and update one or more Network Access Lists. Used in conjunction with iCall, this script will periodically check for and apply updates to your Network Access List(s) without any administrative intervention, allowing you to focus on other mission critical tasks. The script is maintained and documented in this GitHub repository: https://github.com/f5regan/o365-apm-split-tunnel Microsoft has provided us with a statement concerning their recommendations for Office 365 and split tunneling: "Microsoft recommends excluding traffic destined to key Office 365 services from the scope of VPN connection by configuring split tunneling using published IPv4 and IPv6 address ranges. For best performance and most efficient use of VPN capacity, traffic to these dedicated IP address ranges associated with Office 365 Exchange Online, SharePoint Online and Microsoft Teams (referred to as Optimize category in Microsoft documentation) should be routed directly, outside of the VPN tunnel. Please refer to Microsoft guidance for more detailed information about this recommendation." Microsoft’s recommendations have been incorporated into the script published in the aforementioned GitHub repository. See the changelog for details. More Resources In addition to considering how the steps in this article may relieve some strain on your organization’s remote access infrastructure, I’d highly recommend visiting How to optimize SSL VPN connections when BIG-IP is reaching 100% CPU for further guidance on optimizing SSL VPN connections.
