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
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: "user@example.com", 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("user@example.com")
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: "user@example.com", 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: "user@example.com"})
Settings
To view the server's auth settings, call GoTrue.settings()
License
MIT