App Options

This page walks you through every option you have for an app that uses JustAuthenticateMe.

The Interface

All of the options discussed on this page are found when you create a new app or edit an existing app via the JustAuthenticateMe console.

Screenshot of "Add App" form

App Name

The first option is the app name. This is used for two purposes:

  1. For you to identify your app in the JustAuthenticateMe console.
  2. For your users to identify the login email that they receive.

That second reason is particularly important. When you initiate authentication for a user, they will receive an email from no-reply@justauthenticate.me with two indicators that the email is for logging in to your app.

  1. The subject will contain the app name: Log in to ${appName}.
  2. The body will have a large header that says the app name (if you use the default email template).

It ends up looking something like this (default email template shown):

Screenshot of Log In Email

Because of this, it's recommended that you set your production app name to something short and easily recognizable.

Redirect URL

When a user clicks a "Log In Now!" link from an email as seen above, JustAuthenticateMe creates a token(s) for them and needs to return that token(s) to your app. It returns the token(s) to your app via the Redirect URL.

JustAuthenticateMe will make a GET request to the URL you provide with one or two query string parameters:

  1. idToken will be a JWT with a couple claims. Most importantly, the email claim will be the user's email.
  2. refreshToken will be a secure token that only this user can use to fetch a new ID token after the current one expires. This is only included if you enabled Refresh.

Succinctly, your app should expect a GET to:

${redirectURL}?idToken=longBase64String&refreshToken=anotherLongBase64String

So make sure you have an API endpoint or page with javascript ready to handle that request. You'll typically want to grab the tokens, store them in a safe place, and then redirect to the logged in page of your app.

Allow Refresh

This checkbox turns on or off the suite of "refresh" features for your app that JustAuthenticateMe can provide.

When checked, JustAuthenticateMe will generate refresh tokens for your users and provide them alongside the ID token via the Redirect URL. Then, your app can use JustAuthenticateMe's refresh API to fetch fresh ID tokens for your users when their current ID tokens expire.

When not checked, new refresh tokens will not be generated and existing refresh tokens will not be honored. Your user's session will last precisely as long as the ID Token TTL and no longer.

Should you allow refresh?

This will vary from app to app. Refresh tokens are convenient for your users because they won't have to log in as frequently; however, it will be a bit more work for you to implement, and you'll be responsible for handling an additional secret value for your users.

Whether this tradeoff is worth it largely depends on the usage patterns of your app. If your users typically only use your app for sessions that fit within a reasonable ID Token TTL, then you may be fine without refresh tokens. If your users frequently access your app for longer sessions, or return to your app many times per day, refresh tokens will probably enhance your UX.

ID Token TTL

The ID Token TTL is the number of seconds that a user's ID token is valid. Because ID Tokens are stateless and cannot be revoked, you typically want to keep this as short as reasonably possible.

If you are using refresh tokens, then we just want the TTL to be long enough that your app won't have to use the refresh token too frequently. A typical TTL in this case might be around 10 or 15 minutes (600 or 900 seconds, respectively).

If you aren't using refresh tokens, then you can reasonably make the ID Token TTL a bit larger to accomodate the average session length of a user. We don't recommend setting the TTL to anything longer than 2 hours (7200 seconds).

Email Template

By default, JustAuthenticateMe uses an attractive but generic email for all login emails to users. We understand that you may want to customize this template for your apps' brand and identity. This field allows you to write your own email and insert the magic link that JustAuthenticateMe provides.

This template is interpreted as an HTML email, so use <br> for line breaks. We suggest using a tool like https://putsmail.com to test out your HTML emails.

You must include the text ${MAGIC_LINK} somewhere in your email template. This piece of text will be replaced by the actual link that your user will click to log in.

You can leave this field blank to use JustAuthenticateMe's standard email template.

Coming Soon

JustAuthenticateMe is under active development, and new features will be arriving soon that allow further customization.

Refresh Token TTLs

Currently, refresh tokens are valid forever as long as they are used at least once every 7 days. This is a pretty lenient policy that covers the widest variety of use cases possible, but may be too lenient for your app. We will be adding two configuration options for refresh tokens:

  1. Refresh Token Lifetime TTL: This will be the total time from issuance that a refresh token is valid. If this is set to 10 days, the user will have to log in again 10 days after initial login.
  2. Refresh Token Frequency TTL: This will be the amount of time since the last use that the refresh token is valid. If this is set to 1 day, then the refresh token must be used at least once a day to stay valid.

Feedback

If you need help or are missing a configuration that your app needs, please reach out to support@justauthenticate.me. We're eager to make JustAuthenticateMe work for your use case.