View Source PurpleAuthClient (Purple Auth Client v0.1.0)
PurpleAuthClient
Client library for using my password authentication service Purple Auth, available at https://purpleauth.com. Also can be self-hosted. It will handle all the API calls to do the authentication
PurpleAuthClient
requires configuration values in your application compile environment (config/config.exs
).
:host
: The endpoint where Purple Auth is hosted. Probably https://purpleauth.com
:app_id
: When you create an app at Purple Auth, it will supply you with an App ID
. Provide that here.
:api_key
: You will also be given an API Key to authorize you and prevent others from using your quota. Be sure not
to commit this to source control.
Link to this section Summary
Functions
Request a new ID token using a refresh token. Returns a new id token
Starts authenticating a user by sending information to their email
using the given flow
Submits the one time password provided by a user. Returns either the new authentication tokens or and error and a reason.
Verify an ID Token locally from your server. This will be much faster because we cache the public keys
so that after the first time, it can be executed without any slow REST API calls. Returns :ok
and the claims
from the token or :error
and information about the error.
Request the server to do token verification. Returns :ok
and claims from the token or :error
and
a reason.
Link to this section Functions
Request a new ID token using a refresh token. Returns a new id token
parameters
Parameters
- refresh_token: Refresh token from the client.
examples
Examples
> PurpleAuthClient.refresh("refresh_token")
{:ok, "newidtokenfromserver"}
> PurpleAuthClient.refresh("invalid_refresh_token")
{:error, :authentication_failure}
Starts authenticating a user by sending information to their email
using the given flow
parameters
Parameters
- email: the email of the user to be authenticated
- flow: either
:magic
for a magic link the redirects back to your site or:otp
to send the user a code they can enter within a certain time.
Returns :ok
or a tuple of :error
and information about the error
examples
Examples
> PurpleAuthClient.start_authentication("rickhenry@rickhenry.dev", :otp)
:ok
> PurpleAuthClient.start_authentication("rickhenry@rickhenry.dev", :magic)
:ok
> PurpleAuthClient.start_authentication("bad email", :otp)
{:error, :validation_error}
@spec submit_code(String.t(), String.t()) :: {:error, any()} | {:ok, %{:id_token => any(), optional(:refresh_token) => any()}}
Submits the one time password provided by a user. Returns either the new authentication tokens or and error and a reason.
parameters
Parameters
- email: The user's email
- code: code entered by the user based on what they received in their email
examples
Examples
> PurpleAuthClient.submit_code("rickhenry@rickhenry.dev", "123456")
{:ok, %{"id_token" => "newjwtidtoken"}}
> PurpleAuthClient.submit_code("rickhenry@rickhenry.dev", "123457")
{:error, :authentication_failure}
Verify an ID Token locally from your server. This will be much faster because we cache the public keys
so that after the first time, it can be executed without any slow REST API calls. Returns :ok
and the claims
from the token or :error
and information about the error.
parameters
Parameters
- id_token: the token to verify
examples
Examples
> PurpleAuthClient.verify("useridtoken")
{:ok, %{"iat" => 123456, "sub" => "rickhenry@rickhenry.dev"}}
> PurpleAuthClient.verify("fakeuseridtoken")
{:error, :signature_error}
Request the server to do token verification. Returns :ok
and claims from the token or :error
and
a reason.
parameters
Parameters
- id_token: JWT idToken from the client
examples
Examples
> PurpleAuthClient.verify_token_remote("some_id_token")
{:ok, %{"sub" => "rickhenry@rickhenry.dev"}}
> PurpleAuthClient.verify_token_remote("expired_token")
{:error, :authentication_failure}