Configuring Topdesk SAML Single Sign On with F5 Big-IP IDP

I recently had a requirement to configure SAML2.0 Single-Sign on for Topdesk SaaS. My company currently use on-premise F5 Big-IP as a local IDP for SAML and have a few cloud apps working this way. When I set these up however, the documentation from both F5 or the cloud providers themselves was readily available and very thorough.

Topdesk however, not so much. The Topdesk Operator Manual, which is only available if you are a customer and through their extranet, talks only about SAML2.0 with Microsoft ADFS. A disclaimer however states along the lines of “SAML single sign should work with any SAML2.0 compliant IDP in theory, but has only been thoroughly tested with Microsoft ADFS”. Not useful, but reassuring that I should be able to get this to work.

Google Searches didn’t return anyone with experience of implementing F5 as an IDP for SAML authentication to Topdesk SaaS, but did return a few SAML cloud providers who offered it as a service. So hopefully this blog post will help someone else like me out there in the future.

The documentation is written for TOPdesk 8.01.015 and F5 Big-IP 13 Hotfix 3. Other versions may differ.

Configure F5 Big-IP

Configure Virtual Server

First things first, you will need a virtual server on your F5 to listen for HTTPS traffic.

1. Go to Local Traffic > Virtual Servers > Virtual Server List.
2. Click Create.
3. Give your Virtual Server a name that will help you easily identify it in the future. Description can help here too.
4. Set type to Standard.
5. Source Address will allow you to filter out who can access the virtual server. If you want it to be accessible from anywhere, set it to 0.0.0.0/0.
6. Destination Address/Mask allows you to set the IP Address the F5 will listen on. This IP address will need to be accessible from the internet, either by being a publically routable address, or with NAT configured on your perimeter firewall. It should also be part of a public DNS A Record.
7. Service Port allows you to set what port the F5 will listen on. Set this to 443 HTTPS.
8. Ensure state is set to Enabled.
9. The only other option you need to set right now, is your SSL Profile (Client) and SSL Profile (Server). This needs to be a trusted certificate (by devices that will be accessing Topdesk). The easiest is to purchase a certificate from a well-known Certificate Authority. I won’t go over creating SSL Profiles in this blog post, the documentation is out there if you need it.
10. Click the Finished button.

Your config should look something like this:

Configure SAML IdP Service

Next, we’ll configure the F5 SAML IdP Service.

1. Go to Access > Federation > SAML Identify Providers > Local IdP Services.
2. Click Create.
3. On the General Settings page:
1. In IdP Service Name, enter a name for you to easily identify this service in the future. Eg. Topdesk IdP.
2. In IdP Entity ID, you need to enter a unique identifier for this IdP service. It needs to include the public DNS name of the virtual server you created earlier. For example: https://topdesksso.example.com/idp/topdesk.

1. Click on the Assertion Settings section:
1. Set Assertion Subject Type to Transient Identifier.
2. Set Assertion Subject Value needs to be the variable you will pull from logged in users that you will use to login users to Topdesk. Usually this is email address so set this to %{session.ad.last.attr.mail}
3. Set Authentication Context Class Reference to urn:oasis:names:tc:SAML:2.0:nameid-format:transient.

1. Click on the SAML Attributes section:
1. Click Add.
2. Set Name to Email Address.
3. Click Add.
4. Set value to %{session.ad.last.attr.mail}.
5. Click Update.
6. Click OK.

1. Click Security Settings section:
1. Select the certificate and signing key that you want to use to sign the SAML assertion. This adds a layer of protection to the sign in process.
2. Click OK.

The SAML Local Identity Provider service is configured. We are ready to share this metadata with topdesk. Select it and choose Export Metadata to download an .xml version that will be uploaded to Topdesk.

Configure Topdesk SAML Service

1. Log into your Topdesk SaaS instance as an operator.
2. Click Topdesk Menu > Settings.
3. Drill down Functional Settings > Login Settings > General.
4. Under SAML Login, you’ll see two sections; Public and Secure. Public will configure SAML for the Self-Service Portal, whilst Secure will configure SAML for Operator login. I’ll describe configuring for Self-Service Portal, but the process is the same for Operator.
5. Click Add Configuration under Public.
6. Select Upload as file and click Browse. Select the .xml file you downloaded shortly.
7. This will place an entry in the drop-down box of Entity ID, of the IdP Entity ID that you entered in the F5 IdP config (eg. https://topdesk.example.com/idp/topdesk). Select this.
8. In User name attribute, this needs to match the entry you configured in the F5 IdP setting SAML attribute. In our example this was Email Address.
9. The logout url will automatically complete when selecting the Entity ID.
10. The Topdesk endpoint should have automatically completed, but this will be the URL of your Topdesk SaaS instance.
11. Tick Host Topdesk Metadata.
12. Untick Assertions will be encrypted.
13. Upload the certificate and key that you configured in the Security Settings section of the F5 IdP. This can be a pain to get right, as the certificate and key must be separate, the certificate must be a .pem with x.509 formatting, and the private key must be RSA encrypted with PKCS8 formatting and DER encoding. There are guides out there to do this with OpenSSL.
14. Enter a display name, this is what the button will say on the Topdesk login page once SAML is enabled, so something simple like Login works well here.
15. Click Save.

1. Select the config you just made, and click Download. This will download the .xml metadata copy we can use to complete the configure on our F5.
2. Just before we finish in Topdesk, we should enable SAML authentication on the Self-Service Portal. Head to Self-Service Portal and tick SAML Single Sign On.
3. Click Save.

Complete F5 SAML Configuration

Create External SP Connector and Bind to Local IdP Service

Finally, back on our F5:

1. Go to Access > Federation > SAML Identity Providers > External SP Connectors.
2. Click the drop-down arrow next to create and choose From Metadata.
3. Click Browse and select the .xml metadata file you just downloaded from Topdesk.
4. Enter a Service Provider Name (eg. Topdesk) and click OK.

Next we must link together the IdP configuration, and the SP configuration you just created.

1.  Go to Access > Federation > SAML Identity Providers > Local IdP services.
2. Tick the Topdesk IdP configuration from earlier.
3. Click Bind/Unbind SP Connectors.
4. Tick the Topdesk SP configuration you just created.
5. Click OK.

Configure SAML Resource and Attach to IdP Service

1. Next, go to Access > Federation > SAML Resources.
2. Click Create
3. Give the resource a name, eg. Topdesk
4. From the SSO Configuration dropdown, select the Topdesk IdP service you created earlier
5. Click Finished

Note: The remainder of the process is standard SAML F5 configuration. The below is taken from the F5 guide, I’ve added in red some notes that need specific config, but there are few and far between:

Configure a full webtop

A full webtop allows your users to connect and disconnect from a network access connection, portal access resources, SAML resources, app tunnels, remote desktops, and administrator-defined links.

1. On the Main tab, click Access Policy > Webtops.
2. Click Create to create a new webtop.
3. Type a name for the webtop you are creating.
4. From the Type list, select Full.
5. Click Finished.

The webtop is now configured, and appears in the list. You can edit the webtop further, or assign it to an access policy.

To use this webtop, it must be assigned to an access policy with a full resource assign action or with a webtop and links assign action. All resources assigned to the full webtop are displayed on the full webtop.

Configuring an access policy for a SAML SSO portal

Configure an access policy so that the BIG-IP system (as an IdP) can authenticate users using any non-SAML authentication type, and assign SAML resources and a webtop to the session.

Note: This access policy supports users that initiate a connection at a SAML service provider or at the SAML IdP.

1. On the Main tab, click Access Policy > Access Profiles. The Access Profiles List screen opens.
2. In the Access Policy column, click the Edit link for the access profile you want to configure to launch the visual policy editor. The visual policy editor opens the access policy in a separate screen.
3. Click the (+) sign anywhere in the access policy to add a new action item. An Add Item screen opens, listing Predefined Actions that are grouped by General Purpose, Authentication, and so on.
4. From the General Purpose area, select Logon Page and click the Add Item button. The Logon Page Agent properties window opens.
5. Make any changes that you require to logon page properties and click Save. The Access Policy window displays.
6. Add one or more authentication checks on the fallback branch after the Logon Page action. Select the authentication checks that are appropriate for application access at your site.
7. On a successful branch after an authentication check, assign SAML resources and a full webtop to the session.
1. Click plus [+] on a successful branch after an authentication check. The Add Item window opens.
2. From the General Purpose list, select the Full Resource Assign agent, and click Add Item. The Resource Assignment window opens.
3. Click Add new entry. An Empty entry appears.
4. Click the Add/Delete link below the entry. The window changes to display resources on multiple tabs.
5. Select the SAML tab, then from it select the SAML resources that represent the service providers that authorized users can access.
6. Click Update. The window changes to display the Properties screen, where the selected SAML resources are displayed.
7. Click the Add/Delete link below the entry. The window changes to display resources on multiple tabs.
8. Select the Webtop tab, then select a full webtop on which to present the selected resources. You must assign a full webtop to the session even if you have configured all SAML resources to not publish on a webtop.
9. Click Update. The window changes to display the Properties screen. The selected webtop and SAML resources are displayed.
10. Click Save. The Properties window closes and the Access Policy window is displayed.

You have configured a webtop to display resources that are available from service providers and that an authorized user can access.

8. Optional: Add any other branches and actions that you need to complete the access policy.
9. Change the Successful rule branch from Deny to Allow and click the Save button.
10. Click the Apply Access Policy link to apply and activate your changes to the access policy.
11. Click the Close button to close the visual policy editor.

You have an access policy that presents a logon page, authenticates the user, and assigns SAML resources and a full webtop on which to present them to the user.

Simple access policy for access to services on SAML service providers

As we want to use AD attributes (email address) of the logged in user to send to Topdesk, we need to add an AD query object between “Successful” and “Full Resource Assign”. You’ll need your Active Directory configured as a AAA server under Access > Authentication > Active Directory. The AD Query object should look like:

Adding the access profile to the virtual server

You associate the access profile with the virtual server so that Access Policy Manager^®can apply the profile to incoming traffic and run an access policy if one is configured for this access profile.

1. On the Main tab, click Local Traffic > Virtual Servers. The Virtual Server List screen opens.
2. Click the name of the virtual server you want to modify. The one we created at the start!
3. In the Access Policy area, from the Access Profile list, select the access profile.
4. Click Update to save your changes.

Your access policy is now associated with the virtual server.

You’re ready to go! You can either login to your F5 webtop using AD credentials, and click the Topdesk icon, or you can go to your Topdesk SaaS instance, and use the SAML Login button we created earlier. The latter is a bit nice for users. Either way, the webtop will prompt you for credentials. There are ways around this using Kerberos/NTLM, but that’s for another time.