Web API Token Authentication

Before version 8.3.4, the web services API authentication used implicit OAuth, passing a username and password to the Terminalfour instance. For many, this meant setting up a specific user to handle API requests or using a Terminalfour user.

Either way, passing usernames and passwords this way is far from ideal so now we’ve added a way to use API Keys / Tokens to handle the authentication. There are five immediate benefits to this:

1. You’re not passing sensitive usernames and passwords each time you use the web services API
2. Tokens can expire so you can provide access for just a specific duration or if there has been a data breach, the token can be deleted and a new one can be created. This also makes interoperability with third-party applications more secure. If you are testing or retiring an application that uses Terminalfour’s Web Services API, then you can easily remove or disable the key it uses
3. You can manage access to Terminalfour for all third-party applications with each User’s Terminalfour API Keys (tokens)
4. Writing code that interacts with the web services API has been simplified so your client isn’t required to track session information and the connection step can be eliminated
5. Users authenticating with a directory service like LDAP could not use that account for the web services API. An administrator can generate an API key associated with their user account regardless of where the credentials originate.

This makes working with the Web Services API easier and far more secure.

How tokens work

An Administrator can generate tokens in the User Management screen.

API Keys / Tokens use JSON Web Tokens (JWTs) to pass authorization information between clients and Terminalfour. 

The Tokens generated by Terminalfour are digitally signed using a 64-bit secret and an HMAC algorithm to ensure their contents can be trusted. They contain the following information:

• Terminalfour user (principal) id
• Token expiry date
• Token identifier (in the case of API tokens generated in the UI)
• Token creation time
• Principal full name
• Token audience value (this includes the user for API tokens and the system for temporary tokens)

In addition to the new API Keys/Tokens, the standard process of connecting to Terminalfour has been updated. The existing connection/authorization flow works like before but now a temporary JWT is used as the bearer token instead of an oAuth bearer token.

A new endpoint (/rs/authorise) has also been added for generating temporary JWTs. This can be used to generate a temporary JWT in a single request from existing credentials (username and password)

Since Terminalfour now supports stateless requests, no active sessions are required when submitting web service requests.

Generating tokens

New tokens can be generated in the following three ways:

1. Using the/rs/authorise endpoint
• A GET request using BASIC authentication with the user’s credentials is sent to /rs/authorise. If the credentials are valid, Terminalfour will respond with a new temporary JWT valid for 30 minutes
• Generates temporary tokens with a validity period of 30 minutes
• Supports stateless requests
2. Using legacy /rs/authorize-implicit and rs/authorize-implicit/decision endpoints
• These can be used in the same manner as in previous versions, the accessToken returned will now be a JWT rather than an oAuth token. The JWT will be valid for 30 minutes
• Generates temporary tokens with a validity period of 30 minutes

This method has been marked as deprecated and is due to be removed in a future version.

3. An Administrator can create a new token for a user through the UI
• This token can then be copied and used to authorize web service requests
• The administrator can set an expiry date on this token
• Stateless requests are supported
• The token can be used to authorize the linked user’s web services requests for the lifetime of the token

Conclusion

Our aim is that enhancements like this will encourage more of you to take advantage of the web services API. We are working hard on other improvements, so stay tuned...