It is already more than a year ago that we first heard of something new: a new architecture for TOPdesk, based on microservices. This innovation ensures that TOPdesk becomes more secure, easier to maintain and update, and less susceptible to disruptions. In this new architecture access to TOPdesk is regulated by something that TOPdesk calls “the passlayer”. The passlayer takes care of authentication and securing sessions. As a rule of thumb TOPdesk SAAS uses the passlayer, but TOPdesk on premises do not. More about this later in this article.
HTTPrequests project
The average TOPdesk users do not see or notice the passlayer. They simply login, and use TOPdesk. For a little project I had to dive into the intricacies of the passlayer, and I am happy to share my findings. The project was a Python script that sends HTTPrequests to TOPdesk in batch. This is obsolete technology; HTTPrequests are superseded by a more robust REST API. However, they are widely used and they still work. Moreover, some modules have no REST API endpoints, which leave HTTPrequests as the sole solution for automated tasks. This is the case for Problem Management, Visitor Registration and some others. You can find my Python scripts here. The scripts in action:
TOPdesk has supported HTTPrequests ever since I first started working with TOPdesk in 2013. This technology enabled external systems or users to create or edits card in the database, such as tickets. The not-so-secure aspect of HTTPrequests was/is that it allowed authentication by providing a plain text username and a plain text password in the url. With the implementation of the passlayer and the new architecture on SAAS this no longer works. And with good reasons, because usernames and plain text passwords are a security hazard. There are however some situations where it is still possible to authenticate via credentials in the url. The most useful is the option to send HTTPrequests to “this TOPdesk”. This is an option when creating HTTPrequests in the Actions module. This functionality ensures backward compatibility with existing HTTPrequests that automate particular tasks.
So, with the new architecture comes the passlayer, and the passlayer is what blocks authentication by username/password within the url. However, once you pass though the passlayer (option 1), or bypass the passlayer (option 2), HTTPrequests work again. This is something that needs some explaining.
Option 1: pass through the passlayer
In the classic TOPdesk, you could simply login by sending one POST request:
https://yourtopdesk.topdesk.net/tas/secure?j_username=username&j_password=password
Replace url, username and password, and you will access the landing page within TOPdesk. This still works with TOPdesk on premise. After login you get two cookies:
- __cfduid
- JSESSIONID_SECURE
In the new architecture you still need the same three variables in order to login: url, username and password. However, there is now a complex token exchange that takes place when logging in, spread over four consecutive requests:
- GET request to https://yourtopdesk.topdesk.net/tas/secure/login/form
- POST request to https://yourtopdesk.topdesk.net/tas/secure/login/verify/
- POST request to https://yourtopdesk.topdesk.net/passlayer-idp
- POST request to https://yourtopdesk.topdesk.net/services/authenticate/token/createSession
After login you get three cookies:
- __cfduid
- JSESSIONID_SECURE
- authsession
If the authsession cookie is set login was successful. You have passed through the passlayer. Hooray!
Option 2: bypassing the passlayer
Bypassing the passlayer sounds rather hacky. However it is standard TOPdesk functionality. Remember that HTTPrequests still work when using the option “this TOPdesk”. The reason they still work is because they do not navigate through the passlayer. The passlayer not only takes care of authentication and securing a session, but also serves as the intermediate between the user and the reverse proxy. In other words, the passlayer takes you to the other side of reverse proxy, into the application. However, if you are “this TOPdesk” and you communicate to “this TOPdesk” you remain on the “other” side of the reverse proxy. You do not need to pass through the passlayer at all. And this is why HTTPrequests to “this TOPdesk” continue to work: they bypass the passlayer. An analysis of the first beta release of TOPdesk on premise with services confirm this.
Surprising conclusion
For me it was a somewhat surprising conlusion: the passlayer does not replace the existing authentication mechanism. To the contrary, the existing authentication mechanism is still in place and is still used in some cases. The passlayer is like a wrapper around it. In addition, the reverse proxy turns out to be a fundamental new component in the new architecture. This in turn explains the choice to release TOPdesk as virtual appliance.
Fortunately, HTTPrequests that do not contain authentication strings can still be used. This is what my Python scripts do: login, secure a session, save the session cookies, and use these session cookies when sending HTTPrequests in batch. This is how the Python method looks like:
Again, you can find the source code here.
