Various minor SSO fixes and readme updates (#95)

* Fix the following: 1. Update readme for instructions on implementing SSO, 2: Fix some missing enum values ported from supabase auth repo, 3: Add some example persistence code

* Cleanup ClientPersistence example file

Author: Rycko1

Gotrue/Constants.cs

@@ -62,6 +62,8 @@ public enum EmailOtpType
 		/// </summary>
 		public enum Provider
 		{
+			[MapTo("anonymous_users")]
+			AnonymousUsers,
 			[MapTo("apple")]
 			Apple,
 			[MapTo("azure")]
@@ -149,4 +151,4 @@ public enum SignUpType
 			Phone
 		}
 	}
-}
+}

Gotrue/Settings.cs

@@ -21,10 +21,14 @@ public class Settings
 		[JsonProperty("sms_provider")]
 		public string? SmsProvider { get; set; }
 
-		[JsonProperty("external")]
-		public Dictionary<string, bool>? Services { get; set; }
+		[JsonProperty("mfa_enabled")]
+		public bool? MFAEnabled { get; set; }
+
+		// SAML = SSO enabled
+		[JsonProperty("saml_enabled")]
+		public bool? SAMLEnabled { get; set; }
 
-		[JsonProperty("external_labels")]
-		public Dictionary<string, string>? Labels { get; set; }
+		[JsonProperty("external")]
+		public Dictionary<string, bool>? ExternalProviders { get; set; }
 	}
 }

Gotrue/SignInAnonymouslyOptions.cs

@@ -4,6 +4,9 @@
 
 namespace Supabase.Gotrue
 {
+	/// <summary>
+	/// Options for handling signing in anonymously
+	/// </summary>
 	public class SignInAnonymouslyOptions
 	{
 		/// <summary>
@@ -20,4 +23,4 @@ public class SignInAnonymouslyOptions
 		[JsonProperty("captchaToken")]
 		public string? CaptchaToken { get; set; }
 	}
-}
+}

GotrueExample/ClientPersistence.cs

@@ -0,0 +1,52 @@
+#nullable enable
+
+using Microsoft.Extensions.Logging;
+using Supabase.Gotrue;
+using Supabase.Gotrue.Interfaces;
+
+namespace GotrueExample;
+
+/// <summary>
+/// This is an example of how to handle session persistence using the helpers and interfaces provided
+///
+/// We typically would load the session from storage here if we want to persist things to disk
+/// between application restarts. Depending on your use case you will need to implement SaveSession and LoadSession differently
+/// to handle loading and saving the session in your applications cache
+/// </summary>
+/// <example>
+/// Usage using dependency injection
+/// <code>
+///     services.AddSingleton<IGotrueSessionPersistence<Session>, ClientPersistence>();
+///     var provider = Host.Run();
+///     var client = provider.GetRequiredService<IGotrueClient<User, Session>>();
+///     var sessionPersistence = provider.GetRequiredService<IGotrueSessionPersistence<Session>>();
+///     client.SetPersistence(sessionPersistence);
+/// </code>
+/// </example>
+public class ClientPersistence : IGotrueSessionPersistence<Session>
+{
+    private Session? _session;
+    private ILogger<ClientPersistence> Logger { get; }
+
+    public ClientPersistence(ILogger<ClientPersistence> logger)
+    {
+        Logger = logger;
+        IGotruePersistenceListener<Session> persistenceListener = new PersistenceListener(this);
+        persistenceListener.Persistence.LoadSession();
+    }
+
+    public void SaveSession(Session session)
+    {
+        _session = session;
+    }
+
+    public void DestroySession()
+    {
+        _session = null;
+    }
+
+    public Session? LoadSession()
+    {
+        return _session;
+    }
+}

GotrueExample/Program.cs

@@ -8,13 +8,18 @@
 
 namespace GotrueExample
 {
-    internal class Program
+    internal static class Program
     {
-        private static Random random = new Random();
+        private static Random random = new();
         static void Main(string[] args)
         {
             using IHost host = Host.CreateDefaultBuilder(args)
-                .ConfigureServices((_, services) => services.AddSingleton<IGotrueClient<User, Session>, Client>())
+                .ConfigureServices((_, services) =>
+                {
+                    services.AddSingleton<IGotrueClient<User, Session>, Client>();
+                    services.AddSingleton<IGotrueSessionPersistence<Session>, ClientPersistence>();
+                    services.AddLogging();
+                })
                 .Build();
 
             UseClient(host.Services);
@@ -28,6 +33,8 @@ static async void UseClient(IServiceProvider services)
             IServiceProvider provider = serviceScope.ServiceProvider;
 
             var client = provider.GetRequiredService<IGotrueClient<User, Session>>();
+            var sessionPersistence = provider.GetRequiredService<IGotrueSessionPersistence<Session>>();
+            client.SetPersistence(sessionPersistence);
 
             Session session = null;
             var email = $"{RandomString(12)}@supabase.io";

GotrueTests/StatelessClientTests.cs

@@ -76,8 +76,8 @@ public async Task Settings()
 		{
 			var settings = await _client.Settings(Options);
 			Assert.IsNotNull(settings);
-			Assert.IsFalse(settings.Services["zoom"]);
-			Assert.IsTrue(settings.Services["email"]);
+			Assert.IsFalse(settings.ExternalProviders["zoom"]);
+			Assert.IsTrue(settings.ExternalProviders["email"]);
 			Assert.IsFalse(settings.DisableSignup);
 			Assert.IsTrue(settings.MailerAutoConfirm);
 			Assert.IsTrue(settings.PhoneAutoConfirm);

README.md

@@ -227,6 +227,52 @@ var state = await client.SignIn(Constants.Provider.Github, new SignInOptions
 var session = await client.ExchangeCodeForSession(state.PKCEVerifier, RETRIEVE_CODE_FROM_GET_PARAMS);
 ```
 
+## Sign In With Single Sign On (SSO)
+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](https://supabase.com/docs/guides/auth/enterprise-sso/auth-sso-saml) 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:
+
+1. Request initiated by calling `SignInWithSSO`
+   1. The `RedirectTo` attribute is recommended for handling the callback and converting to a session
+1. `ssoResposne` contains the providers login Uri, navigate to this
+1. User logs in with provider (Okta/Auth0, Microsoft Entra, Google Workspaces ect...)
+1. Supabase GoTrue server handles SAML exchange for us
+   1. Supabase GoTrue server generates session info and appends it to the callback (RedirectedTo) url
+1. We can then use either `ExchangeCodeForSession(code)` or `GetSessionFromUrl(callbackUri)`
+
+```csharp
+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: http://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](GotrueExample/SupabaseClientPersistence.cs)
+
+For additional info on how the GoTrue server handles SSO requests see 
+[here](https://github.com/supabase/auth/blob/55409f797bea55068a3fafdddd6cfdb78feba1b4/internal/api/samlacs.go#L315-L316)
+and [here](https://github.com/supabase/auth/blob/55409f797bea55068a3fafdddd6cfdb78feba1b4/internal/api/token.go#L54-L55)
 ## Troubleshooting
 
 **Q: I've created a User but while attempting to log in it throws an exception:**