auth

README

auth-go

A Golang client library for the Supabase Auth API.

For more information about the Supabase fork of GoTrue, check out the project here.

Project status

This library is a pre-release work in progress. It has not been thoroughly tested, and the API may be subject to breaking changes, and so it should not be used in production.

The endpoints for SSO SAML are not tested and POST /sso/saml/acs does not provide request and response types. If you need additional support for SSO SAML, please create an issue or a pull request.

Quick start

Install

go get github.com/Rubitec/supabase-auth-go

Usage

package main

import "github.com/Rubitec/supabase-auth-go"

const (
    projectReference = "<your_supabase_project_reference>"
    apiKey = "<your_supabase_anon_key>"
)

func main() {
    // Initialise client
    client := auth.New(
        projectReference,
        apiKey,
    )

    // Log in a user (get access and refresh tokens)
    resp, err := client.Token(auth.TokenRequest{
        GrantType: "password",
        Email: "<user_email>",
        Password: "<user_password>",
    })
    if err != nil {
        log.Fatal(err.Error())
    }
    log.Printf("%+v", resp)
}

Options

The client can be customized with the options below.

In all cases, these functions return a copy of the client. To use the configured value, you must use the returned client. For example:

client := auth.New(
    projectRefernce,
    apiKey,
)

token, err := client.Token(auth.TokenRequest{
        GrantType: "password",
        Email: email,
        Password: password,
})
if err != nil {
    // Handle error...
}

authedClient := client.WithToken(
    token.AccessToken,
)
user, err := authedClient.GetUser()
if err != nil {
    // Handle error...
}

WithToken

func (*Client) WithToken(token string) *Client

Returns a client that will use the provided token in the Authorization header on all requests.

WithCustomAuthURL

func (*Client) WithCustomAuthURL(url string) *Client

Returns a client that will use the provided URL instead of https://<project_ref>.supabase.com/auth/v1/. This allows you to use the client with your own deployment of the Auth server without relying on a Supabase-hosted project.

WithClient

func (*Client) WithClient(client http.Client) *Client

By default, the library uses a default http.Client. If you want to configure your own, pass one in using WithClient and it will be used for all requests made with the returned *auth.Client.

Testing

You don't need to know this stuff to use the library

The library is tested against a real Auth server running in a docker image. This also requires a postgres server to back it. These are configured using docker compose.

To run these tests, simply make test.

To interact with docker compose, you can also use make up and make down.

Differences from auth-js

Prior users of auth-js may be familiar with its subscription mechanism and session management - in line with its ability to be used as a client-side authentication library, in addition to use on the server.

As Go is typically used on the backend, this library acts purely as a convenient wrapper for interacting with a Auth server. It provides no session management or subscription mechanism.

Migrating from gotrue-go

This repository was created as a duplicate of gotrue-go.

As part of renaming the package, breaking changes to the API were also introduced, to keep consistency with the new naming. The changes can generally be boiled down to:

1. Rename instances of gotrue-go to auth-go
2. Rename instances of GoTrue to Auth

There are a small number of exceptions where required to maintain compatibility with the implementation of the Auth server. No other changes were introduced, so you should find the exact same functionality under a very similar name if updating your codebase from gotrue-go to auth-go.

Documentation

Index

• Variables
• type Client
  • func New(url string, projectReference string, apiKey string) Client

Variables

var (
	ErrInvalidProjectReference = errors.New("cannot create auth client: invalid project reference")
)

Types

type Client

type Client interface {

	// By default, the client will use the supabase project reference and assume
	// you are connecting to the Auth server as part of a supabase project.
	// To connect to a Auth server hosted elsewhere, you can specify a custom
	// URL using this method.
	//
	// It returns a copy of the client, so only requests made with the returned
	// copy will use the new URL.
	//
	// This method does not validate the URL you pass in.
	WithCustomAuthURL(url string) Client
	// WithToken sets the access token to pass when making admin requests that
	// require token authentication.
	//
	// It returns a copy of the client, so only requests made with the returned
	// copy will use the new token.
	//
	// The token can be your service role if running on a server.
	// REMEMBER TO KEEP YOUR SERVICE ROLE TOKEN SECRET!!!
	//
	// A user token can also be used to make requests on behalf of a user. This is
	// usually preferable to using a service role token.
	WithToken(token string) Client
	// WithClient allows you to pass in your own HTTP client.
	//
	// It returns a copy of the client, so only requests made with the returned
	// copy will use the new HTTP client.
	WithClient(client http.Client) Client

	// GET /admin/audit
	//
	// Get audit logs.
	//
	// May optionally specify a query to use for filtering the audit logs. The
	// column and value must be specified if using a query.
	//
	// The result may also be paginated. By default, 50 results will be returned
	// per request. This can be configured with PerPage in the request. The response
	// will include the total number of results, as well as the total number of pages
	// and, if not already on the last page, the next page number.
	AdminAudit(req types.AdminAuditRequest) (*types.AdminAuditResponse, error)

	// POST /admin/generate_link
	//
	// Returns the corresponding email action link based on the type specified.
	// Among other things, the response also contains the query params of the action
	// link as separate JSON fields for convenience (along with the email OTP from
	// which the corresponding token is generated).
	//
	// Requires admin token.
	AdminGenerateLink(req types.AdminGenerateLinkRequest) (*types.AdminGenerateLinkResponse, error)

	// GET /admin/sso/providers
	//
	// Get a list of all SAML SSO Identity Providers in the system.
	AdminListSSOProviders() (*types.AdminListSSOProvidersResponse, error)
	// POST /admin/sso/providers
	//
	// Create a new SAML SSO Identity Provider.
	AdminCreateSSOProvider(req types.AdminCreateSSOProviderRequest) (*types.AdminCreateSSOProviderResponse, error)
	// GET /admin/sso/providers/{idp_id}
	//
	// Get a SAML SSO Identity Provider by ID.
	AdminGetSSOProvider(req types.AdminGetSSOProviderRequest) (*types.AdminGetSSOProviderResponse, error)
	// PUT /admin/sso/providers/{idp_id}
	//
	// Update a SAML SSO Identity Provider by ID.
	AdminUpdateSSOProvider(req types.AdminUpdateSSOProviderRequest) (*types.AdminUpdateSSOProviderResponse, error)
	// DELETE /admin/sso/providers/{idp_id}
	//
	// Delete a SAML SSO Identity Provider by ID.
	AdminDeleteSSOProvider(req types.AdminDeleteSSOProviderRequest) (*types.AdminDeleteSSOProviderResponse, error)

	// POST /admin/users
	//
	// Creates the user based on the user_id specified.
	//
	// Requires admin token.
	AdminCreateUser(req types.AdminCreateUserRequest) (*types.AdminCreateUserResponse, error)
	// GET /admin/users
	//
	// Get a list of users.
	//
	// Requires admin token.
	AdminListUsers() (*types.AdminListUsersResponse, error)
	// GET /admin/users/{user_id}
	//
	// Get a user by their user_id.
	AdminGetUser(req types.AdminGetUserRequest) (*types.AdminGetUserResponse, error)
	// PUT /admin/users/{user_id}
	//
	// Update a user by their user_id.
	AdminUpdateUser(req types.AdminUpdateUserRequest) (*types.AdminUpdateUserResponse, error)
	// DELETE /admin/users/{user_id}
	//
	// Delete a user by their user_id.
	AdminDeleteUser(req types.AdminDeleteUserRequest) error

	// GET /admin/users/{user_id}/factors
	//
	// Get a list of factors for a user.
	AdminListUserFactors(req types.AdminListUserFactorsRequest) (*types.AdminListUserFactorsResponse, error)
	// PUT /admin/users/{user_id}/factors/{factor_id}
	//
	// Update a factor for a user.
	AdminUpdateUserFactor(req types.AdminUpdateUserFactorRequest) (*types.AdminUpdateUserFactorResponse, error)
	// DELETE /admin/users/{user_id}/factors/{factor_id}
	//
	// Delete a factor for a user.
	AdminDeleteUserFactor(req types.AdminDeleteUserFactorRequest) error

	// GET /authorize
	//
	// Get access_token from external oauth provider.
	//
	// Scopes are optional additional scopes depending on the provider (email and
	// name are requested by default).
	//
	// If successful, the server returns a redirect response. This method will not
	// follow the redirect, but instead returns the URL the client was told to
	// redirect to.
	Authorize(req types.AuthorizeRequest) (*types.AuthorizeResponse, error)

	// POST /factors
	//
	// Enroll a new factor.
	EnrollFactor(req types.EnrollFactorRequest) (*types.EnrollFactorResponse, error)
	// POST /factors/{factor_id}/challenge
	//
	// Challenge a factor.
	ChallengeFactor(req types.ChallengeFactorRequest) (*types.ChallengeFactorResponse, error)
	// POST /factors/{factor_id}/verify
	//
	// Verify the challenge for an enrolled factor.
	VerifyFactor(req types.VerifyFactorRequest) (*types.VerifyFactorResponse, error)
	// DELETE /factors/{factor_id}
	//
	// Unenroll an enrolled factor.
	UnenrollFactor(req types.UnenrollFactorRequest) (*types.UnenrollFactorResponse, error)

	// GET /health
	//
	// Check the health of the Auth server.
	HealthCheck() (*types.HealthCheckResponse, error)

	// POST /invite
	//
	// Invites a new user with an email.
	//
	// Requires service_role or admin token.
	Invite(req types.InviteRequest) (*types.InviteResponse, error)

	// POST /logout
	//
	// Logout a user (Requires authentication).
	//
	// This will revoke all refresh tokens for the user. Remember that the JWT
	// tokens will still be valid for stateless auth until they expires.
	Logout() error

	// POST /magiclink
	//
	// DEPRECATED: Use /otp with Email and CreateUser=true instead of /magiclink.
	//
	// Magic Link. Will deliver a link (e.g.
	// /verify?type=magiclink&token=abcdefghijklmno) to the user based on email
	// address which they can use to redeem an access_token.
	//
	// By default Magic Links can only be sent once every 60 seconds.
	Magiclink(req types.MagiclinkRequest) error
	// POST /otp
	// One-Time-Password. Will deliver a magiclink or SMS OTP to the user depending
	// on whether the request contains an email or phone key.
	//
	// If CreateUser is true, the user will be automatically signed up if the user
	// doesn't exist.
	OTP(req types.OTPRequest) error

	// GET /reauthenticate
	//
	// Sends a nonce to the user's email (preferred) or phone. This endpoint
	// requires the user to be logged in / authenticated first. The user needs to
	// have either an email or phone number for the nonce to be sent successfully.
	Reauthenticate() error

	// POST /recover
	//
	// Password recovery. Will deliver a password recovery mail to the user based
	// on email address.
	//
	// By default recovery links can only be sent once every 60 seconds.
	Recover(req types.RecoverRequest) error

	// GET /settings
	//
	// Returns the publicly available settings for this auth instance.
	GetSettings() (*types.SettingsResponse, error)

	// POST /signup
	//
	// Register a new user with an email and password.
	Signup(req types.SignupRequest) (*types.SignupResponse, error)

	// Sign in with email and password
	//
	// This is a convenience method that calls Token with the password grant type
	SignInWithEmailPassword(email, password string) (*types.TokenResponse, error)
	// Sign in with phone and password
	//
	// This is a convenience method that calls Token with the password grant type
	SignInWithPhonePassword(phone, password string) (*types.TokenResponse, error)
	// Sign in with refresh token
	//
	// This is a convenience method that calls Token with the refresh_token grant type
	RefreshToken(refreshToken string) (*types.TokenResponse, error)
	// POST /token
	//
	// This is an OAuth2 endpoint that currently implements the password and
	// refresh_token grant types
	Token(req types.TokenRequest) (*types.TokenResponse, error)

	// GET /user
	//
	// Get the JSON object for the logged in user (requires authentication)
	GetUser() (*types.UserResponse, error)
	// PUT /user
	//
	// Update a user (Requires authentication). Apart from changing email/password,
	// this method can be used to set custom user data. Changing the email will
	// result in a magiclink being sent out.
	UpdateUser(req types.UpdateUserRequest) (*types.UpdateUserResponse, error)

	// GET /verify
	//
	// Verify a registration or a password recovery. Type can be signup or recovery
	// or magiclink or invite and the token is a token returned from either /signup
	// or /recover or /magiclink.
	//
	// The server returns a redirect response. This method will not follow the
	// redirect, but instead returns the URL the client was told to redirect to,
	// as well as parsing the parameters from the URL fragment.
	//
	// NOTE: This endpoint may return a nil error, but the Response can contain
	// error details extracted from the returned URL. Please check that the Error,
	// ErrorCode and/or ErrorDescription fields of the response are empty.
	Verify(req types.VerifyRequest) (*types.VerifyResponse, error)
	// POST /verify
	//
	// Verify a registration or a password recovery. Type can be signup or recovery
	// or magiclink or invite and the token is a token returned from either /signup
	// or /recover or /magiclink.
	//
	// This differs from GET /verify as it requires an email or phone to be given,
	// which is used to verify the token associated to the user. It also returns a
	// JSON response rather than a redirect.
	VerifyForUser(req types.VerifyForUserRequest) (*types.VerifyForUserResponse, error)

	// GET /sso/saml/metadata
	//
	// Get the SAML metadata for the configured SAML provider.
	//
	// If successful, the server returns an XML response. Making sense of this is
	// outside the scope of this client, so it is simply returned as []byte.
	SAMLMetadata() ([]byte, error)
	// POST /sso/saml/acs
	//
	// Implements the main Assertion Consumer Service endpoint behavior.
	//
	// This client does not provide a typed endpoint for SAML ACS. This method is
	// provided for convenience and will simply POST your HTTP request to the
	// endpoint and return the response.
	//
	// For required parameters, see the SAML spec or the Auth implementation
	// of this endpoint.
	//
	// The server may issue redirects. Using the default HTTP client, this method
	// will follow those redirects and return the final HTTP response. Should you
	// prefer the client not to follow redirects, you can provide a custom HTTP
	// client using WithClient(). See the example below.
	//
	// Example:
	//	c := http.Client{
	//		CheckRedirect: func(req *http.Request, via []*http.Request) error {
	//			return http.ErrUseLastResponse
	//		},
	//	}
	SAMLACS(req *http.Request) (*http.Response, error)

	// POST /sso
	//
	// Initiate an SSO session with the given provider.
	//
	// If successful, the server returns a redirect to the provider's authorization
	// URL. The client will follow it and return the final HTTP response.
	//
	// Auth allows you to skip following the redirect by setting SkipHTTPRedirect
	// on the request struct. In this case, the URL to redirect to will be returned
	// in the response.
	SSO(req types.SSORequest) (*types.SSOResponse, error)
}

Create a new client using auth.New, then you can call the methods below.

Some methods require bearer token authentication. To set the bearer token, use the WithToken(token) method.

func New

func New(url string, projectReference string, apiKey string) Client

Set up a new Auth client.

url: The URL is the base URL for your Supabase project. It should be in the format "https://%s.supabase.co/auth/v1".

projectReference: The project reference is the unique identifier for your Supabase project. It can be found in the Supabase dashboard under project settings as Reference ID.

apiKey: The API key is used to authenticate requests to the Auth server. This should be your anon key.

This function does not validate your project reference. Requests will fail if you pass in an invalid project reference.