Templated-JWT

Working with JWTs using templates.

Basic usage

• setup templates
• sign
• verify

const templatedJWT = new TemplatedJWT({
  sign: {
    auth: {
      type: token.Type.JWS,
      purpose: "auth",
      key: await importKey("secret"),
      claims: {
        exp: 300
      },
      headers: {
        alg: "HS256"
      }
    }
  },
  verify: {
    auth: {
      type: token.Type.JWS,
      purpose: "auth",
      key: await importKey("secret"),
    }
  }
})

const {jwt} = await templatedJWT.sign("auth", {}, {});

await templatedJWT.verify("auth", jwt);

Example flow

| User | Action | Server | | -------------------------------------------------------- |:------:| ------------------------------------------------------------------------------- | | Signs in | --> | Verify | | | | Generate Refresh or Session JWT as Session_token | | Store Session_token and its exp | <-- | Send Session_token Token | | | | | | Request Access_token sending Session_token | --> | Verify Session_token Token | | | | Generate Auth or Once JWT as Access_token | | Store Access_token and its exp | <-- | Send Access Token | | | ... | | | If API call: send Access_token | --> | Verify Access_token Token | | | | Perform API action | | | ... | | | If Session_token exp half time: send Session_token | --> | Verify Session_token Token | | | | Generate new Refresh or Session JWT as Session_token invalidating old one | | Store Session_token and its exp | <-- | Send Session_token Token | | | ... | | | If Access_token exp half time: send Session_token | --> | Verify Session_token Token | | | | Generate Auth or Once JWT as Access_token | | Store Access_token and its exp | <-- | Send Access Token | | | ... | | | Sign out: send Session_token | --> | Invalidate Session_toke |

List of example templates that can be used for different purposes.

Refresh | Refresh Token

• Long lived tokens.
• Can resign (create new token from this one).
• Should be revoked on resign or logout until exp.
• Can sign other tokens (like Auth).
• Should be used to authenticate a user to call APIs!

| Claim | Description | Value | | -----------:|:------------------------------------- | --------------------------------------------- | | iss | Issuer | issuer domain | | sub | Subject | user id | | aud | Audience | same as iss | | exp | Expiration Time | 30d | | nbf | Not Before | -3m | | iat | Issued At | Time of JWT creation | | jti | JWT ID | UUID | | sid | Session ID | This session UUID | | auth_time | Time when the authentication occurred | Time of first Refresh JWT creation or login |

Session | Session Token

• Indefinite tokens (server may impose a rule of max age).
• Should be stored as session and deleted on logout.
• Can sign other tokens (like Auth).
• Server should keep track of last usage time.
• Should be used to authenticate a user to call APIs!

| Claim | Description | Value | | -----------:| ------------------------------------- | --------------------------------------------- | | iss | Issuer | issuer domain | | sub | Subject | user id | | aud | Audience | same as iss | | nbf | Not Before | -3m | | iat | Issued At | Time of JWT creation | | jti | JWT ID | UUID | | sid | Session ID | This session UUID | | auth_time | Time when the authentication occurred | Time of first Refresh JWT creation or login |

Auth | Access Token

• Short lived token.
• Used to access API.
• No other JWT should be signed with it.
• If authenticating other systems use Asymmetric keys.

| Claim | Description | Value | | -----:| --------------- | -------------------- | | iss | Issuer | issuer domain | | sub | Subject | user id | | aud | Audience | specific API | | exp | Expiration Time | 15m | | nbf | Not Before | -3m | | iat | Issued At | Time of JWT creation | | jti | JWT ID | UUID | | sid | Session ID | This session UUID |

Once | Single use Access Token

• Used to access API only once.
• No other JWT should be signed with it.
• Should be rejected if nonce has been already used.
• If authenticating other systems use Asymmetric keys.

| Claim | Description | Value | | -------:| --------------- | -------------------- | | iss | Issuer | issuer domain | | sub | Subject | user id | | aud | Audience | specific API | | exp | Expiration Time | from 2m to 30d | | nbf | Not Before | -3m | | iat | Issued At | Time of JWT creation | | jti | JWT ID | UUID | | sid | Session ID | This session UUID | | nonce | Unique | Can be UUID |