This document is intended for Partica customers who want to integrate their own user /

subscription / payment system to grant access to a Partica publication.

Partica.


Overview


Partica uses JWT (JSON web tokens) to create a trust between itself and your system. Once you

validate a user in your system, you create a token for that user, and send the user with the token

to Partica. Partica validates the token and grants access to the secure publication. If the token is

invalid the user gets redirected back to your login URL.


See https://jwt.io/introduction/ for more information on JWT.



Setup


You will need to share a secret (a random sequence of letters / numbers) to sign and

verify the JWT. Once the shared secret has been agreed you can create a JWT using one of

many libraries. See https://jwt.io/#libraries


Here is a recommended secret generator.


Partica uses HS256 for creating the signature.


If you are already using JWT for an existing system then we can extend that for use in Partica by

using your existing shared key.


You can also use the same secret across multiple partica domains (multiple publications),

allowing the same JWT to be used on those domains. This is ideal if you want a single login to

grant access to multiple publications.


Implementation


Once your user has been validated by your authentication system, you create the JWT and

transmit it to Partica using the query string parameter externalauthtoken, for example:


https://democustomer.partica.online/?externalauthtoken=your.jwt.token



Partica will read the externalauthtoken query string and verify it was created using the shared

key and grant the user access to Partica content.


Partica will redirect users who are not logged in back to your system - you need to supply a

signup and login url. These can be the same.



JWT Token Structure


Partica requires the following reserved claims:




iss (issuer): Issuer of the JWT

sub (subject): Subject of the JWT (the user)

exp (expiration time): Time after which the JWT expires

iat (issued at time): Time at which the JWT was issued; can be used to determine age of the JWT


You can see a full list of reserved claims at the IANA JSON Web Token Claims Registry.

Example JWT


Here is an example JWT signed with the secret : sbuxqV3SXVOvH149fzU9Z8Jn4gC1FStc

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0aGlyZC5wYXJ0eS5pc3N1ZXIiLCJpYXQiOjE2Mjc2NDQ4NzMsImV4cCI6MTYyNzczMTI3Mywic3ViIjoieW91ci11c2VyLWlkZW50aWZpZXIifQ.siJXt32tlip5iOgvStzJU4Mc7CWiHq3__M48VQg9whk

Go to https://jwt.io/ to decode into the following.

{
  "iss": "third.party.issuer",
  "iat": 1627644873,
  "exp": 1627731273,
  "sub": "your-user-identifier"
}