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.
Enhanced security with F5 BIG-IP APM and Okta through Multi-Factor Authentication
This article is the third in the three-part series. Go to Part 1 here: Secure Access to Web Applications with F5 and Okta using SAML 2.0 (1 of 2) Go to Part 2 here: Secure Access to Web Applications with F5 and Okta using SAML 2.0 (2 of 2) Multi-factor Authentication (MFA) is a security best practice that enhances authentication by requesting two or more verifiable authentication factors. Common authentication factors are: Something You Know, Something You Have, and Something You Are. In addition to configuring native MFA support, the F5 BIG-IP Access Policy Manager (APM) system offers the flexibility to combine multiple authentication mechanisms from partners like Okta. In this DevCentral blog, we will look at how to configure APM for Okta MFA to authenticate using Something You Know and Something You Have. The HTTP connector for Okta MFA is supported in F5 BIG-IP APM system running TMOS v16.0 or later. Setting up Okta MFA Follow the steps below to configure ‘Okta Verify’ for mobile MFA. Navigate to Okta web UI >> Security >> Multifactor and activate Okta Verify. Figure 1: Activate Okta Verify MFA Click on the Factor Enrollment option in the sub menu, then click on the Edit button. On the popup screen, choose Everyone option under Assign to groups. When done, press the Update Policy button. Figure 2: Assign the MFA policy to the user group Configuring F5 BIG-IP APM for Okta MFA Follow the steps below to configure the HTTP connector for Okta MFA. Create a DNS Resolver to Resolve the DNS Queries and Cache the Results On the main menu, navigate to Network >> DNS Resolvers. On the DNS Resolvers web page, click on the Create button. Enter a name and click the Finished button. On the DNS Resolvers web page, click on the above created DNS resolver list name. Navigate to the Forward Zones tab in the sub menu to add any recursive nameservers. When done, press the Finished button. Figure 3: Create the DNS resolver Creating an HTTP Connector and Assign the DNS Resolver Navigate to Access >> Authentication >> HTTP Connector and click on HTTP Connector Transport. On the HTTP Connector Transport web page, click on the Create button. Enter a name and select the above created DNS Resolver and the SSL Server Profile. When done, press the Save button. Figure 4: Sample HTTP connector configuration Creating the Okta Connector and Assigning the HTTP Connector Navigate to Access >> Authentication and click on Okta Connector. On the Okta Connector web page click on the Create button. Enter a name and select the above created HTTP connector. Type the Okta Domain name and paste the Okta API Token from Okta. When done, press the Save button. Figure 5: Sample Okta connector configuration Note: To create a new Okta API token, navigate to Okta web UI >> Security >> API and click on Tokens. Creating and assigning the Access profile and Access Policy to the Application Follow the steps below to create an access profile and per-request access policy for Okta MFA and assign them to the application. Creating the Access Profile and Access Policy Navigate to Access >> Profiles/Policies and click on Access profiles (Per Session Policies). click on the Create button to create a new access profile. Enter a name and select All in the Profile Type drop down-list. Scroll down to the Language Settings section. Select the preferred language and move it to the left into Accepted Languages box. When done, press the Finished button. Figure 6: Sample access profile configuration Next, navigate to Access >> Profiles/Policies and click on Per-Request Policies. Click on Create button to create a new access policy. Enter a name and select All in the Profile Type drop down list. Scroll down to the Language Settings section. Select the preferred language and move it to the left into Accepted Languages box. When done, click on Finished button. On the Per-Request Policies page, click the Edit button next to the above created policy. Create the per-request policy using the Visual Policy Editor as show in the figure 7. Figure 7: Sample per-request policy To add the Okta MFA, click on the + sign. On the popup screen, click on the Authentication tab and select Okta MFA. When done, click on the Add Item button. On the popup screen, enter a name and choose the above configured Okta connector. When done, click the Save button. Figure 8: Sample Okta MFA configuration with ‘Okta Connector’ assigned Assigning the Access Profile and Access Policy to the Virtual Server Navigate to Local Traffic >> Virtual Servers >> Virtual Server List and click on the Virtual server configured for the application. Scroll down to the Access Policy section and select the Access Profile and the Per-request Policy. When done, press the Update button. Figure 9: Assign the access profile and per-request policy to the virtual server Validating and Verifying the Solution Follow the steps below to setup and validate mobile MFA using ‘Okta Verify’. Download the ‘Okta Verify’ app on your mobile device. Login to Okta Web UI using your username and password. On the dashboard, click on the user setting. Under the extra verification section, click on the Setup button. On the resulting web page, click on Configure Factor and choose the Device Type (Android or Apple). Scan the presented barcode with the Okta mobile app for verification, this completes the setup. Access the application app.f5sec.net from a browser. When prompted enter the username and password. After successful authentication, you will be prompted for MFA, click on the Send Push button. Complete the MFA using the Okta Verify app on your mobile device. Figure 10: User prompted for MFA after successful authentication Conclusion The joint F5 and Okta MFA integration offers a compelling solution for customers who are interested in securely accessing enterprise applications on-premises and in any cloud by increasing the assurance of authentication. Additional Resources Part 1 - Secure Access to Web Applications with F5 and Okta using SAML 2.0 Part 2 - Secure Access to Web Applications with F5 and Okta using SAML 2.0 BIG-IP APM Product Information: Knowledge Center Free Training Course: Getting Started with BIG-IP Access Policy Manager (APM) Lightboard Lesson: F5 Access Policy Manager and Okta - Single Sign On and Multi-Factor Authentication External Resource: F5 | Okta partnershipAPM Cookbook: Okta MFA Integration
Since the launch of the Okta and F5 Integration Guide I've seen interest in leveraging this partnership take off. One aspect I've enjoyed is watching how customers address pain points they were not able to address previously. For example, providing multi-factor authentication (MFA) for Microsoft Exchange Outlook Web Access (OWA). This particular customer standardized on Okta's MFA solution but OWA was behind Microsoft Threat Management Gateway (TMG) and could not easily integrate with Okta. For this solution F5's Access Policy Manager (APM) will replace the TMG servers and leverage Okta's on-premises RADIUS agent for MFA via Okta Verify, which supports push notification - by far my favorite feature. I've included a video below that walks through the process of configuring Okta for RADIUS based multifactor as well as configuring APM to leverage Okta's RADIUS agent. https://youtu.be/jpoVo0nuilQ?list=PLAVmgu9Rja5Cyu7KhQ3CUJFNOI5Tr-Wk2 Okta Configuration On the Okta administrator portal you'll need to create a new Okta Sign-on policy: Security -> Policies. Once you name the new policy you'll need to add a rule: The crucial part here is to select RADIUS for the And Authenticates via option. F5 Configuration The F5 APM configuration is pretty straight forward since you can use the built-in VPE macro template for RADIUS authentication but we'll need to create a RADIUS AAA object first. Once the RADIUS AAA object is created go ahead and create a new Access Profile and customize your VPE as shown below - for detailed steps please watch the attached video. Pretty easy solution and we're just scratching the surface on what is possible. Can't wait to start playing with Okta's API via iRules LX!
