[FR] Improve docs for SAML auth

[bdruth]

(note: I'm happy to contribute with a little direction)

I've just gone through and spent a good few hours trying to get SAML auth working. It seems that supabase/auth has diverged from gotrue in how SAML auth works, and I'm not entirely sure what of the existing Okta auth instructions are valid vs not.

(caveat, I was setting up Google Workspace/GSuite auth)

What I ended up having to do was define a GOTRUE_SAML_ENABLED=true and a GOTRUE_SAML_PRIVATE_KEY env var for gotrue. The initial directions here helped with figuring these new vars out.

In addition, the API_EXTERNAL_URL needed to have /gotrue appended, otherwise the ACS URL set in the SAML configuration in Google (or whatever the IdP is) won't match up with what's expected. It's unclear to me if this will impact anything else (like emails or whatever) - ultimately gotrue doesn't know, I think, that the nginx proxy puts it behind /gotrue/* - but you have to use this URL in the IdP, otherwise it won't redirect to a functional SAML endpoint, but gotrue needs to validate that it's URL matches the AcsURL in the request it receives.

diff --git a/docker-compose.yml b/docker-compose.yml
index 0962b338..7a13e3e5 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -86,6 +86,8 @@ services:
       - GOTRUE_EXTERNAL_DISCORD_CLIENT_ID=${GOTRUE_EXTERNAL_DISCORD_CLIENT_ID}
       - GOTRUE_EXTERNAL_DISCORD_SECRET=${GOTRUE_EXTERNAL_DISCORD_SECRET}
       - GOTRUE_EXTERNAL_DISCORD_REDIRECT_URI=${GOTRUE_EXTERNAL_DISCORD_REDIRECT_URI}
+      - GOTRUE_SAML_ENABLED=${GOTRUE_SAML_ENABLED:-false}
+      - GOTRUE_SAML_PRIVATE_KEY=${GOTRUE_SAML_PRIVATE_KEY}

   appflowy_cloud:
     restart: on-failure

diff --git a/deploy.env b/deploy.env
index 75adfea0..fde0bcec 100644
--- a/deploy.env
+++ b/deploy.env
@@ -67,7 +67,7 @@ GOTRUE_ADMIN_PASSWORD=password
 # If you are using a different domain, you need to change the redirect_uri in the OAuth2 configuration
 # Make sure that this domain is accessible to the user
 # Make sure no endswith /
-API_EXTERNAL_URL=http://your-host
+API_EXTERNAL_URL=http://your-host/gotrue

 # In docker environment, `postgres` is the hostname of the postgres service
 # GoTrue connect to postgres using this url
@@ -94,6 +94,9 @@ GOTRUE_EXTERNAL_APPLE_ENABLED=false
 GOTRUE_EXTERNAL_APPLE_CLIENT_ID=
 GOTRUE_EXTERNAL_APPLE_SECRET=
 GOTRUE_EXTERNAL_APPLE_REDIRECT_URI=${API_EXTERNAL_URL}/gotrue/callback
+# SAML config
+GOTRUE_SAML_ENABLED=false
+GOTRUE_SAML_PRIVATE_KEY=

 # File Storage
 # Create the bucket if not exists on AppFlowy Cloud start up.

Here's the Google side of the configuration (I think this is basically what the Okta docs indicate, too), Name ID format is EMAIL

Thanks!

[speed2exe]

@bdruth Thanks for sharing. We have not explored SAML with Google's API, so this is really helpful. The information you gave is sufficient for self-hosters to set up. You may submit a doc in https://github.com/AppFlowy-IO/AppFlowy-Cloud/tree/main/doc.

[bdruth]

@speed2exe great! I'll put something together, then :)