JavaScript API

i·views 5.4

Class: JWT

$k. JWT

new $k.JWT(user, expiry, claims)

Creates a new token

Name Type Description
user $k.User optional
expiry object optional

Either a number (expiry in seconds since the current date), or a date. Default is 24 hours
claims object optional
Version:
  • Experimental feature, might be removed at any time
Since:
  • 5.1.0 Generate and verify JSON web tokens for REST requests

Methods

static$k.JWT.createKeys(overwrite)

Creates persistent keys for signing

Name Type Description
overwrite boolean optional

True (default) if existing keys should be overwritten, false if keys should only be generated if there are no keys yet.
Version:
  • Experimental feature, might be removed at any time
Since:
  • 5.1.0
Throws:
Type Description
$k.exception.AccessDenied

If generating keys is not allowed

static$k.JWT.parse(encodedToken) : JSONWebToken

Parses an encoded token. Does not check its validity.

Name Type Description
encodedToken string
Version:
  • Experimental feature, might be removed at any time
Since:
  • 5.1.0
Throws:
Type Description
$k.exception.InvalidValue

If the string is not a valid token
Returns:
Type Description
JSONWebToken Token

static$k.JWT.verify(token, expectedClaims, key)

Verifies the token. Shortcut for $k.JWT.parse(token).verify(claims, key)

Name Type Description
token string

Token to verify
expectedClaims object optional

Expected claims.
key string optional

Encoded key. If not provided, a volume specific persistent key is used. Available since 5.2.2..


Expected formats:

  • Symmetric key (e.g. HS256): base64 encoded secret key
  • Public key: PEM-encoded certificate
  • Private key: PEM-encoded private key
Version:
  • Experimental feature, might be removed at any time
Since:
  • 5.1.0
Deprecated
  • Use $k.JWT.parse(token).verify(claims, key)
    Throws:
    Type Description
    $k.exception.AccessDenied

    If the token could not be verified

    addClaims(claims)

    Adds additional claims. Overwrites claims with the same name

    Name Type Description
    claims object
    Version:
    • Experimental feature, might be removed at any time
    Since:
    • 5.1.0

    payload() : object

    Returns the payload object

    Version:
    • Experimental feature, might be removed at any time
    Since:
    • 5.1.0
    Throws:
    Type Description
    $k.exception.InvalidValue

    If the payload is not valid JSON
    Returns:
    Type Description
    object

    setExpiry(expiry)

    Set the expiry claim of the token

    Name Type Description
    expiry object

    Either a number (expiry in seconds since the current date), or a date
    Version:
    • Experimental feature, might be removed at any time
    Since:
    • 5.1.0

    setPayload()

    Sets the payload object

    Version:
    • Experimental feature, might be removed at any time
    Since:
    • 5.2.2

    setRenew(duration)

    Set the renew claim of the token

    Name Type Description
    duration object

    Duration in seconds
    Version:
    • Experimental feature, might be removed at any time
    Since:
    • 5.1.0
    Deprecated
    • Do not use any more. This custom claim is not used.

      setSubject(subject)

      Set the subject claim of the token

      Name Type Description
      subject string

      Subject
      Version:
      • Experimental feature, might be removed at any time
      Since:
      • 5.1.0

      setUser(user)

      Set the ID of the user as the subject of the token. Do not use if a REST service expects a different subject value (e.g. E-Mail).

      Name Type Description
      user $k.User
      Version:
      • Experimental feature, might be removed at any time
      Since:
      • 5.1.0

      sign(key, algorithm) : string

      Signs the token.

      This method does not check the authentication of the user. This allows custom authentication mechanisms. Use $k.User.getAuthenticatedUser() for built-in username/password checking.

      Name Type Description
      key string optional

      Encoded key. If not provided, a volume specific persistent key is used. Available since 5.2.2..


      Expected formats:

      • Symmetric key (e.g. HS256): base64 encoded secret key
      • Public key: PEM-encoded certificate
      • Private key: PEM-encoded private key
      algorithm string optional

      Algorithm to use. Default is HS256. Available since 5.2.2.
      Version:
      • Experimental feature, might be removed at any time
      Since:
      • 5.1.0
      See:
      • $k.User#getAuthenticatedUser
      Returns:
      Type Description
      string Signed, encoded token (
      ..)

      verify(expectedClaims, key, algorithm)

      Verifies the token.

      Name Type Description
      expectedClaims object optional

      Expected claims. If undefined then only expiry will be checked.
      key string optional

      Encoded key. If not provided, a volume specific persistent key is used. Available since 5.2.2..


      Expected formats:

      • Symmetric key (e.g. HS256): base64 encoded secret key
      • Public key: PEM-encoded certificate
      • Private key: PEM-encoded private key
      algorithm string optional

      Algorithm to use. Default is HS256. Available since 5.2.2.
      Version:
      • Experimental feature, might be removed at any time
      Since:
      • 5.1.0
      Throws:
      Type Description
      $k.exception.AccessDenied

      If the token could not be verified (e.g. invalid token or unsupported algorithm)