PowAssent v0.4.8 PowAssent.Plug View Source

Plug helper methods.

If you wish to configure PowAssent through the Pow plug interface rather than environment config, please add PowAssent config with :pow_assent config:

plug Pow.Plug.Session,
  repo: MyApp.Repo,
  user: MyApp.User,
  pow_assent: [
    http_adapter: PowAssent.HTTPAdapter.Mint,
    json_library: Poison,
    user_identities_context: MyApp.UserIdentities
  ]

Link to this section Summary

Functions

authenticate(conn, map)

Authenticates a user with provider and provider user params.

authorize_url(conn, provider, redirect_uri)

Calls the authorize_url method for the provider strategy.

available_providers(conn)

Lists available providers for connection.

callback(conn, provider, params, redirect_uri)

Calls the callback method for the provider strategy.

callback_upsert(conn, provider, params, redirect_uri)

Calls the callback method for the provider strategy and will authenticate, upsert user identity, or create user.

change_user(conn, params \\ %{}, user_params \\ %{}, user_id_params \\ %{})

Creates a changeset.

create_user(conn, user_identity_params, user_params, user_id_params \\ nil)

Create a user with the provider and provider user params.

delete_identity(conn, provider)

Deletes the associated user identity for the current user and provider.

delete_session(conn, key)

Deletes key from session.

fetch_config(conn)

Fetch PowAssent configuration from the Pow configration.

init_session(conn)

Initializes session.

merge_provider_config(conn, provider, new_config)

Merges existing provider config with new config in the conn.

providers_for_current_user(conn)

Lists associated providers for the user.

put_create_session_callback(conn, callback)

Store a callback method to run after session is created.

put_session(conn, key, value)

Inserts value for key in session.

upsert_identity(conn, user_identity_params)

Will upsert identity for the current user.

Link to this section Functions

authenticate(conn, map)

authenticate(Plug.Conn.t(), map()) ::
  {:ok, Plug.Conn.t()} | {:error, Plug.Conn.t()}

Authenticates a user with provider and provider user params.

If successful, a new session will be created. After session has been created the callbacks stored with put_create_session_callback/2 will run.

authorize_url(conn, provider, redirect_uri)

authorize_url(Plug.Conn.t(), binary(), binary()) ::
  {:ok, binary(), Plug.Conn.t()} | {:error, any(), Plug.Conn.t()}

Calls the authorize_url method for the provider strategy.

A generated authorization URL will be returned. If :session_params is returned from the provider, it'll be added to the connection as private key :pow_assent_session_params.

If :nonce is set to true in the PowAssent provider configuration, a randomly generated nonce will be added to the provider configuration.

available_providers(conn)

available_providers(Plug.Conn.t() | PowAssent.Config.t()) :: [atom()]

Lists available providers for connection.

callback(conn, provider, params, redirect_uri)

callback(Plug.Conn.t(), binary(), map(), binary()) ::
  {:ok, map(), map(), Plug.Conn.t()} | {:error, any(), Plug.Conn.t()}

Calls the callback method for the provider strategy.

Returns the user identity params and user params fetched from the provider.

:session_params will be added to the provider config if :pow_assent_session_params is present as a private key in the connection.

callback_upsert(conn, provider, params, redirect_uri)

callback_upsert(Plug.Conn.t(), binary(), map(), binary()) ::
  {:ok, Plug.Conn.t()} | {:error, Plug.Conn.t()}

Calls the callback method for the provider strategy and will authenticate, upsert user identity, or create user.

See callback/4, authenticate/2, upsert_identity/2, and create_user/4 for more.

To track the state of the flow the following keys may be populated in conn.private:

:pow_assent_callback_state - The state of the flow, that is either {:ok, step} or {:error, step}.
:pow_assent_callback_params - The params returned by the strategy callback phase.
:pow_assent_callback_error - The resulting error of any step.

The value of :pow_assent_callback_state may be one of the following:

{:error, :strategy} - An error ocurred during strategy callback phase. :pow_assent_callback_error will be populated with the error.
{:ok, :upsert_user_identity} - User identity was created or updated.
{:error, :upsert_user_identity} - User identity could not be created or updated. :pow_assent_callback_error will be populated with the changeset.
{:ok, :create_user} - User was created.
{:error, :create_user} - User could not be created. :pow_assent_callback_error will be populated with the changeset.

If :pow_assent_registration in conn.private is set to false then create_user/4 will not be called and the :pow_assent_callback_state set to {:error, :create_user} with nil value for :pow_assent_callback_error.

change_user(conn, params \\ %{}, user_params \\ %{}, user_id_params \\ %{})

Creates a changeset.

create_user(conn, user_identity_params, user_params, user_id_params \\ nil)

create_user(Plug.Conn.t(), map(), map(), map() | nil) ::
  {:ok, map(), Plug.Conn.t()}
  | {:error, {:bound_to_different_user | :invalid_user_id_field, map()} | map(),
     Plug.Conn.t()}

Create a user with the provider and provider user params.

If successful, a new session will be created. After session has been created the callbacks stored with put_create_session_callback/2 will run.

delete_identity(conn, provider)

delete_identity(Plug.Conn.t(), binary()) ::
  {:ok, map(), Plug.Conn.t()} | {:error, {:no_password, map()}, Plug.Conn.t()}

Deletes the associated user identity for the current user and provider.

delete_session(conn, key)

delete_session(Plug.Conn.t(), atom()) :: Plug.Conn.t()

Deletes key from session.

fetch_config(conn)

fetch_config(Plug.Conn.t()) :: PowAssent.Config.t()

Fetch PowAssent configuration from the Pow configration.

Calls Pow.Plug.fetch_config/1 and fetches the pow_assent key value.

init_session(conn)

init_session(Plug.Conn.t()) :: Plug.Conn.t()

Initializes session.

Session data will be fetched and deleted from the PowAssent session store if a pow_assent_session key was found in the Plug session. The session data is set for the :pow_assent_session key in in conn.private.

A :before_send callback will be set to store session data. If :pow_assent_session key in conn.private has been populated, a random UUID is generated and used as the key for the stored session data. The UUID is then stored as pow_assent_session key in the Plug session.

The session store can be changed by setting :session_store config option. By default it's {PowAssent.Store.SessionCache, backend: Pow.Store.Backend.EtsCache}. The backend store can be changed by setting :cache_store_backend for the Pow configuration.

merge_provider_config(conn, provider, new_config)

merge_provider_config(Plug.Conn.t(), binary(), Keyword.t()) :: Plug.Conn.t()

Merges existing provider config with new config in the conn.

The existing config is fetched with fetch_config/1, and the new config deep merged unto it with PowAssent.Config.merge_provider_config/3. The updated config will be set as :pow_assent config value for the Pow config for the conn with Pow.Plug.put_config/2.

providers_for_current_user(conn)

providers_for_current_user(Plug.Conn.t()) :: [atom()]

Lists associated providers for the user.

put_create_session_callback(conn, callback)

put_create_session_callback(Plug.Conn.t(), function()) :: Plug.Conn.t()

Store a callback method to run after session is created.

put_session(conn, key, value)

put_session(Plug.Conn.t(), atom(), any()) :: Plug.Conn.t()

Inserts value for key in session.

upsert_identity(conn, user_identity_params)

upsert_identity(Plug.Conn.t(), map()) ::
  {:ok, map(), Plug.Conn.t()}
  | {:error, {:bound_to_different_user, map()} | map(), Plug.Conn.t()}

Will upsert identity for the current user.

If successful, a new session will be created. After session has been created the callbacks stored with put_create_session_callback/2 will run.