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.
- Go to Local Traffic > Virtual Servers > Virtual Server List.
- Click Create.
- Give your Virtual Server a name that will help you easily identify it in the future. Description can help here too.
- Set type to Standard.
- 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.
- 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.
- Service Port allows you to set what port the F5 will listen on. Set this to 443 HTTPS.
- Ensure state is set to Enabled.
- 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.
- Click the Finished button.
Configure SAML IdP Service
Next, we’ll configure the F5 SAML IdP Service.
- Go to Access > Federation > SAML Identify Providers > Local IdP Services.
- Click Create.
- On the General Settings page:
- In IdP Service Name, enter a name for you to easily identify this service in the future. Eg. Topdesk IdP.
- 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.
- Click on the Assertion Settings section:
- Set Assertion Subject Type to Transient Identifier.
- 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}
- Set Authentication Context Class Reference to urn:oasis:names:tc:SAML:2.0:nameid-format:transient.
- Click on the SAML Attributes section:
- Click Add.
- Set Name to Email Address.
- Click Add.
- Set value to %{session.ad.last.attr.mail}.
- Click Update.
- Click OK.
- Click Security Settings section:
- 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.
- 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
- Log into your Topdesk SaaS instance as an operator.
- Click Topdesk Menu > Settings.
- Drill down Functional Settings > Login Settings > General.
- 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.
- Click Add Configuration under Public.
- Select Upload as file and click Browse. Select the .xml file you downloaded shortly.
- 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.
- 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.
- The logout url will automatically complete when selecting the Entity ID.
- The Topdesk endpoint should have automatically completed, but this will be the URL of your Topdesk SaaS instance.
- Tick Host Topdesk Metadata.
- Untick Assertions will be encrypted.
- 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.
- 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.
- Click Save.
- 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.
- 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.
- Click Save.
Complete F5 SAML Configuration
Create External SP Connector and Bind to Local IdP Service
Finally, back on our F5:
- Go to Access > Federation > SAML Identity Providers > External SP Connectors.
- Click the drop-down arrow next to create and choose From Metadata.
- Click Browse and select the .xml metadata file you just downloaded from Topdesk.
- 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.
- Go to Access > Federation > SAML Identity Providers > Local IdP services.
- Tick the Topdesk IdP configuration from earlier.
- Click Bind/Unbind SP Connectors.
- Tick the Topdesk SP configuration you just created.
- Click OK.
Configure SAML Resource and Attach to IdP Service
- Next, go to Access > Federation > SAML Resources.
- Click Create
- Give the resource a name, eg. Topdesk
- From the SSO Configuration dropdown, select the Topdesk IdP service you created earlier
- 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.
- On
the Main tab, click Access Policy > Webtops.
- Click Create to
create a new webtop.
- Type
a name for the webtop you are creating.
- From
the Type list, select Full.
- 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.
- On
the Main tab, click Access Policy > Access Profiles. The
Access Profiles List screen opens.
- 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.
- 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.
- From
the General Purpose area, select Logon Page and click the Add
Item button. The Logon Page Agent properties window opens.
- Make
any changes that you require to logon page properties and click Save. The
Access Policy window displays.
- 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.
- On a
successful branch after an authentication check, assign SAML resources and
a full webtop to the session.
- Click
plus [+] on a successful branch after an authentication
check. The Add Item window opens.
- From
the General Purpose list, select the Full Resource Assign agent,
and click Add Item. The Resource Assignment window opens.
- Click Add
new entry. An Empty entry appears.
- Click
the Add/Delete link below the entry. The window changes to
display resources on multiple tabs.
- Select
the SAML tab, then from it select the SAML resources that represent the
service providers that authorized users can access.
- Click Update. The
window changes to display the Properties screen, where the selected SAML
resources are displayed.
- Click
the Add/Delete link below the entry. The window changes to
display resources on multiple tabs.
- 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.
- Click Update. The
window changes to display the Properties screen. The selected webtop and
SAML resources are displayed.
- 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.
- Optional: Add
any other branches and actions that you need to complete the access
policy.
- Change
the Successful rule branch from Deny to Allow and click
the Save button.
- Click
the Apply Access Policy link to apply and activate your changes
to the access policy.
- 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.
- On
the Main tab, click Local Traffic > Virtual Servers. The
Virtual Server List screen opens.
- Click
the name of the virtual server you want to modify.
The one we created at the start!
- In
the Access Policy area, from the Access Profile list, select the
access profile.
- 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.