Tutorial: Configure F5 BIG-IP’s Access Policy Manager for header-based SSO
In this article, you’ll learn to implement Secure Hybrid Access (SHA) with single sign-on (SSO) to header-based applications using F5’s BIG-IP advanced configuration.
Configuring BIG-IP published applications with Azure AD provides many benefits, including:
Improved Zero trust governance through Azure AD pre-authentication and Conditional Access
Full Single sign-on (SSO) between Azure AD and BIG-IP published services.
Manage identities and access from a single control plane, the Azure portal
To learn about all of the benefits, see the article on F5 BIG-IP and Azure AD integration and what is application access and single sign-on with Azure AD.
Scenario description
For this scenario, we have a legacy application using HTTP authorization headers to control access to protected content.
Ideally, application access should be managed directly by Azure AD but being legacy it lacks any form of modern authentication protocol. Modernization would take considerable effort and time, introducing inevitable costs and risk of potential downtime. Instead, a BIG-IP deployed between the public internet and the internal application will be used to gate inbound access to the application.
Having a BIG-IP in front of the application enables us to overlay the service with Azure AD pre-authentication and header-based SSO, significantly improving the overall security posture of the application.
Scenario architecture
The secure hybrid access solution for this scenario is made up of:
Application: BIG-IP published service to be protected by and Azure AD SHA.
Azure AD: Security Assertion Markup Language (SAML) Identity Provider (IdP) responsible for verification of user credentials, Conditional Access (CA), and SSO to the BIG-IP. Through SSO, Azure AD provides the BIG-IP with any required session attributes including user identifiers.
BIG-IP: Reverse proxy and SAML service provider (SP) to the application, delegating authentication to the SAML IdP, before performing header-based SSO to the backend application.

| Step | Description |
|---|---|
| 1. | User connects to application's SAML SP endpoint (BIG-IP). |
| 2. | BIG-IP APM access policy redirects user to Azure AD (SAML IdP). |
| 3. | Azure AD pre-authenticates user and applies any enforced CA policies. |
| 4. | User is redirected to BIG-IP (SAML SP) and SSO is performed using issued SAML token. |
| 5. | BIG-IP injects Azure AD attributes as headers in request to the application. |
| 6. | Application authorizes request and returns payload. |
Prerequisites
Prior BIG-IP experience isn't necessary, but you'll need:
An Azure AD free subscription or above
An existing 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 an existing BIG-IP F5 BIG-IP® Local Traffic Manager™ (LTM)
90-day BIG-IP full feature trial license.
User identities synchronized from an on-premises directory to Azure AD
An account with Azure AD application admin permissions
SSL certificate for publishing services over HTTPS or use default certificates while testing
An existing header-based application or setup a simple IIS header app for testing
BIG-IP configuration methods
There are many methods to configure BIG-IP for this scenario, including two template-based options and an advanced configuration. This article covers the advanced approach, which provides a more flexible way of implementing SHA by manually creating all BIG-IP configuration objects. You would also use this approach for scenarios that the guided configuration templates don't cover.
Note
All example strings or values in this article should be replaced with those for your actual environment.
Adding F5 BIG-IP from the Azure AD gallery
Setting up a SAML federation trust between BIG-IP APM and Azure AD is one of the first step in implementing SHA. It establishes the integration required for BIG-IP to hand off pre-authentication and conditional access to Azure AD, before granting access to the published service.
Sign-in to the Azure AD portal using an account with application administrative rights.
From the left navigation pane, select the Azure Active Directory service
Go to Enterprise Applications and from the top ribbon select + New application
Search for F5 in the gallery and select F5 BIG-IP APM Azure AD integration
Provide a name for the application, followed by Add/Create to add it to your tenant. The name should reflect that specific service.
Configure Azure AD SSO
With the new F5 application properties in view, go to Manage > Single sign-on
On the Select a single sign-on method page, select SAML and skip the prompt to save the single sign-on settings by selecting No, I'll save later
On the Set up single sign-on with SAML blade, select the pen icon for Basic SAML Configuration to provide the following:
a. Replace the pre-defined Identifier URL with the URL for your BIG-IP published service. For example,
https://mytravel.contoso.comb. Do the same with the Reply URL but include the path for the APM's SAML endpoint. For example,
https://mytravel.contoso.com/saml/sp/profile/post/acsNote
In this configuration the SAML flow would operate in IdP initiated mode, where Azure AD issues the user with a SAML assertion before they are redirected to the BIG-IP service endpoint for the application. The BIG-IP APM supports both, IdP and SP initiated modes.
c. For the
Logout URIenter the BIG-IP APM Single Logout (SLO) endpoint pre-pended by the host header of the service being published. Providing an SLO URI ensures the user's BIG-IP APM session has ended after being signed out of Azure AD. For example,https://mytravel.contoso.com/saml/sp/profile/redirect/slr
Note
From TMOS v16 the SAML SLO endpoint has changed to
/saml/sp/profile/redirect/slo.Select Save before exiting the SAML configuration blade and skip the SSO test prompt
Select the pen icon to edit the User Attributes & Claims > + Add new claim
Set the claim properties with the following then select Save
Property Description Name Employeeid Source attribute user.employeeid 
Select + Add a group claim and select Groups assigned to the application > Source Attribute > sAMAccountName

Save the configuration and close the blade
Observe the properties of the User Attributes & Claims section. Azure AD will issue users these properties for BIG-IP APM authentication and SSO to the backend application:

Feel free to add any other specific claims your BIG-IP published application might expect as headers. Any claims defined in addition to the default set will only be issued if they exist in Azure AD. In the same way, Directory roles or group memberships also need defining against a user object in Azure AD before they can be issued as a claim.
In the SAML Signing Certificate section, select the Download button to save the Federation Metadata XML file to your computer.

SAML signing certificates created by Azure AD have a lifespan of three years and should be managed using the published guidance.
Azure AD authorization
By default, Azure AD will only issue tokens to users that have been granted access to an application.
In the application's configuration view, select Users and groups.
Select + Add user and in the Add Assignment blade select Users and groups.
In the Users and groups dialog, add the groups of users authorized to access the internal header-based application, followed by Select > Assign
This completes the Azure AD part of the SAML federation trust. The BIG-IP APM can now be set up to publish the internal web application and configured with a corresponding set of properties to complete the trust for SAML pre-authentication.
Advanced configuration
SAML configuration
The following steps create the BIG-IP SAML service provider and corresponding SAML IdP objects required to complete federating the published application, with Azure AD.
Select Access > Federation > SAML Service Provider > Local SP Services > Create

Provide a Name and the exact same Entity ID defined in Azure AD earlier

SP Name Settings are only required if the entity ID isn't an exact match of the hostname portion of the published URL, or equally if it isn't in regular hostname-based URL format. Provide the external scheme and hostname of the application being published if entity ID is
urn:mytravel:contosoonline.Scroll down to select the new SAML SP object and select Bind/UnBind IdP Connectors.

Select Create New IdP Connector and from the drop-down menu choose From Metadata

Browse to the federation metadata XML file you downloaded earlier and provide an Identity Provider Name for the APM object that will represent the external SAML IdP. For example,
MyTravel_AzureAD
Select Add New Row to choose the new SAML IdP Connector, followed by Update

Select OK to save the settings

Header SSO configuration
Create an APM SSO object for doing headers SSO to the backend application.
Select Access > Profiles/Policies > Per-Request Policies > Create
Provide a unique profile a name and add at least one Accepted Language, then select Finished. For example, SSO_Headers

Select the Edit link for the new per-request policy you just created

After the visual policy editor has launched select the + symbol next to fallback

In the pop-up switch to the General Purpose tab to select HTTP Headers > Add Item

Select Add new entry to create 3 separate HTTP Header modify entries using the following:
Property Description Header Name upn Header Value %{session.saml.last.identity} Header Name employeeid Header Value %{session.saml.last.attr.name.employeeid} Header Name group_authz Header Value %{session.saml.last.attr.name. http://schemas.microsoft.com/ws/2008/06/identity/claims/groups}Note
APM session variables defined within curly brackets are case sensitive. So, entering EmployeeID when the Azure AD attribute name is being sent as employeeid will cause an attribute mapping failure. Unless necessary, we recommend defining all attributes in lowercase.

When done, select Save and close the visual policy editor.

Access profile configuration
An access profile binds many APM elements managing access to BIG-IP virtual servers, including access policies, SSO configuration, and UI settings.
Select Access > Profiles / Policies > Access Profiles (Per-Session Policies) > Create to provide the following then select Finished:
Property Description Name MyTravel Profile Type All Accepted Language Add at least one language 
Select the Edit link for the per-session profile you just created

Once the visual policy editor has launched, select the + symbol next to fallback

In the pop-up select Authentication > SAML Auth > Add Item

For the SAML authentication SP configuration, set the AAA Server option to use the SAML SP object you created earlier, followed by Save.

Attribute mapping
Although optional, adding a LogonID_Mapping configuration enables the BIG-IP active sessions list to display the UPN of the logged in user instead of a session number. This is useful for when analyzing logs or troubleshooting.
Select the + symbol for the SAML Auth Successful branch

In the pop-up select Assignment > Variable Assign > Add Item

Provide a descriptive name and in the Variable Assign section select Add new entry > change. For example, LogonID_Mapping.

Set both variables to use the following, then Finished > Save
Property Description Custom Variable session.saml.last.identity Session Variable session.logon.last.username Select the Deny terminal of the Access Policy's Successful branch and change it to Allow, followed by Save
Commit the policy by selecting Apply Access Policy and close the visual policy editor tab
Backend pool configuration
For the BIG-IP to know where to forward client traffic, you need to create an APM node object representing the backend server hosting your application, and place that node in an APM pool.
Select Local Traffic > Pools > Pool List > Create and provide a name for a server pool object. For example, MyApps_VMs

Add a pool member object with the following:
Property Description Node Name Optional display name for the server hosting the backend web application Address IP address of the server hosting the application Service Port The HTTP/S port the application is listening on 
Note
Health monitors require additional configuration not covered in this tutorial.
Virtual server configuration
A virtual server is a BIG-IP data plane object represented by a virtual IP address listening for clients requests to the application. Any received traffic is processed and evaluated against the APM access profile associated with the virtual server, before being directed according to the policy results and settings.
Select Local Traffic > Virtual Servers > Virtual Server List > Create
Provide the virtual server with a Name, an unused IP IPv4/IPv6 that can be assigned to the BIG-IP to receive client traffic, and set the Service Port to 443

HTTP Profile: Set to http
SSL Profile (Client): Enables Transport Layer Security (TLS), enabling services to be published over HTTPS. Select the client SSL profile you created as part of the pre-requisites or leave the default if testing

Change the Source Address Translation option to Auto Map

Under Access Policy, set the Access Profile created earlier. This binds the Azure AD SAML pre-authentication profile and headers SSO policy to the virtual server.

Finally, set the Default Pool to use the backend pool objects created in the previous section, then select Finished.

Session management
A BIG-IPs session management setting is used to define the conditions under which user sessions are terminated or allowed to continue, limits for users and IP addresses, and error pages. You can create your own policy by heading to Access Policy > Access Profiles and selecting your application from the list.
Regarding SLO functionality, having defined a SLO URI in Azure AD will ensure an IdP initiated sign out from the MyApps portal also terminates the session between the client and the BIG-IP APM. Having imported the application's federation metadata.xml then provides the APM with the Azure AD SAML log-out endpoint for SP initiated sign-outs. But for this to be truly effective, the APM needs to know exactly when a user signs-out.
Consider a scenario where a BIG-IP web portal isn't used, the user has no way of instructing the APM to sign out. Even if the user signs-out of the application itself, the BIG-IP is technically oblivious to this, so the application session could easily be reinstated through SSO. For this reason SP initiated sign-out needs careful consideration to ensure sessions are securely terminated when no longer required.
One way of achieving this would be to add an SLO function to your applications sign out button, so that it can redirect your client to the Azure AD SAML sign-out endpoint. The SAML sign-out endpoint for your tenant can be found in App Registrations > Endpoints.
If making a change to the app is a no go then consider having the BIG-IP listen for the apps sign-out call, and upon detecting the request have it trigger SLO. More details on using BIG-IP iRules to achieve this are available in article K42052145 and article K12056.
Summary
This last step provides break down of all applied settings before they are committed. Select Deploy to commit all settings and verify that the application has appeared in your tenant.
Your application is now published and accessible via SHA, either directly via its URL or through Microsoft's application portals.
Next steps
As a user, launch a browser and connect to the application's external URL or select the application's icon in the Microsoft MyApps portal. After authenticating to Azure AD, you'll be redirected to the BIG-IP virtual server for the application and automatically signed in through SSO. The output of the injected headers displayed by our headers-based application is shown.

For increased security, organizations using this pattern could also consider blocking all direct access to the application, in that way forcing a strict path through the BIG-IP.
Troubleshooting
Failure to access the SHA protected application could be down to any number of potential factors, including a misconfiguration.
BIG-IP logs are a great source of information for isolating all sorts of authentication & SSO issues. When troubleshooting you should increase the log verbosity level by heading to Access Policy > Overview > Event Logs > Settings. Select the row for your published application then Edit > Access System Logs. Select Debug from the SSO list then OK. You can now reproduce your issue before looking at the logs but remember to switch this back when finished.
If you see a BIG-IP branded error after being redirected following Azure AD pre-authentication, it's likely the issue relates to SSO from Azure AD to the BIG-IP. Navigate to Access > Overview > Access reports and run the report for the last hour to see logs provide any clues. The View session variables link for your session will also help understand if the APM is receiving the expected claims from Azure AD.
If you don't see a BIG-IP error page, then the issue is probably more related to SSO from the BIG-IP to the backend application. In which case you should head to Access Policy > Overview > Active Sessions and select the link for your active session. The View Variables link in this location may also help root cause SSO issues, particularly if the BIG-IP APM fails to obtain the right user and domain identifiers.
See BIG-IP APM variable assign examples and F5 BIG-IP session variables reference for more info.
Additional resources
For more information refer to these articles: