Gatekeeping your API: protect your data with application passwords

If you have a recent version of TOPdesk, then you now have another option for authenticating applications that use the TOPdesk API. Instead of using your login data for TOPdesk to authenticate API access, you generate a unique password to grant access to each application. Read on to find out what the benefits of using a unique password is and why TOPdesk made these changes.

Benefits of the Application Passwords

1) Easy for integration developers

Applications access the TOPdesk API in a single request. Just use Basic Authentication to provide the username and (application) password to the request. There are no tokens to remember between requests.

2) Unique passwords for each application

Unique passwords offer more security and also protects your personal login data.

3) Faster password verification

The generated passwords are very long. As the passwords can't be brute forced, a fast hash function is used to verify passwords.

4) Single Sign-On supported for operators

The operators log in using any authentication method. Then they generate application passwords for integrations, that use a different authentication method.

5) Manage application access easily

You and your operators have an overview of applications that have access to the TOPdesk API. In this overview, you see which applications were last active. You remove access by simply pressing a button. As you don't use your personal login data to authorize access, you won't break integrations when you change your password.

Why the need for change?

Previously, applications accessed the TOPdesk APIs via a two-step process. First, a session token was fetched using the login name and password of the operator. Then, the application used that token to access the TOPdesk APIs.

This token-based approach had several problems:

1) Error-prone for integration developers

The token that was returned from the login endpoint was only valid for eight hours. After eight hours, the login endpoint can be called again to get a new token. For most cases, eight hours was enough. However, errors would occur when you would test your application and everything seemed fine. But in production, you would suddenly notice that you forgot to re-authenticate or have an error-handler do this if the token expires. Your application would suddenly stop working and this was typically after office hours.

2) Cumbersome for integration developers

Even for the simplest application, two requests are needed. One to get a token, and then one to get the data. Not all tools can handle that.

3) You would store your TOPdesk password in other applications

Normally, passwords are not stored in any database. After the user provides a password, a so-called hash function is applied to transform the password to a hash of the password. This process is irreversible. In the old system, the developers of applications that used the TOPdesk API would have to ask the user to provide the password every time, or store the password in a way that is reversible. That was not very secure, considering users have the tendency to reuse their passwords for several applications.

4) Password verification is slow by design

As explained before, passwords should never be stored in the database. Instead they are hashed, and the hashes are stored. If for some reason, attackers get access to the hash of a password, they can try to hash millions of possible passwords, to see if they can get the same hash. To prevent this from being reasonable feasible, we use a hash function that is very, very slow by design. The downside of a slow hash function is that if a lot of operators use the TOPdesk APIs, it takes a lot of computing time to just verify the passwords. As passwords are now longer, a quicker hash function can be used.

5) No possibility for Single Sign-On (SAML2)

TOPdesk supports multiple ways for users to authenticate themselves. We recommend that application managers use SAML to authenticate users. That means that their own Active Directory, or similar system, is used to do the whole authentication. In browsers, this means that whenever operators wants to use TOPdesk, they are redirected to the Identity Provider, that does the whole authentication, and are then redirected back to TOPdesk. When you use an API, this process doesn't work.

6) Not easy to prevent an application further access

You can only block an application's access to your account by changing your password. If you have multiple application that access your account, you would have to give the other applications your new password. If you change your password for any other reason, you also would have to change that password in all other applications. Furthermore, you might not even know which other applications have access to your account. By changing your password, your integrations could suddenly break without you noticing. Each application gets it's own password, so the chances of your breaking an integration is much smaller. You have to remove the application password permissions from an operator, or manually delete the application from the overview list.

Using Application Passwords

To start using application passwords, you will first need permissions. Either assign permissions to your operators, or request permission from your application manager.

Via Open user menu > My Settings, you can add application passwords. After creating a new password by providing an application name and expiry date, you will see a long generated password. Copy this password. This is the only time you will see this password looks like this: dklcw-jbkqb-pon52-wjrvg-gpgmm. Use this password to grant an application access to the TOPdesk APIs. For maximum security, you should not store the password anywhere. After creating a password, the application is displayed in the list of application passwords, along with its creation date, expiry, and when the application last accessed the operator's account. Operators can remove an application password to prevent the application further access to their account.