Candidate Authentication with JWT

Introduction

The scenario is that there is a service integrating viasto’s interview suite to support the hiring process. A candidate who is already logged in in this service can go to the interview suite without logging in again with separate credentials. Because this service is usually an applicant tracking system this document will refer to it as ATS.

JWT

JWT provides a standardized and rather simple way for building Single Sign-on (SSO) solutions. For a brief introduction please have a look at the Wikipedia article about JWT. The website JWT.IO provides a list of libraries for many languages implementing the JWT standard.

Prerequisites

There are two things required to start using this authentication method:

• an existing candidate with the status invited or confirmed (refer to Candidate workflow)
• a shared secret key for signing the JWT payload (provided by viasto, please contact the helpdesk)

Usage

The ATS and the interview suite share a secret key. Using this secret key the ATS generates and signs JSON payload with the following information:

{
  "iat": <Unix timestamp when the token was generated>,
  "exp": <Unix timestamp when the token expires>,
  "identity": <interview suite Candidate ID>
}

The only signing algorithm supported is HS256.

The interview suite Candidate ID in the identity field was requested by the ATS in a previous API call. Then the generated JWT token can be used to build a link to the interview suite in the following format:

https://{{company_identifier}}.interview-suite.com/cfev3/auth/jwt/{{JWT_payload}}

Clicking on this link, given that the token is valid, will authenticate a user and give them access to the interview suite candidate frontend.

How it works

After clicking the link the interview suite receives a GET request. It will then try to verify the JWT token. If it is not valid an error page will be shown. Otherwise the Candidate ID is used to authenticate the user which results in giving them a proper session like they would get when authenticating via password. The user will then be redirected to welcome page.