Overview

JSON Web Token (JWT) is a compact, URL-safe means of representing claims to be transferred between your system and Acadio. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

Integration

Integrating JWT-based authentication within Acadio is a simple process that requires only a few steps.

To begin, access your Acadio Admin portal and navigate to the Settings section. From there, select Integrations to proceed.

Locate the JWT Auth app within the Integrations section and initiate the installation process by clicking on the "Install App" button.

You will be presented with a form where you can enter a shared secret to sign your JWT. Optionally, you can enter both a max-age and issuer claim. For more information regarding these claims, visit https://jwt.io/introduction. 

Usage

The JWT Auth app is used to create and/or authenticate users from your systems. The signed token is represented as follows:

  • email
    (String) User's unique email
  • meta
    (optional)(Object) A JSON field allowing you to map custom data to your customers
  • groups *
    (optional)(Array) An array containing ID's of Groups to associate this user with
  • credits *
    (optional)(Array) An array of objects
    (object) Credit
    orderId (string maxlen 32) An order id to associate to this credit
    id (int) A credit id mapping to an Acadio credit instance
  • onboard
    (optional)(Boolean) If true, the user will be redirected to onboarding upon creation.

* Credits and Groups are non-partial and always synced unless omitted, meaning if the property is detected, the system will sync the data. For example, if the token provides groups: [], this will be treated as a removal of any associated group. If the Groups property doesn't exist, no action will be taken on any current association with user groups.

Endpoint

Once configured, the endpoint will be https://(domain.acadio.com|yourcustomdomain.com)/auth/callback/jwt-auth?token=xxxxxxxxxxxxxxx&go=/somewhere.

Where the token is the signed JWT token and the go parameter is the location to redirect the user to after authentication.

Disconnect

To remove the JWT auth integration simply navigate to your integrations section and click remove. Once removed the JWT secret and any signed tokens will be rejected by Acadio.