class JOSE::JWT

• JOSE::JWT
• Reference
• Object

Overview

JWT (JSON Web Token) compact representation of claims (RFC 7519).

Tokens are backed by a Hash(String, JSON::Any) and can be signed (JWS) or encrypted (JWE). The seven RFC 7519 registered claims (#iss, #sub, #aud, #exp, #nbf, #iat, #jti) are available as typed accessors. Use the claim macro to define additional typed claims in a subclass:

require "jose"

class MyJWT < JOSE::JWT
  claim role : String?
end

jwk = JOSE::JWK.generate_key_oct

tok = MyJWT.new
tok.sub = "alice"
tok.role = "admin"
tok.exp = Time.utc + 1.hour

signed = JOSE::JWT.sign(jwk, tok)
valid, decoded, _header = JOSE::JWT.verify_strict(jwk, ["HS256"], signed)
my_jwt = MyJWT.from_map(decoded.to_map)
my_jwt.sub  # => "alice"
my_jwt.role # => "admin"

Defined in:

jose/jwt.cr

Constructors

• .decrypt(jwk : JWK, encrypted : String | EncryptedBinary) : JWT

  Decrypts a compact JWE and returns the contained JWT.

• .from_binary(json : String) : self

  Parses a JSON string and returns a JWT.

• .from_map(map : Hash(String, JSON::Any)) : self

  Wraps an existing claims map in a JWT.

• .new(fields : Hash(String, JSON::Any))
• .new
• .peek(compact : String) : JWT

  Alias for .peek_payload.

• .peek_payload(compact : String) : JWT

  Decodes the payload of compact as a JWT without verifying the signature.

Class Method Summary

• .encrypt(jwk : JWK, jwt : JWT, header_overrides : Hash(String, JSON::Any) | Nil = nil) : EncryptedBinary

  Encrypts jwt for jwk and returns a compact EncryptedBinary.

• .peek_protected(compact : String) : Hash(String, JSON::Any)

  Decodes the protected header of compact without verifying.

• .sign(jwk : JWK, jwt : JWT, header_overrides : Hash(String, JSON::Any) | Nil = nil) : SignedBinary

  Signs jwt with jwk and returns a compact SignedBinary.

• .verify(jwk : JWK, signed : String | SignedBinary) : Tuple(Bool, JWT, Hash(String, JSON::Any))

  Verifies a compact JWS carrying JWT claims.

• .verify_strict(jwk : JWK, allowed_algs : Array(String), signed : String | SignedBinary, *, iss : String | Nil = nil, aud : String | Array(String) | Nil = nil, typ : String | Nil = nil, validate_claims : Bool = true) : Tuple(Bool, JWT, Hash(String, JSON::Any))

  Like .verify but enforces RFC 8725 best-current-practices on top of the cryptographic signature check.

Macro Summary

• claim(decl)

Instance Method Summary

• #[](key : String) : JSON::Any

  Returns the claim for key, raising KeyError when absent.

• #[]?(key : String) : JSON::Any | Nil

  Returns the claim for key, or nil when absent.

• #aud : String | Array(String) | Nil
• #aud=(value : String | Array(String) | Nil)
• #exp : Time | Nil
• #exp=(value : Time | Nil)
• #expired?(now : Time = Time.utc) : Bool

  Returns true if #exp is set and is in the past relative to now.

• #fields : Hash(String, JSON::Any)

  The claims map backing this token.

• #iat : Time | Nil
• #iat=(value : Time | Nil)
• #iss : String | Nil

  String (default fallthrough)

• #iss=(value : String | Nil)

  ── RFC 7519 Registered Claims ───────────────────────────────────────────

• #jti : String | Nil

  String (default fallthrough)

• #jti=(value : String | Nil)
• #nbf : Time | Nil
• #nbf=(value : Time | Nil)
• #not_yet_valid?(now : Time = Time.utc) : Bool

  Returns true if #nbf is set and has not yet been reached relative to now.

• #sub : String | Nil

  String (default fallthrough)

• #sub=(value : String | Nil)
• #to_binary : String

  Serializes the claims to a compact JSON string.

• #to_map : Hash(String, JSON::Any)

  Returns the underlying claims map.

• #valid_at?(now : Time = Time.utc) : Bool

  Returns true if the token is currently valid: not expired and nbf has passed.

Constructor Detail

Class Method Detail

Macro Detail

Instance Method Detail