Single sign-on is a mechanism that allows you to authenticate users in your system and then tell another application, in this case, Checkbox, that the user has been authenticated and should be granted access to the application. The user is then allowed to access Checkbox without being prompted to present a username or password to Checkbox directly.
Checkbox relies on a technology called JWT (JSON Web Token) for securing the exchange of user authentication data. This technology allows you to tell Checkbox, in a secure way, that users are authenticated.
Single sign-on with JWT is currently available on all plans except for the Basic Checkbox Online plan.
Enabling JWT
To enable JWT with Checkbox you will want to navigate to the Checkbox System Settings -> UserSettings -> Users & Security. You will want to select the option to enable JWT, generate a secure token as well as supply the system with a return URL. The return URL will be where the user is redirected if the token fails for whatever reason. This prevents them from ever seeing the Checkbox login screen.
The Process
- User logs into your application or web site
- They click a link on your site to either create & manage surveys or to submit a survey response
- You write code in your system that generates a secure JWT token and then redirects them to
the Checkbox application - Checkbox parses the JWT token, verifies the secure key, and then logs the user into the system
that matches the email address in the token
Additional information about JWT
JWT is an open standard that is being driven by the international standards body IETF and is backed by top-level organizations such as Microsoft, Facebook, and Google.
One thing to be aware of is that the JWT payload is merely encoded and signed, not encrypted, so don’t put any sensitive data in the hash table. JWT works by serializing the JSON that is being transmitted to a string. It then base64 encodes that string and then makes an HMAC of the base64 string which depends on the shared secret key. This produces a signature that the recipient side can use to validate the user.