FastBound allows third-party applications to sign their users into FastBound by passing a JSON Web Token (JWT) on the query string to any FastBound URL. Append your JWT as the token query string parameter, and FastBound will recognize it, parse it, and attempt to authorize your user.

You must email FastBound Support to enable Single Sign-On from your application. FastBound Support will provide you with a secret key that you will use to sign the JWTs that you send to us. Signed requests allow FastBound to verify that sign-on requests are legitimate. FastBound will also provide you with an issuer, which you must include in the JWT payload.

Each user that will sign onto FastBound via your application must have a FastBound user account. If they do not have a FastBound user account, when they try to sign in from your application, they will be prompted to create a FastBound user. After they have verified their email address, they will be able to sign on from your application.

The JWT.io Debugger allows you to quickly check that a JWT is well-formed and manually inspect the values of the various claims.

JWT Header

The header must contain two properties:

alg must be HS256
typ must be JWT

Example JWT Header (Open in JWT.io)

{
  "alg": "HS256",
  "typ": "JWT"
}

JWT Payload

The payload must contain the following properties:

jti must be unique, not null or empty, and at least 128 bits (16 characters) in length.
iss (Issuer) identifies the sender, your application. This will typically be a URL like https://myapp.example.com. FastBound will provide this to you ahead of time, along with the secret used to sign your JWTs.
iat (Issued At) is the UNIX timestamp in seconds of when the JWT was generated.
aud (Audience) identifies the recipient, FastBound. This must contain the scheme and hostname of the FastBound environment. In almost all cases, this will be https://cloud.fastbound.com.
sub (Subject) identifies the user that you are attempting to sign on to FastBound via your application. This must be a string that uniquely identifies the user within your application, and must never change.

Example JWT Payload (Open in JWT.io)

{
  "jti": "O0tr2XPGtXVxq4Kt",
  "iss": "https://myapp.example.com",
  "iat": 1375747200,
  "aud": "https://cloud.fastbound.com",
  "sub": "ba5eba11-b01d-face-f01d-ab1edeadbeef"
}

Digitally Signing the JWT

You must sign JWTs with the secret that is shared by you and FastBound. This secret is a base64-encoded string of random bytes. FastBound will reject any JWTs that are not signed, or where the signature is not valid.

Please treat this secret with the same care as you would any other password or security credential.

Since maintaining the privacy of this key is so vital, please DO NOT send it to your web pages for use in JavaScript or distribute this secret in installed client software applications.

Signing In

You can sign the user into FastBound by appending a token query string to any FastBound URL. FastBound will recognize the token query string parameter, and if we successfully parse it, allow the user to proceed.

If a user is not signed-in to FastBound, and we don’t recognize the subject (sub) in the JWT, FastBound will send the user to our sign-in screen. Once the user signs in successfully, we’ll redirect them to a page to confirm the sign-on for your application. After confirming, the user’s browser redirects to the original destination.

Recommended flow for generating JWTs in your application

FastBound allows for +/- 5 minutes of clock skew in JWTs. Any iat value that falls outside of this range will result in an Expired Token error. We recommend that you generate the JWT on whatever action the user takes that causes your application to try to sign the user into FastBound (e.g., when the user clicks a link or button).

Likewise, we recommend that you do not generate the JWT at page load time because the user might load the page and let it sit for > 5 minutes. When the user clicks on a button that takes them to FastBound, they will get an Expired Token error because the JWT is now more than 5 minutes old.

Example of our recommended web interaction that does not result in an Expired Token error

One of your application pages loads
The user clicks a link that will sign them into Fastbound. This link points to another page on your site that will first generate a JWT on demand, and then redirect the user to FastBound (e.g., <a href=’/RedirectToFastBound’>Goto FastBound</a>)
User visits /RedirectToFastBound
/RedirectToFastBound creates a JWT for the user, then redirects the user to https://cloud.fastbound.com/SomePath?token=YOUR_JWT_HERE
The JWT does not result in an Expired Token error

Example of a web interaction that could result in Expired Token errors:

One of your application pages loads
The user clicks a link that will sign them into Fastbound. This link contains a JWT created at page load time (e.g., <a href=’https://cloud.fastbound.com/SomePath?token=POTENTIALLY_EXPIRED_JWT’>Goto FastBound</a>)
Depending on how long ago the page loaded, the user might get an Expired Token error when trying to sign into FastBound

Again, we don’t recommend generating the JWTs in JavaScript in the browser because then your FastBound signing secret would no longer be secret.

Error Responses

Here are the errors you might encounter when trying to sign a user into FastBound via the token query string parameter:

Invalid Token is caused by a blank or malformed token query string parameter value.
Invalid Token (Issuer) is caused by the JWT’s iss value not matching a valid Issuer defined in FastBound. Please ensure it exactly matches the issuer provided to you by FastBound.
Invalid Token (Signature) is caused by the JWT having a signature that FastBound could not verify with the issuer’s secret, or the JWT having no signature at all.
Invalid Token (Audience) is caused by (1) the JWT’s aud value not being a well-formed URL, or (2) the JWT’s aud value not matching the host and scheme of the FastBound environment. (Reminder: unless you’re instructed otherwise, aud should always be https://cloud.fastbound.com.)
Invalid Token (ID) is caused by the JWT’s jti value being null or empty, less than 128 bits (16 characters) in length, or trying to use a single token more than once.
Expired Token is caused by the JWT’s iat value being more than 5 minutes in the past, or more than 5 minutes into the future.

Single Sign-On