Auctoritas v0.4.0 Auctoritas View Source
Auctoritas
Session like authentication library for Elixir applications
- Documentation: HexDocs
Installation
If available in Hex, the package can be installed
by adding auctoritas
to your list of dependencies in mix.exs
:
def deps do
[
{:auctoritas, "~> 0.2.0"}
]
end
Basic Usage
iex> alias Auctoritas.AuthenticationManager, as: Auth
Auctoritas.AuthenticationManager
iex> user_data = %{username: "USERNAME", password: "PASSWORD"}
%{username: "USERNAME", password: "PASSWORD"}
iex> token_data = %{user_id: 1, username: "USERNAME", email: "USERNAME@EMAIL.COM"}
%{user_id: 1, username: "USERNAME", email: "USERNAME@EMAIL.COM"}
iex> {:ok, token} = Auth.authenticate(user_data, token_data)
{:ok, "35cdc028d1623b58f616d21386d1c7982b25183776b7af69f9bb7dc0852a5095"}
iex> {:ok, data} = Auth.get_token_data(token)
{:ok,
%Auctoritas.AuthenticationManager.DataStorage.Data{
data: %{email: "USERNAME@EMAIL.COM", user_id: 1, username: "USERNAME"},
metadata: %{
expires_in: 86385250,
inserted_at: 1547158890,
updated_at: 1547158890
}
}}
iex> {:ok, data} = Auth.deauthenticate(token)
{:ok, true}
Configuration
config :auctoritas, :config,
name: "auctoritas_default", # Custom name if you need multiple auctoritas authentication managers
data_storage: Auctoritas.AuthenticationManager.DataStorage, # Custom data_storage implementation (default is Cachex)
token_manager: Auctoritas.AuthenticationManager.DefaultTokenManager, # Custom token_manager implementation
expiration: 86400 # Token expiration timer in second
Spawning Auctoritas authentication managers
iex> alias Auctoritas.AuthenticationManager, as: Auth
Auctoritas.AuthenticationManager
iex> alias Auctoritas.Config
Auctoritas.Config
iex> config = Config.new(name: "custom_name", token_manager: CustomTokenManager, expiration: 120)
%Auctoritas.Config{
data_storage: Auctoritas.AuthenticationManager.DataStorage,
expiration: 120,
name: "custom_name",
token_manager: CustomTokenManager
}
iex> alias Auctoritas.AuthenticationSupervisor
Auctoritas.AuthenticationSupervisor
iex> AuthenticationSupervisor.start_link(config)
{:ok, #PID<0.278.0>}
iex> {:ok, token} = Auth.authenticate("custom_name", %{username: "username"}, %{})
{:ok, "3acbc9f1362ba9fb09fc3db6e4e1f6cfa5fcd2738156d11461cab3bd0ed92940"}
Implementing token_manager
For custom token_manager you need to implement Auctoritas.TokenManager
behaviour
defmodule Auctoritas.TokenManager do
@type token() :: String.t()
@type name() :: String.t()
@callback generate_token(name(), any()) :: {atom(), token()}
@callback authentification_data_check(name(), any()) :: {atom(), any()}
@callback data_check(name(), any()) :: {atom(), any()}
end
Simplest way to implement Auctoritas.TokenManager
behaviour is to inject default TokenManager into your own module with __using__
macro
defmodule CustomTokenManager do
use Auctoritas.AuthenticationManager.TokenManager
end
Now you can override default functions to suit your own needs
defmodule CustomTokenManager do
use Auctoritas.AuthenticationManager.TokenManager
@spec authentification_data_check(name(), map()) :: {atom(), any()}
def authentification_data_check(name, data) when is_bitstring(name) and is_map(data) do
case data do
%{password: "secret_password"} -> {:ok, data}
_ -> {:error, "Invalid user credentials"}
end
end
end
Link to this section Summary
Types
Token expiration in seconds
Name from config (Auctoritas supervisor name)
Authentication token
Functions
Authenticate with supplied arguments to default authentication_manager;
- authentication_data is checked and then used to generate token
- data is stored inside data_storage with token as the key
Authenticate with supplied arguments to custom authentication_manager;
- authentication_data is checked and then used to generate token
- data is stored inside data_storage with token as the key
Returns a specification to start this module under a supervisor
Deauthenticate supplied token from default authentication_manager
Deauthenticate supplied token from custom authentication_manager
Get associated token data; Token : f3ae51e91f9a882422b52da3fc759a271ca61fde152f64caf9f6ce86161f5c20 refresh token: 48cc25bd6bb4f1f850df4191365227ba88aad241574f3ed448774a5658f5dac8
Examples
iex> Auctoritas.AuthenticationManager.authenticate(%{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
Get associated token data;
Invoked when the server is started. start_link/3
or start/3
will
block until it returns
Start Auctoritas GenServer with specified config (from Auctoritas.Config
)
Link to this section Types
expiration()
View Source
expiration() :: non_neg_integer()
expiration() :: non_neg_integer()
Token expiration in seconds
name()
View Source
name() :: String.t()
name() :: String.t()
Name from config (Auctoritas supervisor name)
token()
View Source
token() :: String.t()
token() :: String.t()
Authentication token
Link to this section Functions
authenticate(authentication_data) View Source
Authenticate with supplied arguments to default authentication_manager;
- authentication_data is checked and then used to generate token
- data is stored inside data_storage with token as the key
Examples
iex> Auctoritas.AuthenticationManager.authenticate(%{username: "username"}, %{user_id: 1})
{:ok, "ec4eecaff1cc7e9daa511620e47203424e70b9c9785d51d11f246f27fab33a0b"}
authenticate(name, authentication_data) View Source
Authenticate with supplied arguments to custom authentication_manager;
- authentication_data is checked and then used to generate token
- data is stored inside data_storage with token as the key
Examples
iex> Auctoritas.AuthenticationManager.authenticate("custom_name", %{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
child_spec(arg) View Source
Returns a specification to start this module under a supervisor.
See Supervisor
.
deauthenticate(token, atom) View Source
Deauthenticate supplied token from default authentication_manager
Examples
iex> Auctoritas.AuthenticationManager.authenticate(%{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
iex> Auctoritas.AuthenticationManager.deauthenticate("0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633")
{:ok, true}
deauthenticate(name, token, atom) View Source
Deauthenticate supplied token from custom authentication_manager
Examples
iex> Auctoritas.AuthenticationManager.authenticate("custom_name", %{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
iex> Auctoritas.AuthenticationManager.deauthenticate("custom_name", "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633")
{:ok, true}
get_refresh_tokens(start, amount) View Source
get_refresh_tokens(name, start, amount) View Source
get_token_data(token) View Source
Get associated token data; Token : f3ae51e91f9a882422b52da3fc759a271ca61fde152f64caf9f6ce86161f5c20 refresh token: 48cc25bd6bb4f1f850df4191365227ba88aad241574f3ed448774a5658f5dac8
Examples
iex> Auctoritas.AuthenticationManager.authenticate(%{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
iex> Auctoritas.AuthenticationManager.get_token_data("0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633")
{:ok,
%Auctoritas.AuthenticationManager.DataStorage.Data{
data: %{user_id: 1},
metadata: %{
expires_in: 86310242,
inserted_at: 1547201115,
updated_at: 1547201115
}
}}
get_token_data(token, token) View Source
Get associated token data;
Examples
iex> Auctoritas.AuthenticationManager.authenticate("custom_name", %{username: "username"}, %{user_id: 1})
{:ok, "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633"}
iex> Auctoritas.AuthenticationManager.get_token_data("custom_name", "0a0c820b3640bca38ec482da31510803e369e7b90dfc01cb1e571b7970b02633")
{:ok,
%Auctoritas.AuthenticationManager.DataStorage.Data{
data: %{user_id: 1},
metadata: %{
expires_in: 86310242,
inserted_at: 1547201115,
updated_at: 1547201115
}
}}
get_token_data(name, token, atom) View Source
get_tokens(start, amount) View Source
get_tokens(name, start, amount) View Source
get_tokens_with_data(start, amount) View Source
get_tokens_with_data(name, start, amount) View Source
init(config) View Source
Invoked when the server is started. start_link/3
or start/3
will
block until it returns.
args
is the argument term (second argument) passed to start_link/3
.
Returning {:ok, state}
will cause start_link/3
to return
{:ok, pid}
and the process to enter its loop.
Returning {:ok, state, timeout}
is similar to {:ok, state}
except handle_info(:timeout, state)
will be called after timeout
milliseconds if no messages are received within the timeout.
Returning {:ok, state, :hibernate}
is similar to {:ok, state}
except the process is hibernated before entering the loop. See
c:handle_call/3
for more information on hibernation.
Returning {:ok, state, {:continue, continue}}
is similar to
{:ok, state}
except that immediately after entering the loop
the c:handle_continue/2
callback will be invoked with the value
continue
as first argument.
Returning :ignore
will cause start_link/3
to return :ignore
and
the process will exit normally without entering the loop or calling
c:terminate/2
. If used when part of a supervision tree the parent
supervisor will not fail to start nor immediately try to restart the
GenServer
. The remainder of the supervision tree will be started
and so the GenServer
should not be required by other processes.
It can be started later with Supervisor.restart_child/2
as the child
specification is saved in the parent supervisor. The main use cases for
this are:
- The
GenServer
is disabled by configuration but might be enabled later. - An error occurred and it will be handled by a different mechanism than the
Supervisor
. Likely this approach involves callingSupervisor.restart_child/2
after a delay to attempt a restart.
Returning {:stop, reason}
will cause start_link/3
to return
{:error, reason}
and the process to exit with reason reason
without
entering the loop or calling c:terminate/2
.
Callback implementation for GenServer.init/1
.
refresh_token(token) View Source
refresh_token(name, token) View Source
start_link(config) View Source
Start Auctoritas GenServer with specified config (from Auctoritas.Config
)