Login tokens

Overview

AuthRocket uses tokens to tell your app about new logins. A new, unique token is created everytime someone logs in.

When a user performs a login, a new token is generated and given to the user by LoginRocket. The user then passes that token on to your server so your backend app can verify that token.

AuthRocket’s login tokens are JWT compatible. JWT, which stands for JSON Web Token, is a way of encoding various data into the login token while representing the token as a string of characters. Because they’re simple strings, JWT tokens are extremely easy to pass around between AuthRocket, your user, and your app.

Additionally, JWTs are digitally signed, making it possible to verify that the contents of the JWT are unchanged. Using the signature, your app can verify the token without making an API call back to AuthRocket, reducing login time for your users.

The JWTs that AuthRocket generates also include an expiration time. This makes it possible to use JWTs as session tokens for the duration of a user’s session. While most traditional web frameworks provide some kind of built-in session handling, JWTs are very useful for modern Javascript app frameworks, such as Angular, React, etc.

AuthRocket’s JWT tokens also include OpenID Connect compatible fields containing basic information about the user, and optionally, information about their account (memberships and orgs). This wealth of information right in the JWT significantly reduces the number of API calls your app would otherwise have to make, making everything faster.

How to use JWTs

JWTs are cryptographically signed using either an asymmetric key pair (default) or a shared secret key. AuthRocket uses a unique JWT key/secret per realm. In our UI, the key/secret is found at Settings -> Realm -> Sessions & JWT. It is also shown in the Integration section for relevant integration types. In the API, it is available via the Get a Realm API call. The public key half of an asymmetric key pair is also available from LoginRocket at https://your-lr-subdomain.loginrocket.com/connect/jwks.

This key/secret will be used by your app to verify the JWT and ensure it’s unmodified.

By default we use the RS256 signing algorithm. This key can be made public, making RS256 suitable for verifying keys from within browsers, native apps, or untrusted 3rd-party systems. It is also safe to commit RS256 keys into your code (although you may choose to use ENV variables or other traditional mechanisms instead, especially if switching between realms).

We also support HS256. HS256 keys must be kept secret at all times and keys must be rotated immediately if accidentally disclosed.

JWT libraries

AuthRocket provides some official libraries that include JWT verification as well as help decoding the embedded data.

See Decode a Session Token for syntax for each of these.

For other languages, there are a number of available JWT libraries, making JWT support easy to implement.

Some JWT libraries require you to explicitly enable expiration checking (the exp claim). Others don’t support it at all and will require you to perform such checks yourself. Without expiration checks, login tokens will effectively never expire!

We recommend libraries that automatically check expiration times. All of the above do so.

What’s inside a JWT

AuthRocket’s JWT’s contain a variety of user data:

Null values are simply left out. For example, if a user does not have a first name, the given_name attribute is left out.

Selecting fields

Most token fields are included by default, but a few are optional and must be enabled by setting Realm.jwt_scopes.

For tokens delivered by LoginRocket, orgs is always included with exactly one element, matching the current/selected account (org & membership). In multi-user account mode, redirect the user to LoginRocket to switch between accounts. When the user is returned to your app, a new token will be sent with the newly selected account.

For sessions retrieved via the AuthRocket API, both Realm.jwt_scopes and the query param org_id affect the results:

org_id missing org_id present
jwt_scopes without ar.orgs no orgs one orgs element matching org_id (like LR)
jwt_scopes with ar.orgs all orgs all orgs, with org_id marked selected

For behavior like LoginRocket, include org_id when using Get a session and exclude ar.orgs from Realm.jwt_scopes.

Token size

Typically JWT tokens are fairly small and are unlikely to cause any operational problems. However, using ar.orgs or cs can add significant amounts of additional data.

This can cause occasional issues with HTTP servers or reverse proxies and may require that such programs be configured to allow long URIs or long headers. Mostly this is only a concern when the token itself is part of the URL.

In our experience, tokens up to 2KB in size will work fine nearly everywhere. Tokens between 2KB and 4KB sometimes require work arounds, but can usually be made to work. Tokens over 4KB may require more attention as to how they are stored and passed around. For example, cookies are limited to 4KB, so a JWT greater than 4KB can’t be stored inside a cookie.

Additional notes

We only use RS256 (our default) or HS256 for JWT signing. If your JWT library allows you to specify the expected signing algorithm, we strongly recommend it.

Contents
Overview How to use JWTs JWT libraries What's inside a JWT Selecting fields Token size Additional notes