[Notice]: v5.0.0 renames this package from gotrue-csharp
to Supabase.Gotrue
. The depreciation notice has been set in NuGet. The API remains the same.
The Client works with Unity. You can find an example of a session persistence implementation for Unity at this gist.
The Client now better supports online/offline usage. The Client now has a simple boolean option "Online" which can be set to to false. This can be combined with the NetworkStatus class to allow the client to automatically go online & offline based on the device's network status.
To use this new NetworkStatus, add the following:
// Create the client
var client = new Client(new ClientOptions { AllowUnconfirmedUserSessions = true });
// Create the network status monitor
var status = new NetworkStatus();
// Tell the network status monitor to update the client's online status
status.Client = client;
// Start the network status monitor
await status.StartAsync();
// rest of the usual client configuration
Only the stateful Client supports this feature, and only for the managed user sessions. Admin JWT methods and the stateless client are not affected.
By default, this change will not affect existing code.
The Client now supports setting a maximum wait time before refreshing the token. This is useful for scenarios where you want to refresh the token before it expires, but not too often.
By default, GoTrue servers are typically set to expire the token after an hour, and the refresh thread will refresh the token when ~20% of that time is left.
However, you can set the expiration time to be much longer on the server (up to a week). In this scenario, you may want to refresh the token more often than once every 5 days or so, but not every hour.
There is now a new option MaximumRefreshWaitTime
which allows you to specify the maximum amount
in time that the refresh thread will wait before refreshing the token. This defaults to 4 hours.
This means that if you have your server set to a one hour token expiration, nothing changes, but
if you extend the server refresh to (for example) a week, as long as the user launches the app
at least once a week, they will never have to re-authenticate.
- Exceptions have been simplified to a single
GotrueException
. AReason
field has been added toGotrueException
to clarify what happened. This should also be easier to manage as the Gotrue server API & messages evolve. - The session delegates for
Save
/Load
/Destroy
have been simplified to no longer requireasync
. - Console logging in a few places (most notable the background refresh thread) has been removed
in favor of a notification method. See
Client.AddDebugListener()
and the test cases for examples. This will allow you to implement your own logging strategy (write to temp file, console, user visible err console, etc). - The client now more reliably emits AuthState changes.
- There is now a single source of truth for headers in the stateful Client - the
Options
headers.
New feature:
- Added a
Settings
request to the stateless API only - you can now query the server instance to determine if it's got the settings you need. This might allow for things like a visual component in a tool to verify the GoTrue settings are working correctly, or tests that run differently depending on the server configuration.
Implementation notes:
- Test cases have been added to help ensure reliability of auth state change notifications and persistence.
- Persistence is now managed via the same notifications as auth state change
- We've implemented the PKCE auth flow. SignIn using a provider now returns an instance of
ProviderAuthState
rather than astring
. - The provider sign in signature has moved
scopes
intoSignInOptions
In Short:
# What was:
var url = await client.SignIn(Provider.Github, "scopes and things");
# Becomes:
var state = await client.SignIn(Provider.Github, new SignInOptions { "scopes and things" });
// Url is now at `state.Uri`
To use this library on the Supabase Hosted service but separately from the supabase-csharp
, you'll need to specify
your url and public key like so:
var auth = new Supabase.Gotrue.Client(new ClientOptions<Session>
{
Url = "https://PROJECT_ID.supabase.co/auth/v1",
Headers = new Dictionary<string, string>
{
{ "apikey", SUPABASE_PUBLIC_KEY }
}
})
Otherwise, using it this library with a local instance:
var options = new ClientOptions { Url = "https://example.com/api" };
var client = new Client(options);
var user = await client.SignUp("[email protected]");
// Alternatively, you can use a StatelessClient and do API interactions that way
var options = new StatelessClientOptions { Url = "https://example.com/api" }
await new StatelessClient().SignUp("[email protected]", options);
This Gotrue client is written to be agnostic when it comes to session persistence, retrieval, and
destruction. ClientOptions
exposes
properties that allow these to be specified.
In the event these are specified and the AutoRefreshToken
option is set, as the Client
Initializes, it will also
attempt to
retrieve, set, and refresh an existing session.
For example, using Xamarin.Essentials
in Xamarin.Forms
, this might look like:
// This is a method you add your application launch/setup
async void Initialize() {
// Specify the methods you'd like to use as persistence callbacks
var persistence = new GotrueSessionPersistence(SaveSession, LoadSession, DestroySession);
var client = new Client(
Url = GOTRUE_URL,
new ClientOptions {
AllowUnconfirmedUserSessions = true,
SessionPersistence = persistence });
// Specify a debug callback to listen to problems with the background token refresh thread
client.AddDebugListener(LogDebug);
// Specify a call back to listen to changes in the user state (logged in, out, etc)
client.AddStateChangedListener(AuthStateListener);
// Load the session from persistence
client.LoadSession();
// Loads the session using SessionRetriever and sets state internally.
await client.RetrieveSessionAsync();
}
// Add callback methods for above
// Here's a quick example of using this to save session data to the user's cache folder
// You'll want to add methods for loading the file and deleting when the user logs out
internal bool SaveSession(Session session)
{
var cacheFileName = ".gotrue.cache";
try
{
var cacheDir = FileSystem.CacheDirectory;
var path = Path.Join(cacheDir, cacheFileName);
var str = JsonConvert.SerializeObject(session);
using (StreamWriter file = new StreamWriter(path))
{
file.Write(str);
file.Dispose();
return Task.FromResult(true);
};
}
catch (Exception err)
{
Debug.WriteLine("Unable to write cache file.");
throw err;
}
}
Once again, Gotrue client is written to be agnostic of platform. In order for Gotrue to sign in a user from an Oauth callback, the PKCE flow is preferred:
- The Callback Url must be set in the Supabase Admin panel
- The Application should have listener to receive that Callback
- Generate a sign in request using:
client.SignIn(PROVIDER, options)
and setting the options to use the PKCEFlowType
- Store
ProviderAuthState.PKCEVerifier
so that the application callback can use it to verify the returned code - In the Callback, use stored
PKCEVerifier
and receivedcode
to exchange for a session.
var state = await client.SignIn(Constants.Provider.Github, new SignInOptions
{
FlowType = Constants.OAuthFlowType.PKCE,
RedirectTo = "https://localhost:3000/oauth/callback"
});
// In callback received from Supabase returning to RedirectTo (set above)
// Url is set as: https://REDIRECT_TO_URL?code=CODE
var session = await client.ExchangeCodeForSession(state.PKCEVerifier, RETRIEVE_CODE_FROM_GET_PARAMS);
Single Sign On (SSO) is an enterprise level authentication protocol that allows a single enterprise account to access many apps at once. A few examples of supported SSO providers are Okta, Microsoft Entra and Google Workspaces
If not already done so, you must first add an SSO provider to your supabase project via the supabase CLI. See the following link for more info on how to configure SSO providers
The flow functions similar to the OAuth flow and supports many of the same parameters. Under the hood the flow is handled quite differently by the GoTrue server but the client is agnostic to the difference in implementations and session info is handled in the same way as the OAuth flow
General auth flow is as follows:
- Request initiated by calling
SignInWithSSO
- The
RedirectTo
attribute is recommended for handling the callback and converting to a session
- The
ssoResposne
contains the providers login Uri, navigate to this- User logs in with provider (Okta/Auth0, Microsoft Entra, Google Workspaces ect...)
- Supabase GoTrue server handles SAML exchange for us
- Supabase GoTrue server generates session info and appends it to the callback (RedirectedTo) url
- We can then use either
ExchangeCodeForSession(code)
orGetSessionFromUrl(callbackUri)
using Constants = Supabase.Gotrue.Constants;
var ssoResponse = await client.SignInWithSSO("supabase.io", new SignInWithSSOOptions
{
RedirectTo = "https://localhost:3000/welcome"
});
// Handle login via ssoResponse.Uri
//
// When the user logs in using the Uri from the ssoResponse,
// they will be redirected to the RedirectTo
// In callback received from Supabase returning to RedirectTo (set above)
// Url is set as: https://REDIRECT_TO_URL?access_token=foobar&expires_at=123...
var session = await client.GetSessionFromUrl(url);
For handling session persistence its recommended using a session persistence layer, take a look at the following example
For additional info on how the GoTrue server handles SSO requests see here and here
Q: I've created a User but while attempting to log in it throws an exception:
A: Provided the credentials are correct, make sure that the User has also confirmed their email.
Adding a handler for email confirmation to a desktop or mobile application can be done, but it requires setting up URL handlers for each platform, which can be pretty difficult to do if you aren't really comfortable with configuring these handlers. ( e.g. Windows, Apple, Android) You may find it easier to create a simple web application to handle email confirmation - that way a user can just click a link in their email and get confirmed that way. Your desktop or mobile app should inspect the user object that comes back and use that to see if the user is confirmed.
You might find it easiest to do something like create and deploy a simple SvelteKit or even a very basic pure JavaScript project to handle email verification.
- API
- Sign Up with Email
- Sign In with Email
- Send Magic Link Email
- Invite User by Email
- Reset Password for Email
- Signout
- Get Url for Provider
- Get User
- Update User
- Refresh Access Token
- List Users (includes filtering, sorting, pagination)
- Get User by Id
- Create User
- Update User by Id
- Sign In with Single Sign On (SSO)
- Client
- Get User
- Refresh Session
- Auth State Change Handler
- Provider Sign In (Provides URL)
- Sign In with Single Sign On (SSO)
- Provide Interfaces for Custom Token Persistence Functionality
- Documentation
- Unit Tests
- Nuget Release
Join the ranks! See a problem? Help fix it!
Made with contrib.rocks.
We are more than happy to have contributions! Please submit a PR.
To run the tests locally you must have docker and docker-compose installed. Then in the root of the repository run:
docker-compose up -d
dotnet test