# `AshAuthentication`
[🔗](https://github.com/team-alembic/ash_authentication/blob/main/lib/ash_authentication.ex#L5)

AshAuthentication provides a turn-key authentication solution for folks using
[Ash](https://www.ash-hq.org/).

## Usage

This package assumes that you have [Ash](https://ash-hq.org/) installed and
configured.  See the Ash documentation for details.

Once installed you can easily add support for authentication by configuring
the `AshAuthentication` extension on your resource:

```elixir
defmodule MyApp.Accounts.User do
  use Ash.Resource,
    extensions: [AshAuthentication],
    domain: MyApp.Accounts

  attributes do
    uuid_primary_key :id
    attribute :email, :ci_string, allow_nil?: false
    attribute :hashed_password, :string, allow_nil?: false, sensitive?: true
  end

  authentication do
    strategies do
      password :password do
        identity_field :email
        hashed_password_field :hashed_password
      end
    end
  end

  identities do
    identity :unique_email, [:email]
  end
end
```

If you plan on providing authentication via the web, then you will need to
define a plug using `AshAuthentication.Plug` which builds a `Plug.Router` that
routes incoming authentication requests to the correct provider and provides
callbacks for you to manipulate the conn after success or failure.

If you're using AshAuthentication with Phoenix, then check out
[`ash_authentication_phoenix`](https://github.com/team-alembic/ash_authentication_phoenix)
which provides route helpers, a controller abstraction and LiveView components
for easy set up.

## Authentication Strategies

Currently supported strategies:

1. `AshAuthentication.Strategy.Password`
   - authenticate users against your local database using a unique identity
   (such as username or email address) and a password.
2. `AshAuthentication.Strategy.OAuth2`
   - authenticate using local or remote [OAuth 2.0](https://oauth.net/2/) compatible services.
   - also includes:
     - `AshAuthentication.Strategy.Apple`
     - `AshAuthentication.Strategy.Auth0`
     - `AshAuthentication.Strategy.Github`
     - `AshAuthentication.Strategy.Google`
     - `AshAuthentication.Strategy.Microsoft`
     - `AshAuthentication.Strategy.Oidc`
     - `AshAuthentication.Strategy.Okta`
     - `AshAuthentication.Strategy.Slack`
3. `AshAuthentication.Strategy.MagicLink`
   - authenticate by sending a single-use link to the user.

### HTTP client settings

Most of the authentication strategies based on `OAuth2` wrap the [`assent`](https://hex.pm/packages/assent) package.

If you needs to customize the behavior of the http client used by `assent`, define a custom `http_adapter` in the
application settings:

`config :ash_authentication, :http_adapter, {Assent.HTTPAdapter.Finch, supervisor: MyApp.CustomFinch}`

See [`assent's documentation`](https://hexdocs.pm/assent/README.html#http-client) for more details on the supported
http clients and their configuration.

### Magic Link configuration

When using the `MagicLink` strategy, you can configure whether invalid
magic link tokens should return an error or an empty result. The current
default for backward compatibility is to return an empty result when a
token is invalid. However, this makes it difficult to distinguish between
a successful sign-in and a failed sign-in due to an invalid token.

To return an error when an invalid token is provided (recommended), set:

`config :ash_authentication, return_error_on_invalid_magic_link_token?: true`

This is especially important if you're using the `AuditLog` add-on, as it
ensures failed sign-in attempts are logged correctly. In the next major
version, returning an error will be the default behavior.

## Add-ons

Add-ons are like strategies, except that they don't actually provide
authentication - they just provide features adjacent to authentication.
Current add-ons:

1. `AshAuthentication.AddOn.Confirmation`
   - allows you to force the user to confirm changes using a confirmation
     token (eg. sending a confirmation email when a new user registers).
2. `AshAuthentication.AddOn.LogOutEverywhere`
   - allows you to revoke all of a user's tokens on sign out.
3. `AshAuthentication.AddOn.AuditLog`
   - provides audit logging for other add-ons and strategies.

## Supervisor

Some add-ons or strategies may require processes to be started which manage
their state over the lifetime of the application (eg periodically deleting
expired token revocations).  Because of this you should add
`{AshAuthentication.Supervisor, otp_app: :my_app}` to your application's
supervision tree.  See [the Elixir
docs](https://hexdocs.pm/elixir/Application.html#module-the-application-callback-module)
for more information.

# `resource_config`

```elixir
@type resource_config() :: %{
  domain: module(),
  providers: [module()],
  resource: module(),
  subject_name: atom()
}
```

# `subject`

```elixir
@type subject() :: String.t()
```

# `add_token_claims`

```elixir
@spec add_token_claims(Ash.Changeset.t() | Ash.Query.t() | Ash.ActionInput.t(), map()) ::
  Ash.Changeset.t() | Ash.Query.t() | Ash.ActionInput.t()
```

Add extra claims to be included in the generated token.

Works with changesets, queries, and action inputs.

## Examples

For create actions (like registration):

    create :register_with_password do
      # ...
      change AshAuthentication.GenerateTokenChange
      change fn changeset, _ctx ->
        AshAuthentication.add_token_claims(changeset, %{"session_type" => "web"})
      end
    end

For read actions (like sign-in):

    MyApp.User
    |> Ash.Query.for_read(:sign_in_with_password, %{email: email, password: password})
    |> AshAuthentication.add_token_claims(%{"session_type" => "api"})
    |> Ash.read_one!()

These claims will be merged with any claims configured via the `extra_claims`
DSL option, with action-level claims taking precedence.

# `authenticated_resources`

```elixir
@spec authenticated_resources(atom() | [atom()]) :: [Ash.Resource.t()]
```

Find all resources which support authentication for a given OTP application.

Returns a list of resource modules.

# `authentication`
*macro* 

# `do_subject_to_user`

# `subject_to_user`

```elixir
@spec subject_to_user(subject() | URI.t(), Ash.Resource.t(), keyword()) ::
  {:ok, Ash.Resource.record()} | {:error, any()}
```

Given a subject string, attempt to retrieve a user record.

    iex> %{id: user_id} = build_user()
    ...> {:ok, %{id: ^user_id}} = subject_to_user("user?id=#{user_id}", Example.User)

Any options passed will be passed to the underlying `Domain.read/2` callback.

# `user_to_subject`

```elixir
@spec user_to_subject(Ash.Resource.record()) :: subject()
```

Return a subject string for user.

This is done by concatenating the resource's subject name with the resource's
primary key field(s) to generate a uri-like string.

Example:

    iex> build_user(id: "ce7969f9-afa5-474c-bc52-ac23a103cef6") |> user_to_subject()
    "user?id=ce7969f9-afa5-474c-bc52-ac23a103cef6"

---

*Consult [api-reference.md](api-reference.md) for complete listing*