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

@spec refresh(String.t()) :: {:ok, String.t()} | {:error, any()}

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}
Link to this function

start_authentication(email, flow)

View Source
@spec start_authentication(String.t(), :magic | :otp) :: :ok | {:error, any()}

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}
Link to this function

submit_code(email, code)

View Source
@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}
@spec verify(String.t()) :: {:ok, map()} | {:error, any()}

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}
Link to this function

verify_token_remote(id_token)

View Source
@spec verify_token_remote(String.t()) :: {:error, any()} | {:ok, map()}

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}