Login tokens

Overview

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.

The JWTs that AuthRocket generates also include an expiration time by default. 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 the newer class of Javascript frameworks, such Angular, Backbone, Ember, etc.

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.

How to use JWTs

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.

• Go
• Java
• .NET
• node.js
• PHP
• Python
• Ruby
• Rust

The official AuthRocket PHP and AuthRocket Ruby libraries also include JWT support. See Decode a Session Token.

What’s inside a JWT

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
• un - Username
• 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.

Token size

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.

Additional notes

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.