RestAuth v1.1.2 RestAuth.Handler behaviour View Source

The primary behaviour that drives the use of RestAuth in a project.

Link to this section Summary

Callbacks

A configuration collback to provide anonymous roles

Verifies the given authority can access an item in the system

A configuration callback to provide default required roles

Invalidates a token

Invalidates a user

Invalidates all user acl based off the user_id in the RestAuth.Authority struct

Similar to load_user_data/2, but uses an already loaded user data and is only responsible for converting it into the RestAuth.Authority struct

Used to load user from a data store

Similar to load_user_data/1 but constructs the authority struct from the token

A configuration callback to determine, if mechanisms of RestAuth should be writing into cookies

Link to this section Callbacks

Link to this callback anonymous_roles() View Source (optional)
anonymous_roles() :: [String.t]

A configuration collback to provide anonymous roles.

If not implemented, [] is used.

Link to this callback can_access_item?(arg0, category, target_id) View Source (optional)
can_access_item?(RestAuth.Authority.t, category :: String.t, target_id :: any) :: boolean

Verifies the given authority can access an item in the system.

The callback is not used by the library and is an advice of use of the library.

Typically does a lookup for permissions in the caching layer first, then in the database if it is not found there.

If using the caching layer, remember to write-through to the service after loading from the database to decide if access is granted or not.

Remember to use invalidate_user_acl/2 to update the acl cache when granting or denying access to things.

Link to this callback default_required_roles() View Source (optional)
default_required_roles() :: [String.t]

A configuration callback to provide default required roles.

If not implemented, [] is used.

Link to this callback invalidate_token(authority) View Source
invalidate_token(authority :: RestAuth.Authority.t) ::
  :ok |
  {:error, reason :: String.t}

Invalidates a token.

Typically this invalidates the token in the cacheservice and deletes any associated data from the database.

Link to this callback invalidate_user(authority) View Source (optional)
invalidate_user(authority :: RestAuth.Authority.t) ::
  :ok |
  {:error, reason :: String.t}

Invalidates a user.

The callback is not used by the library and is an advice of use of the library.

This effectively logs out all active sessions across the application

Typically this invalidates all the tokens in the cacheservice and deletes any associated data from the database.

Link to this callback invalidate_user_acl(authority) View Source (optional)
invalidate_user_acl(authority :: RestAuth.Authority.t) ::
  :ok |
  {:error, reason :: String.t}

Invalidates all user acl based off the user_id in the RestAuth.Authority struct.

The callback is not used by the library and is an advice of use of the library.

Typically used to clear the acl for a user after being granted access to something with intention of refreshing the acl data on subsequent requests.

Can be regarded as a companion function

Link to this callback load_user_data(user) View Source
load_user_data(user :: any) :: {:ok, RestAuth.Authority.t}

Similar to load_user_data/2, but uses an already loaded user data and is only responsible for converting it into the RestAuth.Authority struct.

This function is often used for convenience if a user changes his username, name or other data that requires the system to issue a new authority for an already known user. It is also used in RestAuth.Test.authenticate_conn/2.

Link to this callback load_user_data(username, password) View Source
load_user_data(username :: String.t, password :: String.t) ::
  {:ok, RestAuth.Authority.t} |
  {:error, reason :: String.t}

Used to load user from a data store.

Primary use case is in RestAuth.Controller.login/2. Must return a RestAuth.Authority struct with all the relevant user information.

Beware that while metadata can be anything it must be serializeable by Poison JSON encoder. This can be solved by using the standard types like List, Map etc or by implementing the Poison protocol.

Do note that all the data returned here will be embedded in the token, so try to keep it as small as possible.

The :error reason should be a string explaining why the user was not returned. Some examples

  • “Wrong username and/or password.”
  • “Account is locked”
  • “Account has not been activated yet”.
  • “Error connecting to database.”
Link to this callback load_user_data_from_token(token) View Source
load_user_data_from_token(token :: String.t) ::
  {:ok, RestAuth.Authority.t} |
  {:client_outdated, RestAuth.Authority.t} |
  {:error, reason :: String.t}

Similar to load_user_data/1 but constructs the authority struct from the token.

This function is called on every request and should ideally be backed up by RestAuth.CacheService or any other caching strategy.

If clientside data is outdated, for example by the handler implementing a version field this function can return the authority in a {:client_outdated, RestAuth.Authority.t} tuple. This will make the plug add “x-auth-refresh-token”: “true” header to the reply.

Link to this callback write_cookie?() View Source (optional)
write_cookie?() :: boolean

A configuration callback to determine, if mechanisms of RestAuth should be writing into cookies.

If not implemented, false is used.