Configure F5 BIG-IP Access Policy Manager for form-based SSO
Learn to configure F5 BIG-IP Access Policy Manager (APM) and Microsoft Entra ID for secure hybrid access (SHA) to form-based applications. BIG-IP published services for Microsoft Entra single sign-on (SSO) has benefits:
- Improved Zero Trust governance through Microsoft Entra preauthentication and Conditional Access
- Full SSO between Microsoft Entra ID and BIG-IP published services
- Managed identities and access from one control plane
- See the Microsoft Entra admin center
For the scenario, there's an internal legacy application configured for form-based authentication (FBA). Ideally, Microsoft Entra ID manages application access, because legacy lacks modern authentication protocols. Modernization takes time and effort, introducing the risk of downtime. Instead, deploy a BIG-IP between the public internet and the internal application. This configuration gates inbound access to the application.
With a BIG-IP in front of the application, you can overlay the service with Microsoft Entra preauthentication and header-based SSO. The overlay improves application security posture.
The SHA solution has the following components:
- Application - BIG-IP published service protected by SHA.
- The application validates user credentials against Active Directory
- Use any directory, including Active Directory Lightweight Directory Services, open source, and so on
- Microsoft Entra ID - Security Assertion Markup Language (SAML) identity provider (IdP) that verifies user credentials, Conditional Access, and SSO to the BIG-IP.
- With SSO, Microsoft Entra ID provides attributes to the BIG-IP, including user identifiers
- BIG-IP - reverse-proxy and SAML service provider (SP) to the application.
- BIG-IP delegating authentication to the SAML IdP then performs header-based SSO to the back-end application.
- SSO uses the cached user credentials against other forms-based authentication applications
SHA supports SP- and IdP-initiated flows. The following diagram illustrates the SP-initiated flow.
- User connects to application endpoint (BIG-IP).
- BIG-IP APM access policy redirects user to Microsoft Entra ID (SAML IdP).
- Microsoft Entra preauthenticates user and applies enforced Conditional Access policies.
- User is redirected to BIG-IP (SAML SP) and SSO occurs using issued SAML token.
- BIG-IP prompts the user for an application password and stores it in the cache.
- BIG-IP sends a request to the application and receives a sign on form.
- The APM scripting fills in the username and password, then submits the form.
- The web server serves application payload and sends it to the client.
You need the following components:
- An Azure subscription
- If you don't have one, get an Azure free account
- One of the following roles: Global Administrator, Cloud Application Administrator, or Application Administrator
- A BIG-IP or deploy a BIG-IP Virtual Edition (VE) in Azure
- Any of the following F5 BIG-IP license SKUs:
- F5 BIG-IP® Best bundle
- F5 BIG-IP Access Policy Manager™ (APM) standalone license
- F5 BIG-IP Access Policy Manager™ (APM) add-on license on a BIG-IP F5 BIG-IP® Local Traffic Manager™ (LTM)
- 90-day BIG-IP full feature trial. See Free Trials
- User identities synchronized from an on-premises directory to Microsoft Entra ID
- An SSL certificate to publish services over HTTPS, or use default certificates while testing
- See SSL profile
- A form-based authentication application, or set up an IIS FBA app for testing
The configuration in this article is a flexible SHA implementation: manual creation of BIG-IP configuration objects. Use this approach for scenarios the Guided Configuration templates don't cover.
Replace example strings or values with those from your environment.
Register F5 BIG-IP in Microsoft Entra ID
Steps in this article may vary slightly based on the portal you start from.
BIG-IP registration is the first step for SSO between entities. The app you create from the F5 BIG-IP gallery template is the relying party, representing the SAML SP for the BIG-IP published application.
- Sign in to the Microsoft Entra admin center as at least a Cloud Application Administrator.
- Browse to Identity > Applications > Enterprise applications > All applications.
- In the All applications pane, select New application.
- The Browse Microsoft Entra Gallery pane opens.
- Tiles appear for cloud platforms, on-premises applications, and featured applications. Featured applications icons indicate support of federated SSO and provisioning.
- In the Azure gallery, search for F5.
- Select F5 BIG-IP APM Azure AD integration.
- Enter a Name the new application uses to recognize the application instance.
- Select Add.
- Select Create.
Enable SSO to F5 BIG-IP
Configure the BIG-IP registration to fulfill SAML tokens that BIG-IP APM requests.
- In left menu, in the Manage section, select Single sign-on.
- The Single sign-on pane appears.
- On the Select a single sign-on method page, select SAML.
- Select No, I'll save later.
- On the Set up single sign-on with SAML pane, select the pen icon.
- For Identifier, replace the value with the BIG-IP published application URL.
- For Reply URL, replace the value, but retain the path for the application SAML SP endpoint. With this configuration, SAML flow operates in IdP-initiated mode. Microsoft Entra ID issues a SAML assertion, then the user is redirected to the BIG-IP endpoint.
- For SP-initiated mode, for Sign on URL, enter the application URL.
- For Logout Url, enter the BIG-IP APM single logout (SLO) endpoint prepended by the service host header. Then, BIG-IP APM user sessions end when they sign out of Microsoft Entra ID.
From Traffic Management Operating System (TMOS) v16 onward, the SAML SLO endpoint is
- Select Save.
- Close the SAML configuration pane.
- Skip the SSO test prompt.
- Make a note of the User Attributes & Claims section properties. Microsoft Entra ID issues the properties for BIG-IP APM authentication, and SSO to the back-end application.
- On the SAML Signing Certificate pane, select Download.
- The Federation Metadata XML file is saved to your computer.
Microsoft Entra SAML signing certificates have a lifespan of three years.
Assign users and groups
Microsoft Entra ID issues tokens for users granted access to an application. To grant specific users and groups application access:
- On the F5 BIG-IP application's overview pane, select Assign Users and groups.
- Select + Add user/group.
- Select the users and groups you want.
- Select Assign.
BIG-IP advanced configuration
Use the following instructions to configure BIG-IP.
Configure SAML service provider settings
SAML SP settings define the SAML SP properties that the APM uses to overlay the legacy application with SAML preauthentication. To configure them:
Select Access > Federation > SAML Service Provider.
Select Local SP Services.
On the Create New SAML SP Service pane, for Name and Entity ID, enter the defined name and entity ID.
SP Name Settings values are required if the entity ID doesn't match the hostname portion of the published URL. Or, values are required if the entity ID isn't in regular hostname-based URL format.
If the entity ID is
urn:myvacation:contosoonline, enter the application external scheme and hostname.
Configure an external IdP connector
A SAML IdP connector defines settings for the BIG-IP APM to trust Microsoft Entra ID as its SAML IdP. The settings connect the SAML service provider to a SAML IdP, which establishes the federation trust between the APM and Microsoft Entra ID.
To configure the connector:
Select the new SAML service provider object.
Select Bind/UnbBind IdP Connectors.
In the Create New IdP Connector list, select From Metadata.
On the Create New SAML IdP Connector pane, browse for the Federation Metadata XML file you downloaded.
Enter an Identity Provider Name for the APM object that represents the external SAML IdP. For example, MyVacation_AzureAD.
Select Add New Row.
Select the new SAML IdP Connector.
Configure forms-based SSO
Create an APM SSO object for FBA SSO to back-end applications.
Perform FBA SSO in client-initiated mode or BIG-IP-initiated mode. Both methods emulate a user sign-on by injecting credentials into the username and password tags. The form is then autosubmitted. Users provide password to access an FBA application. The password is cached and reused for other FBA applications.
Select Access > Single Sign-on.
Select Forms Based.
For Name, enter a descriptive name. For example, Contoso\FBA\sso.
For Use SSO Template, select None.
For Username Source, enter the username source to prefill the password collection form. The default
session.sso.token.last.usernameworks well, because it has the signed-in user Microsoft Entra UPN.
For Password Source, keep the default
session.sso.token.last.password, the APM variable BIG-IP uses to cache user passwords.
For Start URI, enter the FBA application logon URI. If the request URI matches this URI value, the APM form-based authentication executes SSO.
For Form Action, leave it blank. Then, the original request URL is used for SSO.
For Form Parameter for Username, enter the sign in form username field element. Use the browser dev tools to determine the element.
For Form Parameter for Password, enter the sign in form password field element. Use the browser dev tools to determine the element.
To learn more, go to techdocs.f5.com for Manual Chapter: Single sign-on methods.
Configure an access profile
An access profile binds the APM elements that manage access to BIG-IP virtual servers, including access policies, SSO configuration, and UI settings.
Select Access > Profiles / Policies.
Select Access Profiles (Per-Session Policies).
Enter a Name.
For Profile Type, select All.
For SSO Configuration, select the FBA SSO configuration object you created.
For Accepted Language, select at least one language.
In the Per-Session Policy column, for the profile, select Edit.
The APM Visual Policy Editor starts.
Under fallback, select the + sign.
- In the pop-up, select Authentication.
- Select SAML Auth.
- Select Add Item.
- On SAML authentication SP, change the Name to Microsoft Entra auth.
- In the AAA Server dropdown, enter the SAML service provider object you created.
- On the Successful branch, select the + sign.
- In the pop-up, select Authentication.
- Select Logon Page.
- Select Add Item.
- For usesrname, in the Read Only column, select Yes.
For the sign in page fallback, select the + sign. This action adds an SSO credential mapping object.
In the pop-up, select the Assignment tab.
Select SSO Credential Mapping.
Select Add Item.
On Variable Assign: SSO Credential Mapping, keep the default settings.
In the upper Deny box, select the link.
The Successful branch changes to Allow.
(Optional) Configure attribute mappings
You can add a LogonID_Mapping configuration. Then, the BIG-IP active sessions list has the signed-in user UPN, not a session number. Use this information for analyzing logs or troubleshooting.
For the SAML Auth Successful branch, select the + sign.
In the pop-up, select Assignment.
Select Variable Assign.
Select Add Item.
On the Properties tab, enter a Name. For example, LogonID_Mapping.
Under Variable Assign, select Add new entry.
For Custom Variable, use
For Session Variable, user
Select Apply Access Policy.
Close the Visual Policy Editor.
Configure a back-end pool
To enable BIG-IP to forward client traffic correctly, create a BIG-IP node object that represents the back-end server that hosts your application. Then, place that node in a BIG-IP server pool.
Select Local Traffic > Pools.
Select Pool List.
Enter a Name for a server pool object. For example, MyApps_VMs.
For Node Name, enter a server display name. This server hosts the back-end web application.
For Address, enter the application server host IP address.
For Service Port enter the HTTP/S port the application is listening on.
Health monitors require configuration this article doesn't cover. Go to support.f5.com for K13397: Overview of HTTP health monitor request formatting for the BIG-IP DNS system.
Configure a virtual server
A virtual server is a BIG-IP data-plane object represented by a virtual IP address. The server listens for client requests to the application. Any received traffic is processed and evaluated against the APM access profile associated with the virtual server. The traffic is directed according to policy.
To configure a virtual server:
Select Local Traffic > Virtual Servers.
Select Virtual Server List.
Enter a Name.
For Destination Address/Mask, select Host and enter an IPv4 or IPv6 address. The address receives client traffic for the published back-end application.
For Service Port, select Port, enter 443, and select HTTPS.
For HTTP Profile (Client), select http.
For SSL Profile (Client), select the profile you created, or leave the default for testing. This option enables a virtual server for Transport Layer Security (TLS) to publish services over HTTPS.
For Source Address Translation, select Auto Map.
Under Access Policy, in the Access Profile box, enter the name you created. This action binds the Microsoft Entra SAML preauthentication profile and FBA SSO policy to the virtual server.
- Under Resources, for Default Pool, select the back-end pool objects you created.
- Select Finished.
Configure session management settings
BIG-IP session management settings define conditions for sessions termination and continuation. Create policy in this area.
- Go to Access Policy.
- Select Access Profiles.
- Select Access Profile.
- From the list, select your application.
If you defined a single logout URI value in Microsoft Entra ID, IdP-initiated sign out from MyApps ends the client and the BIG-IP APM session. The imported application federation metadata XML file provides the APM with the Microsoft Entra SAML endpoint for SP-initiated sign out. Ensure the APM responds correctly to a user sign out.
If there's no BIG-IP web portal, users can't instruct the APM to sign out. If the user signs out of the application, BIG-IP is oblivious. The application session can be reinstated through SSO. For SP-initiated sign out, ensure sessions terminate securely.
You can add an SLO function to your application sign out button. This function redirects the client to the Microsoft Entra SAML sign out endpoint. To locate SAML sign out endpoint, go to App Registrations > Endpoints.
If you can't change the app, have the BIG-IP listen for the app sign out call and trigger SLO.
- K42052145: Configuring automatic session termination (logout) based on a URI-referenced file name
- K12056: Overview of the Logout URI Include option
Your application is published and accessible with SHA with the app URL or Microsoft portals.
The application appears as a target resource in Conditional Access. Learn more: Building a Conditional Access policy.
For increased security, block direct access to the application, enforcing a path through the BIG-IP.
With a browser, connect to the application external URL, or in My Apps, select the application icon.
Authenticate to Microsoft Entra ID.
You’re redirected to the BIG-IP endpoint for the application.
The password prompt appears.
The APM fills the username with the UPN from Microsoft Entra ID. The username is read-only for session consistency. Hide this field, if needed.
The information is submitted.
You're signed in to the application.
When troubleshooting, consider the following information
BIG-IP performs FBA SSO as it parses the sign in form at the URI
- BIG-IP seeks the username and password element tags from your configuration
Ensure element tags are consistent, or SSO fails
Complex forms generated dynamically might require dev tool analysis to understand the sign in form
Client-initiated is better for sign in pages with multiple forms
Both FBA SSO methods optimize user experience and security by hiding form interactions:
- You can validate if the credentials are injected
- In client-initiated mode, disable form autosubmission in your SSO profile
- Use dev tools to disable the two style properties that prevent the sign in page from appearing
Increase log verbosity
BIG-IP logs contain information to isolating authentication and SSO issues. Increase the log verbosity level:
- Go to Access Policy > Overview.
- Select Event Logs.
- Select Settings.
- Select the row of your published application.
- Select Edit.
- Select Access System Logs.
- In the SSO list, select Debug.
- Select OK.
- Reproduce the issue.
- Review the logs.
Revert the settings otherwise there's excessive data.
BIG-IP error message
If a BIG-IP error appears after Microsoft Entra preauthentication, the issue might relate to Microsoft Entra ID and BIG-IP SSO.
- Go to Access > Overview.
- Select Access reports.
- Run the report for the last hour.
- Review the logs for clues.
Use the View session variables link for your session to determine if the APM receives expected Microsoft Entra claims.
No BIG-IP error message
If no BIG-IP error message appears, the issue might relate to the back-end request, or BIG-IP-to-application SSO.
- Select Access Policy > Overview.
- Select Active Sessions.
- Select the active session link.
Use the View Variables link in this location to help determine root cause, particularly if the APM fails to obtain correct user identifier and password.
To learn more, go to techdocs.f5.com for Manual Chapter: Session Variables.