Enduser SSO

Interactive Liveblog features can directly integrate with your websites users. This creates a seamless experience for your users with no need for an extra sign up step.

General Flow

EmbedJS needs to know if your User is logged in or not. Your website must supply EmbedJS with information about the User on startup or whenever the login status changes. To start, EmbedJS only needs a users name to display. When the user actaully takes any action like posting a comment, EmbedJS will reqeust a signed IdToken to verify your users identity.

Step By Step Tutorial

This section assumes you already included the Tickaroo EmbedJS script and use it to display Liveblogs. If that is not the case, please start out with “Getting Started”

Step 1: Generate a secret signing key

1. Log in to your Pro account and navigate to Settings and then Comments.
2. Click on “Create new singing key”
3. Follow the steps of the wizard to create and download a signing key

Step 2: Implement the Basic JS API

On your website, tell Tickaroo when a user is logged in:

function initTickarooSSO() {
  // Tell Tickaroo about the current user
  window.tik4.setCurrentUser({
    sub: "123456789",  // Tbe user ID, must be a string
    name: "JohnDoe",   // The users display name
    idTokenCallback: function() {
      // Will be called if we need to securly verify the identity of the user 
      // (e.g. when a comment should be postet)
      // Must return a Promise for a signed IdToken
      return fetch(/* ... */).json().then(data => data.idToken)
    }
  })
  
  // Optional: Tell Tickaroo how we can trigger your login flow
  window.tik4.setTriggerLoginFunction(function() {
    // Trigger your login flow...
  })
}

// Check if Tickaroo has already loaded, if not wait for the event
if(window.tik4) {
  initTickarooSSO()
} else {
  window.addEventListener("tickarooInit", initTickarooSSO)
}

The name field should be the display name of your User.

The idTokenCallback field is a function returning a Promise<string> object. The function should make a call to your backend to retrieve a signed idToken (see Step 3). The easiest way to do this is to use fetch to call your backend and retrieve the IdToken. EmbedJS will call this only when necessary.

Optional, you can log your user out of Tickaroo by issuing this call:

    window.tik4.setCurrentUser(undefined);

Step 3: Sign the IdToken on your Backend

Your backend must implement an endpoint that returns a signed IdToken. An IdToken is a signed JWT with specific predefined claims. Libraries to create and sign JWTs exist for all popular programming environments.

The IdToken must have the following claims:

Header Claims

interface HeaderClaims {
  "alg": "HS256" | "RS256" | "ES256"  // The signing algorithm you selected in Step 1
  "kid": string                       // The ID of the key generated in Step 1
}

Payload Claims

interface PayloadClaims {
  "sub": string                       // Your user ID. Must be a string and must be unique
  "exp": number                       // UNIX-Timestamp when this token expires. Should be short lived!
  "name": string                      // The display name of the user
  "picture": string | undefined       // Optional: Provide a link to the users avatar website
  "profile": string | undefined       // Optional: Provide a link to the users profile on your website
}

We recommend to set the expiration time no further than 2 minutes into the future. This leaves enough room for slow internet connections while still providing a decent protection against replay attacks.

Example implementation in Java using com.auth0:java-jwt assuming HS256 signature:

private Algorithm algorithm = Algorithm.HMAC256(Base64.getDecoder().decode("..."));

public String signJWT(User user) {
  Date expires = new Date(System.currentTimeMillis() + 120_000);
  return JWT.create()
    .withKeyId("...")
    .withExpiresAt(expires)
    .withSubject(user.getId())
    .withClaim("name", user.getName())
    .sign(algorithm);
}