Service users: accounts that exist only to own API keys.
A service user is an ordinary phoenix_kit_users row with api_only: true, a
non-deliverable address api-<uuid>@service.invalid (the .invalid TLD never
resolves) and a random password hash nobody knows. It holds the roles its
creator chose, so a key owned by it is limited by those roles' permissions
exactly as a key owned by a person is. Every web authentication entry point
refuses api_only users (see the api_only guards in PhoenixKit.Users.Auth
and PhoenixKitWeb.Users.Auth), so the account can never obtain a session.
Which roles a creator may give
Only roles whose permissions are a subset of the creator's own, and never
the Owner role. An api holder with narrow rights therefore cannot build a
more powerful identity than themselves.
The user is created directly, not through Auth.register_user/2: that path
would promote it to Owner on an install without one, add the default User
role, send mail and rate-limit the creator.
Summary
Functions
The roles the person behind creator_scope may give to a service user: not the
Owner role, and only roles whose permissions the creator holds in full. Empty
for someone who does not hold api.
Creates a service user holding roles (a list of role names) on behalf of the
person behind creator_scope.
The service users the person behind scope may see and hand keys to: all of
them for an Owner, the ones they created for any other holder of api, none
for someone without api. Oldest first.
Functions
@spec allowed_roles(PhoenixKit.Users.Auth.Scope.t()) :: [PhoenixKit.Users.Role.t()]
The roles the person behind creator_scope may give to a service user: not the
Owner role, and only roles whose permissions the creator holds in full. Empty
for someone who does not hold api.
@spec create(PhoenixKit.Users.Auth.Scope.t(), %{ optional(:name) => String.t(), roles: [String.t()] }) :: {:ok, PhoenixKit.Users.Auth.User.t()} | {:error, :forbidden | :role_not_allowed | Ecto.Changeset.t()}
Creates a service user holding roles (a list of role names) on behalf of the
person behind creator_scope.
attrs takes roles and an optional name (shown in the user list).
Errors: :forbidden when the creator does not hold api;
:role_not_allowed when any role is unknown, is the Owner role or carries a
permission the creator lacks (nothing is created); a changeset when the name is
invalid.
@spec list(PhoenixKit.Users.Auth.Scope.t()) :: [PhoenixKit.Users.Auth.User.t()]
The service users the person behind scope may see and hand keys to: all of
them for an Owner, the ones they created for any other holder of api, none
for someone without api. Oldest first.