Skip to main content

Integrating with the TinQwise Platform Using JWT SSO

O
Written by Okke Formsma
Updated over a month ago

Overview

This guide explains how to integrate with the TinQwise platform using JSON Web Token (JWT) Single Sign-On (SSO). By following these steps, users can seamlessly authenticate into the TinQwise platform without requiring manual login credentials.

Authentication Flow

  1. The customer generates a JWT token signed with RS256.

  2. The token is appended to the TinQwise platform URL as a query parameter.

  3. TinQwise verifies the token's signature using the customer's provided public key.

  4. If verification is successful, the user is authenticated and granted access.

URL Format

Users should append the JWT token to the TinQwise platform URL as follows:

https://my_domain.platform.co.nl/?jwt=TOKEN

Where TOKEN is the generated JWT token.

JWT Token Requirements

The JWT token must adhere to the following specifications:

  • Algorithm: The token must be signed using RS256.

  • Username Field: The unique identifier for the user should be included in the username claim.

  • Expiration: (Recommended) Set an expiration time (exp claim) to prevent token reuse.

Example JWT Payload

{ "username": "unique_user_id", "exp": 1715123456 }

Setting Up the Connection

To establish a secure connection, the customer must provide TinQwise with their public key for the RS256 signature. This public key will be used to verify the JWT tokens.

Steps:

  1. Generate an RSA key pair (private & public key).

  2. Share the public key with support@tinqwise.com

  3. Ensure that JWT tokens are signed using the corresponding private key.

  4. Make sure users are created with a "jwt username" field set using an importer, API v3 or an excel sheet upload.

    1. When this field is not available, a fallback will be done to the "username" field

Generating an RSA Key Pair

If you need to generate a new key pair, you can use the following OpenSSL command:

openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048 openssl rsa -pubout -in private_key.pem -out public_key.pem

  • private_key.pem: Used to sign JWT tokens.

  • public_key.pem: Shared with TinQwise for verification.

Troubleshooting the connection

In your control environment (https://your-domain.platform.co.nl/control) you can see succesful and failed login attempts. Go to 'users' -> 'integrations' -> 'login logs'.

If the login attempts do not show up, make sure you're adding the token to the URL in the correct way.

Conclusion

By following this guide, you can successfully integrate with TinQwise using JWT SSO, ensuring a secure and seamless login experience for your users.

Did this answer your question?