Guardian

v0.13.0

Guardian v0.13.0 Guardian

A module that provides JWT based authentication for Elixir applications.

Guardian provides the framework for using JWT in any Elixir application, web based or otherwise, where authentication is required.

The base unit of authentication currency is implemented using JWTs.

Configuration

config :guardian, Guardian,
  allowed_algos: ["HS512", "HS384"],
  issuer: "MyApp",
  ttl: { 30, :days },
  serializer: MyApp.GuardianSerializer,
  secret_key: "lksjdlkjsdflkjsdf"

Summary

Functions

decode_and_verify(jwt)

Verify the given JWT. This will decode_and_verify via decode_and_verify/2

decode_and_verify(jwt, params)

Verify the given JWT

decode_and_verify!(jwt)

If successfully verified, returns the claims encoded into the JWT. Raises otherwise

decode_and_verify!(jwt, params)

If successfully verified, returns the claims encoded into the JWT. Raises otherwise

default_token_type()

Returns the current default token type

encode_and_sign(object)

Encode and sign a JWT from a resource. The resource will be run through the configured serializer to obtain a value suitable for storage inside a JWT

encode_and_sign(object, type)

Like encode_and_sign/1 but also accepts the type (encoded to the typ key) for the JWT

encode_and_sign(object, type, claims)

Like encode_and_sign/2 but also encode anything found inside the claims map into the JWT

issuer()

The configured issuer. If not configured, defaults to the node that issued

peek_claims(token)

Read the claims of the token. This is not a verified read, it does not check the signature

peek_header(token)

Read the header of the token. This is not a verified read, it does not check the signature

refresh!(jwt)

Refresh the token. The token will be renewed and receive a new

refresh!(jwt, claims, params \\ %{})

As refresh!/1 but allows the claims to be updated. Specifically useful is the ability to set the ttl of the token

revoke!(jwt, params \\ %{})

Revokes the current token. This provides a hook to revoke. The logic for revocation of belongs in a Guardian.Hook.on_revoke This function is less efficient that revoke!/2. If you have claims, you should use that

revoke!(jwt, claims, params)

Revokes the current token. This provides a hook to revoke. The logic for revocation of belongs in a Guardian.Hook.on_revoke

serializer()

Fetch the configured serializer module

set_aud_if_nil(claims, value)
verify_claims(claims, params)

Functions

decode_and_verify(jwt)

Specs

decode_and_verify(String.t) ::
  {:ok, map} |
  {:error, atom} |
  {:error, String.t}

Verify the given JWT. This will decode_and_verify via decode_and_verify/2

decode_and_verify(jwt, params)

Specs

decode_and_verify(String.t, map) ::
  {:ok, map} |
  {:error, atom | String.t}

Verify the given JWT.

decode_and_verify!(jwt)

Specs

decode_and_verify!(String.t) :: map

If successfully verified, returns the claims encoded into the JWT. Raises otherwise

decode_and_verify!(jwt, params)

Specs

decode_and_verify!(String.t, map) :: map

If successfully verified, returns the claims encoded into the JWT. Raises otherwise

default_token_type()

Returns the current default token type.

encode_and_sign(object)

Specs

encode_and_sign(any) ::
  {:ok, String.t, map} |
  {:error, atom} |
  {:error, String.t}

Encode and sign a JWT from a resource. The resource will be run through the configured serializer to obtain a value suitable for storage inside a JWT.

encode_and_sign(object, type)

Specs

encode_and_sign(any, atom | String.t) ::
  {:ok, String.t, map} |
  {:error, atom} |
  {:error, String.t}

Like encode_and_sign/1 but also accepts the type (encoded to the typ key) for the JWT

The type can be anything but suggested is “access”.

encode_and_sign(object, type, claims)

Specs

encode_and_sign(any, atom | String.t, map) ::
  {:ok, String.t, map} |
  {:error, atom} |
  {:error, String.t}

Like encode_and_sign/2 but also encode anything found inside the claims map into the JWT.

To encode permissions into the token, use the :perms key and pass it a map with the relevant permissions (must be configured)

Example

Guardian.encode_and_sign(
  user,
  :access,
  perms: %{ default: [:read, :write] }
)
issuer()

Specs

issuer :: String.t

The configured issuer. If not configured, defaults to the node that issued.

peek_claims(token)

Read the claims of the token. This is not a verified read, it does not check the signature.

peek_header(token)

Read the header of the token. This is not a verified read, it does not check the signature.

refresh!(jwt)

Specs

refresh!(String.t) ::
  {:ok, String.t, map} |
  {:error, any}

Refresh the token. The token will be renewed and receive a new:

  • jti - JWT id
  • iat - Issued at
  • exp - Expiry time.
  • nbf - Not valid before time

The current token will be revoked when the new token is successfully created.

Note: A valid token must be used in order to be refreshed.

refresh!(jwt, claims, params \\ %{})

Specs

refresh!(String.t, map, map) ::
  {:ok, String.t, map} |
  {:error, any}

As refresh!/1 but allows the claims to be updated. Specifically useful is the ability to set the ttl of the token.

Guardian.refresh(existing_jwt, existing_claims, %{ttl: { 5, :minutes}})

Once the new token is created, the old one will be revoked.

revoke!(jwt, params \\ %{})

Revokes the current token. This provides a hook to revoke. The logic for revocation of belongs in a Guardian.Hook.on_revoke This function is less efficient that revoke!/2. If you have claims, you should use that.

revoke!(jwt, claims, params)

Revokes the current token. This provides a hook to revoke. The logic for revocation of belongs in a Guardian.Hook.on_revoke

serializer()

Specs

serializer :: atom

Fetch the configured serializer module

set_aud_if_nil(claims, value)
verify_claims(claims, params)