JWT SSO

Using JSON Web Token (JWT) for Single Sign-On is an excellent way if your organization does not yet have a central Identity Provider, or when you want give your users a seamless flow from your app to Fellow Digitals. It will require some coding at your end, but this is usually not a lot of work.

---

The process

This is the authentication process:

1. Your user is browsing your company's intranet or website (for example, https://intranet.mycompany.com).
   
2. A script on your side authenticates the user using your proprietary login process.
   
3. Your script builds a JWT token that contains the relevant user data.
   
4. You redirect the user to your Fellow Intranet or Fellow LMS domain (for example https://mycompany.fellow.eu) with the JWT token as a query string parameter.
   
5. Fellow Digitals parses the user details from the JWT token and then grants the user a session.
   

As you can see, this process relies on browser redirects and passing signed messages using JWT. The redirects happen entirely in the browser and there is no direct connection between Fellow Digitals and your systems, so you can keep your authentication scripts safely behind your corporate firewall.

---

Implementation recipe

Authenticate the user

Make sure the user is authenticated at your end. Obtain the authenticated user's email address. This is what Fellow needs to uniquely identify your user.

Create the JWT token

Building the JWT token is pretty simple. We only require a small part of the spec. Please follow these guidelines:

• The email claim is required. This is the user for whom you make the request.
  
• The iat claim is required. This identifies the time at which your JWT was created. If your token is older than a couple of minutes, we will reject it.
  
• The jti claim is required. This is a unique identifier for your token. You can use tokens only once.
  
• Only HS256 is supported. Tokens with other algorithms are rejected.
  

To sign the JWT you need the shared JWT secret, which can be found under Setup → JWT SSO. Please note: your personal API key cannot be used here.

There are many open source JWT libraries available to help you construct the token. However, since our implementation is very straightforward, you could also do it yourself. Here's an example in plain PHP:

function jwt_token($email, $api_key)  
{  
    // create the header part:  
    $header = array('typ' => 'JWT', 'alg' => 'HS256');  
    $base64_header = base64url_encode(json_encode($header));  

    // create the claims part:  
    $claims = array('jti' => mt_rand(), 'iat' => time(), 'email' => $email);  
    $base64_claims = base64url_encode(json_encode($claims));  

    // create the signature:  
    $hash = hash_hmac('SHA256', $base64_header . '.' . $base64_claims, $api_key, true);  
    $base64_signature = base64url_encode($hash);  

    // concatenate the three parts:  
    $jwt = $base64_header . '.' . $base64_claims . '.' . $base64_signature;  
    return $jwt;  
}  

function base64url_encode($data)  
{  
    return rtrim(strtr(base64_encode($data), '+/', '-_'), '=');  
}  

Important! For security consideration your JWT should be valid for only a couple of minutes. Therefore its best to generate the JWT token only just before you redirect the user.

Tip: You can validate the syntax of your generated token here: https://jwt.io.

Redirect the user

Now make the URL where you will send your authenticated user, according to this template:

https://{yourFellowFQDN}/redirect?token={jwt}&locale={language}&next={path}  

• The token parameter is required. This is the signed JWT token containing the user's email address so we can grant the session.
  
• The locale parameter is optional. See our API page for supported languages.
  
• The next parameter is optional. This is the path of the page where the user must land. For a particular course, use the path /{courseId}/course
  

That's it!