View Source AshAuthentication.Jwt (ash_authentication v3.0.3)

Uses the excellent joken hex package to generate and sign Json Web Tokens.

configuration

Configuration

There are a few things we need to know in order to generate and sign a JWT:

  • signing_algorithm - the crypographic algorithm used to to sign tokens. Instance-wide configuration is configured by the application environment, but can be overriden on a per-resource basis.
  • token_lifetime - how long the token is valid for (in hours). Instance-wide configuration is configured by the application environment, but can be overriden on a per-resource basis.
  • signing_secret - the secret key used to sign the tokens. Only configurable via the application environment.
config :ash_authentication, AshAuthentication.Jwt,
  signing_algorithm: "HS256"
  signing_secret: "I finally invent something that works!",
  token_lifetime: 168 # 7 days

Available signing algorithms are Ed448ph, Ed448, Ed25519ph, Ed25519, PS512, PS384, PS256, ES512, ES384, ES256, RS512, RS384, RS256, HS512, HS384 or HS256. Defaults to HS256.

We strongly advise against storing the signing secret in your mix config. We instead suggest you make use of runtime.exs and read it from the system environment or other secret store.

The default token lifetime is 168 and should be specified in integer positive hours.

Link to this section Summary

Types

"claims" are the decoded contents of a JWT. A map of (short) string keys to string values.

A string likely to contain a valid JWT.

Functions

The default signing algorithm

The default token lifetime

Given a token, read it's claims without validating.

Supported signing algorithms

Given a user, generate a signed JWT for use while authenticating.

Given a token, find a matching resource configuration.

Given a token, verify it's signature and validate it's claims.

Link to this section Types

@type claims() :: %{
  required(String.t()) => String.t() | number() | boolean() | claims()
}

"claims" are the decoded contents of a JWT. A map of (short) string keys to string values.

@type token() :: String.t()

A string likely to contain a valid JWT.

Link to this section Functions

@spec default_algorithm() :: String.t()

The default signing algorithm

@spec default_lifetime_hrs() :: pos_integer()

The default token lifetime

@spec peek(token()) :: {:ok, claims()} | {:error, any()}

Given a token, read it's claims without validating.

@spec supported_algorithms() :: [String.t()]

Supported signing algorithms

Link to this function

token_for_user(user, extra_claims \\ %{}, opts \\ [])

View Source
@spec token_for_user(Ash.Resource.record(), extra_claims :: %{}, options :: keyword()) ::
  {:ok, token(), claims()} | :error

Given a user, generate a signed JWT for use while authenticating.

Link to this function

token_to_resource(token, otp_app)

View Source
@spec token_to_resource(token(), module()) :: {:ok, Ash.Resource.t()} | :error

Given a token, find a matching resource configuration.

warning

Warning

This function does not validate the token, so don't rely on it for authentication or authorisation.

Link to this function

verify(token, otp_app_or_resource)

View Source
@spec verify(token(), Ash.Resource.t() | atom()) ::
  {:ok, claims(), Ash.Resource.t()} | :error

Given a token, verify it's signature and validate it's claims.