@spec 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.

@spec 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.

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

Lists available providers for connection.

@spec 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.

@spec 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.

Creates a changeset.

@spec 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.

@spec 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.

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

Deletes key from session.

@spec 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.

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

Initializes session.

Session data will be fetched and deleted from the PowAssent session store if an auth session cookie was found. The session data is set for the :pow_assent_session_info 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 the value for the auth session cookie.

Configuration options

The configuration is fetched with fetch_config/1.

• :session_store - the session store. This value defaults to {PowAssent.Store.SessionCache, backend: Pow.Store.Backend.EtsCache}. The Pow.Store.Backend.EtsCache backend store can be changed with the :cache_store_backend option.

• :auth_session_cookie_key - The cookie key name to use. Defaults to "auth_session". If :otp_app is used it'll automatically prepend the key with the :otp_app value.

• :auth_session_cookie_opts - keyword list of cookie options, see Plug.Conn.put_resp_cookie/4 for options. The default options are [path: "/"].

@spec merge_provider_config(Plug.Conn.t(), binary() | atom(), 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.

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

Lists associated providers for the user.

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

Store a callback method to run after session is created.

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

Inserts value for key in session.

@spec 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.