AuthRocket uses tokens to tell your app about new logins. A new, unique token is created everytime someone logs in.
For hosted logins, including authrocket.js, AuthRocket generates the token and gives it to the user logging in. The user then passes that token on to your server so your backend app can verify that token.
AuthRocket’s login tokens are fully 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 style 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.
AuthRocket’s JWT login tokens also contain basic information about the user, and optionally, information about their 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.
JWTs are cryptographically signed using either a shared secret key or an asymetric key pair. AuthRocket uses a unique JWT secret per realm. In our UI, this secret is found on the Integration page of each Realm. It is also available from the Get a Realm API call.
This secret will be used by your app to verify the JWT and ensure it’s unmodified.
By default we use the HS256 signing algorithm. HS256 is both faster and smaller, but the key must be kept secret at all times.
We also support RS256. This key can be made public, making RS256 suitable for verifying keys from within browsers, native apps, or untrusted 3rd-party systems.
There are a number of existing JWT libraries, making JWT support easy to implement. We recommend libraries that automatically check the token’s expiration time (‘exp’). All of the below do so.
AuthRocket’s JWT’s contain a variety of user data:
iat- Issued at (login) time (JWT standard)
exp- Expiration time (JWT standard)
uid- AuthRocket User ID
fn- First name
ln- Last name
n- Full name
cs- User’s custom attributes
m- Array of Membership + Org data:
p- Array of permissions
cs- Membership’s custom attributes
oid- AuthRocket Org ID
o- Org name
ocs- Org’s custom attributes
Null values are simply left out. For example, if a user does not have a first name, the
fn attribute is left out entirely.
The Realm’s JWT Fields setting determines whether Membership, Org, and/or Custom attribute data is included in the JWT. By default, none of them are.
Normal JWT tokens are fairly small. Howver, they can grow to be quite large if various optional attributes are included (see Included token 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.
We only use
HS256 (our default) or
RS256 for JWT signing. If your JWT library allows you to specify the expected signing algorithm, we strongly recommend it.