Search Documentation

Working with Trongate Tokens

The mx-token attribute in Trongate MX provides a mechanism for seamlessly integrating Trongate's authentication and authorisation system by attaching Trongate Tokens to outgoing HTTP requests.

Implementation Overview

The Trongate PHP framework includes a powerful module named trongate_tokens. This module facilitates authentication and authorisation tasks, enabling you to secure API endpoints with customisable rules. With the trongate_tokens module, you can enforce granular control over who can interact with your API.

What Are 'Trongate Tokens'?

Trongate Tokens are unique, cryptographically generated strings managed by the trongate_tokens module. These tokens act as secure identifiers for users within your application, enabling robust stateful authentication mechanisms. Below is an example of a Trongate Token:

Using Trongate Tokens With Trongate MX

Developers working with Trongate MX can easily take advantage of Trongate's inbuilt token-based security system.

Usage revolves around a three-step process:

1. Attach a Trongate Token to an element that triggers an HTTP response.
2. Attempt to read a submitted token from your API endpoint.
3. Have your API endpoint grant or deny access based on the presence or absence of a valid Trongate Token.

Let's go through each of these three steps, one at a time.

1: Attaching Tokens to Elements

To attach a Trongate Token to an element, we need to first attempt to fetch a valid Trongate Token using PHP. This can be achieved by loading the 'trongate_tokens' module and invoking the _attempt_get_valid_token() method. For example:

Passing The Token Into The View File

Having fetched a Trongate Token, our next task is to pass the fetched token into the associated view file. It's worth noting that the _attempt_get_valid_token() method will return a boolean of false if no valid token is found for the user. With that being the case, it's a good idea to make sure the value of your token is a (variable of a type) string - regardless of the response from the 'trongate_tokens' module. This can be achieved by using PHP's settype() function. For example:

The lines of code, shown above, achieve two things:

1. They convert the value of $token to a type of string.
2. They add the value of the token onto a $data array - giving it a property of 'trongate_token'.

As is normal practice, with Trongate, your corresponding view file or template can then be loaded having the $data array passed in. For example:

Accessing The Token From The View File

Having fetched a token and passed it into your view file, your Trongate Token should now be available via a $trongate_token variable.

As a reminder, if you failed to fetch a valid token for the user then the value for $trongate_token will be an empty string (since we used settype() in the controller file).

Appending The Token To An Element

We can then attach the fetched Trongate Token (which may or may not be a valid token) to an HTML element using the mx-token attribute. For example,

If you prefer working with a more HTML-centered syntax, the same result can be achieved with:

Regardless of whether or not you choose to use Trongate's form helper functions the result will be the same - any HTTP request that gets invoked by clicking on the button will have a Trongate Token attached to the request header.

2: Fetching Sent Tokens From The API

Having attached a Trongate Token onto your request header, the next task is to have your API endpoint fetch the Trongate Token from the header.

There's actually two ways to do this:

1. By using the Trongate Tokens module.
2. By using pure PHP.

Let's go through both of these options.

Fetching Tokens Using The Trongate Tokens Module

If you've been following along with this example, you'll know that we used the Trongate Tokens module to (attempt to!) fetch a Trongate Token which could then be passed into a view file and - ultimately - attached to an HTTP request.

You can use the same methodology to fetch the token from your API endpoints. Here's a reminder of the syntax:

Fetching Tokens Using Pure PHP

Instead of using the Trongate Tokens module to attempt to fetch the Trongate Token from the header, you can use pure PHP. This can be achieved with the following:

Of course, this is not a perfect solution since an error would be thrown in instances where a Trongate Token has not been attached to the HTTP request header.

This can be mitigated by using the ternary operator. For example, with the code below, we attempt to read a Trongate Token from an HTTP request header. However, if a token is not found in the header, the $trongate_token value will be assigned with an empty string.

With the assumption that you know how to authenticate a user, based on the presence or lack of a valid Trongate Token, it's then for you - the developer - to decide whether or not to grant or allow access to an API endpoint.

Granting Or Denying API Access

Once you've validated (or invalidated) a Trongate Token, your API endpoint should respond appropriately using standard HTTP response codes. Here's how to handle common scenarios:

Successful Access

When a valid token is provided and meets all authorization requirements, your endpoint should return an HTTP response code within the success range. For example:

Example of granting access:

Access Denied

When access needs to be denied, use appropriate status codes to indicate why. Examples include but are not limited to the following:

• HTTP 401 (Unauthorized) - When no token is provided or the token is invalid
• HTTP 403 (Forbidden) - When the token is valid but the user lacks sufficient permissions
• HTTP 429 (Too Many Requests) - When rate limiting is exceeded

Example of denying access:

Remember that proper error handling and clear response messages help both security and developer experience. Your API should be both secure and user-friendly.