This page is intended for engineers (normally at institutions), who are responsible for the TOPdesk instances in SURFconext. Managing TOPdesk on SURFconext differs from other service providers in several ways. This page will outline what you need to do in case of changes to instances of TOPdesk or your IdP, which affects your TOPdesk instances. 

Introduction

TOPdesk is connected to SURFconext and many institutions make use of TOPdesk. TOPdesk is a single tenant service, usually consisting of a 'public' and a 'secure' instance, and has the following properties with regards to SURFconext:

  • Depending on the agreements an institution has made, the connection with SURFconext is managed by the institution or by TOPdesk. This is stated in the contracts that an institution has concluded with TOPdesk. Make sure you know well in advance of making changes to TOPdesk or your IdP, who is responsible for the management of the TOPdesk instances in SURFconext.
  • It is a Single Tenant Service, so every institution has their own entry in SURFconext to access TOPdesk and needs to be configured and registered in SURFconext separately for every institution.
  • Changes in the configuration of a TOPdesk instance generally result in a new entityID. This has to be registered again in SURFconext by TOPdesk or the institution, depending on the service agreements (see above).

  • A change in the entityID of an IdP, e.g. when upgrading a new IdP platform, results in configuration changes in TOPdesk and usually new entityIDs of TOPdesk in SURFconext.

  • TOPdesk instances use a Single Sign On location that is specific to the institution it is used for.

  • When a change is submitted and a new entity registered, the previous version of the entity remains active for a transition period. Notify us when the old instances can be deleted. This avoids a cluttered list of TOPdesk instances in the IdP dashboard and SURFconext.

Manage TOPdesk instances using TOPdesk's Self-Service Portal and SURFconext SP Dashboard

Step 1: Create TOPdesk metadata in TOPdesk's Self-Service Portal

Note: this procedure is copied from TOPdesk knowledge item KI 7463. Please refer to this item for the actual version of the procedure.

  • Go to Functional Settings > Login > General > Self-Service Portal / Operator's Section
  • Click Add... and fill in the following:
  • You can download the metadata certificate from SURF, upload it to TOPdesk and turn it on for added security
    • Host TOPdesk metadata: yes
    • Assertions will be encrypted: no
    • Generate key pair: yes
    • Enter a name, e.g. 'SURF Authentication'
    • Save the data.
  • By default SURFconext does not validate the signature of the AuthNRequest, the authentication request, from TOPdesk. Although present in your metadata, there is no need to update the certificate in SURFconext for your TOPdesk instances when updated. 
  • Click 'URL metadata'. Use this URL in step 2.

Step 2: Configure your TOPdesk instance in the SURFconext Service Provider Dashboard

The SURFconext Service Provider Dashboard (https://sp.surfconext.nl) enables you to manage your service(s) on the SURFconext platform. It allows you to create, test and edit entities before promoting them to production. An institution or TOPdesk Support can get access to the SURFconext SP Dashboard by sending a mail to the SURFconext help-desk (support@surfconext.nl).

How to use this SURFconext SP Dashboard is found on this page. There are no special requirements to work with the SP Dashboard, other than the browser you are viewing this page with:

  • If you work for a Service Provider and you are not a member of an Identity Provider like an institution or a research facility that is enlisted with SURFconext, you can use our guest identity provider eduID to gain access to the Service Provider Dashboard.

  • If you setup a service and you work for a Dutch education or research institution, you can use the identity of this institution to work with the dashboard.

  • You will have an overview of all your TOPdesk instances in one place. This makes TOPdesk's instances manageable for TOPdesk Premium Support as well as for customers of TOPdesk.

Enter in the URL you received  in step 2 in the Import Url field in SP Dashboard, when you create your TOPdesk instance.

Step 3: Enable SAML authentication in TOPdesk's Self-Service Portal

When your TOPdesk instance is published to production at SURFconext, check the SAML option in the Self-Service Portal.

Upgrade or migrate an IdP

The TOPdesk services are configured with an IdP specific Single Sign On location on SURFconext which for an IdP need to be converted from the old to the new IdP when doing an upgrade. Prior to an IdP-upgrade going live you need to collect data that you need to configure in your TOPdesk instance. Contact support@surfconext.nl. We will supply you with the necessary data of the IdP in SURFconext to migrate the TOPdesk instance. The Single Sign On location (SSO-URL) will change. Changing this URL will most likely result in a new instance of TOPdesk in SURFconext, because the entityID of the TOPdesk instance will change. Using the SP Dashboard, you can upload and publish the new metadata.

As an example, the following data will be supplied by us. Note that the IdP Hash will change for the new instance of the upgraded IdP:

Supplied info when upgrading an IdP

Current instance of the IdP

The new IdP

The information needs to be processed by either TOPdesk (premiumsupport@topdesk.com) or the TOPdesk responsible engineer at an institution. After that, publish your new instance through the SP Dashboard or by supplying us with the new metadata.