Authorization and authentication

Introduction

This article describes user authentication and authorization schemata on the Trusted Twin platform.

The purpose of this article is to provide system architects and developers with conceptual knowledge required to design solutions on the Trusted Twin platform. For developer resources, please consult the Trusted Twin docs website.

10 min read

Figure 1. Authorization and authentication on the Trusted Twin platform.

Concept

Overview

There are two user authentication schemata on the Trusted Twin platform:

  • User Secret (API key) based user authentication schema,
  • User Token based user authentication schema.

Both schemata use the same authorization model. The model is based on the user role.
Read more: Account and user

A User Secret (API key) and a User Token have different purposes of use:

  • A User Secret (API key) is intended for use by backend applications that require access to the Trusted Twin API.
  • A User Token is intended for use by frontend applications. It allows for direct access to the Trusted Twin API, bypassing backend applications. A User Token is always generated on the base of a User Secret (API key) and it inherits all permissions of the User Secret (API key).

Figure 2. A User Secret (API key) is intended for use by backend applications. A User Token is intended for use by frontend applications.

User Secret (API key)

A User Secret (API key) is always associated with a user. A user can only have one active User Secret (API key) at a given time. The User Secret (API key) serves for user authentication.

Figure 3. A user can have only one User Secret (API key) at a given time.

Permissions granted to a given User Secret (API key) (i.e., user permissions and rules) are stored in the role of the user for whom the User Secret (API key) was generated. The "validity_ts" is stored as an attribute by the user for whom the given User Secret (API key) was generated.

A change to the user role or an update of the "validity_ts" attribute does not automatically invalidate a User Secret (API key).

User Token

A User Token is always associated with the User Secret (API key) which was used to generate it. You can generate any number of User Tokens  using a single User Secret (API key). The permissions of a User Token are inherited from the User Secret (API key) used to generate it. These permissions are checked during each API call.

Figure 4. Any number of User Tokens can be generated using a single User Secret (API key).

When creating a User Token, you can specify the "validity_ts" of a given User Token which will always be subordinate to the "validity_ts" of the User Secret (API key) used to generate a given User Token.

When creating a User Token, you can provide a dictionary containing variables (i.e., "secret_dict") that will be passed to authorization rules and templates in the same way as when using the "X-TrustedTwin" custom header, which allows for personalization of User Tokens. The "secret_dict" is not visible to the user creating the User Token. In case when the "X-TrustedtTwin" header is passed in the API method call authorized with the User Token, the "secret_dict" passed in the User Token takes precedence over variables of the same name passed in the "X-TrustedTwin" custom header.

Developer resources
Custom headers
Rules
Templates

When creating a User Token, you can indicate whether the User Token can be used to create more User Tokens ("create" option)  or to extend the "validity_ ts" of a User Token ("refresh" option).

Important note

Refreshing an existing User Token does not automatically invalidate the User Token used to refresh that User Token. You should treat a “refreshed” User Token  as a copy of this User Token with updated validity (i.e, the "secret_dict" is inherited from the User Token that was used to refresh it). 

Figure 5. Refreshing User Token generates a copy of the User Token used to generate it with an updated validity. The User Token inherits the “secret_dict” of the User Token used to generate it.

Because User Tokens are always subordinate to the User Secret (API key) used to generate it, invalidating a User Secret (API key) automatically invalidates all User Tokens which were generated on the base of this User Secret (API key). 

Figure 6. User Token “secret_dict” variables take precedence over DICT variables passed in the “X-TrustedTwin” custom header.

Best practices

  • We recommend creating a dedicated user and User Secret (API key) for generating User Tokens with limited permissions.
  • We recommend using a "secret_dict" to limit User Token access to only selected resources (e.g., Twins, Entries, Identities).
  • Remember that invalidating a User Secret (API key) automatically invalidates all User Tokens associated with the User Secret (API key).
  • Remember that User Tokens always inherit permissions from current settings of the user role associated with the User Secret (API key) used to generate the User Token.

For more information about how to use the Trusted Twin platform in your application’s architecture or technology stack, please contact hello@trustedtwin.com or schedule a video consultation with us through Calendly.

ON THIS PAGE