supabase-community / gotrue-ex

An Elixir client for the GoTrue authentication service

GoTrue

An Elixir client for GoTrue.

GoTrue is an open source authentication service that supports many methods of authentication:

• Classic email+password logins
• Passwordless logins with magic links
• OAUTH2 - Google, GitHub, BitBucket, GitLab, etc..
• SAML/SSO

Documentation

Why?

GoTrue is a way of doing authentication by delagating the work to a separate service. It has a very slim HTTP API, so less code to maintain. It's also a polyglot auth solution.

It was developed by Netlify, though this version is being developed against the supabase fork

For many apps, phx_gen_auth is a great solution, but it requires a bit more work to setup and adjust. It does mean inheriting a bunch of code. For a small team, or for quick experimentation, offloading a task like auth removes a big friction and reduces time to market.

It also makes it possibile to create an Elixir supabase client down the road.

Installation

Add gotrue to your list of dependencies in mix.exs:

def deps do
  [
    {:gotrue, "~> 0.1.0"}
  ]
end

Optional

In your config/dev.exs & config/prod.exs, configure settings:

config :gotrue,
  # URL to your GoTrue instance
  base_url: "http://0.0.0.0:9999",

  # The project's API key
  api_key: "your-super-secret-operator-token"

Usage

Creating a user account

Several options exist to create an account:

Password based

Pass credentials to GoTrue.sign_up/1, a new account will be created and a JWT token is returned.

GoTrue.client("https://ttlzokxvatvexhtzrpsm.supabase.co/auth/v1", "my-supabase-project-api-key")
|> GoTrue.sign_up(%{email: "[email protected]", password: "123456"})

OAUTH2

Oauth is performed on the client by redirecting the user. To get the redirection URL, call GoTrue.url_for_provider/1:

GoTrue.url_for_provider(:google)
GoTrue.url_for_provider(:github)
GoTrue.url_for_provider(:gitlab)
GoTrue.url_for_provider(:bitbucket)
GoTrue.url_for_provider(:facebook)

Magic Link

Users can login without password, by requesting a magic link:

GoTrue.client("https://ttlzokxvatvexhtzrpsm.supabase.co/auth/v1", "my-supabase-project-api-key")
|> GoTrue.send_magic_link("[email protected]")

That sends them an email with a link to login. The link will contain the access_token & refresh_token.

Sign in

If you're using password logins, sign in a user by passing the email & password to GoTrue.sign_in/1, it returns a JWT

GoTrue.client("https://ttlzokxvatvexhtzrpsm.supabase.co/auth/v1", "my-supabase-project-api-key")
|> GoTrue.sign_in(%{email: "[email protected]", password: "12345"})

Refreshing JWT

Each JWT expires based on your GoTrue server's settings. To refresh it, pass the refresh_token to GoTrue.refresh_access_token/1

# first get an access token, there are many ways:

# via sign up
%{access_token: jwt, refresh_token: refresh_token} = GoTrue.sign_up(...)

# or via login
%{access_token: jwt, refresh_token: refresh_token} = GoTrue.sign_in(...)

# or via a redirection from an oauth provider
def controller_action(conn, %{access_token: jwt, refresh_token: refresh_token}) do
  # put in session
end

# refresh it before it expires
%{access_token: new_jwt} = GoTrue.refresh_access_token(refresh_token)

Sign out

To revoke a JWT, call GoTrue.sign_out/1

GoTrue.sign_out(jwt)

Getting user info

The user's info can be accessed by calling GoTrue.get_user/1 with their current JWT:

GoTrue.get_user(jwt)

Updating user info

Using a JWT, the user's data can be updated by calling GoTrue.update_user/2

GoTrue.update_user(jwt, %{data: %{favorite_language: "elixir"}})

Invitations

Users can be invited by passing their email address to GoTrue.invite/1, this sends them an email with a completion link.

GoTrue.invite(%{email: "[email protected]"})

Settings

To view the server's auth settings, call GoTrue.settings()

License

MIT

gotrue-ex's Issues

Changing how the client is initialized

It would be nice (or even necessary) if another library or application could pass the connection info (url + api_key) to the client initialization.

The Elixir docs even discourage using Application config in libraries

• https://hexdocs.pm/elixir/master/library-guidelines.html#avoid-application-configuration
• https://hexdocs.pm/elixir/master/library-guidelines.html#avoid-compile-time-application-configuration

Maybe something like

def client(base_url, api_key, options) do
  access_token = Keyword.get(options, :access_token, api_key)
  middlewares = [
      {Tesla.Middleware.BaseUrl, @base_url},
      Tesla.Middleware.JSON,
      {Tesla.Middleware.Headers, [{:apikey, @api_key}, {:authorization, access_token}]}
    ]
  Tesla.client(middlewares)
  
  # changing functions to get client as first argument
  def update_user(client, info) do
    ...

Another option would be always creating the client with only the
base_url and api_key and then overwrite the headers in the module functions

def update_user(client, access_token, info) do
  # ... overwrite headers in client ...
  # go on

And then in another library or application it could be used like

GoTrue.client(my_base_url, my_api_key)
|> GoTrue.update_user(access_token, %{"username" => "new-user-name"})

decrypt the jwt

Hi,

I was looking for a way to re-use and read the jwt set by supabase directly from our elixir server.

If I got it right, sharing the secret key between supabase and the elixir server and send the jwt directly to both (from the browser) should work.

but I didn't find any function allowing to decrypt the jwt in this library. am I missing something or isn't it covered?