From 53afb9d84c6a9cf187b21be0cdc30f31b1931fdc Mon Sep 17 00:00:00 2001
From: Stojan Dimitrovski <sdimitrovski@gmail.com>
Date: Fri, 7 Apr 2023 12:40:16 +0200
Subject: [PATCH 1/2] reference-docs: add `signInWithSSO` to JS/TS reference
 docs

---
 spec/common-client-libs-sections.json | 13 ++++++--
 spec/supabase_js_v2.yml               | 44 +++++++++++++++++++++++++++
 2 files changed, 54 insertions(+), 3 deletions(-)

diff --git a/spec/common-client-libs-sections.json b/spec/common-client-libs-sections.json
index dd45af3fbae..13716468d9d 100644
--- a/spec/common-client-libs-sections.json
+++ b/spec/common-client-libs-sections.json
@@ -418,6 +418,13 @@
         "product": "auth",
         "type": "function"
       },
+      {
+        "id": "sign-in-with-whatsapp-otp",
+        "title": "Sign in a user through WhatsApp",
+        "slug": "auth-signinwithwhatsappotp",
+        "product": "auth",
+        "type": "function"
+      },
       {
         "id": "sign-in-with-oauth",
         "title": "Sign in a user through OAuth",
@@ -426,9 +433,9 @@
         "type": "function"
       },
       {
-        "id": "sign-in-with-whatsapp-otp",
-        "title": "Sign in a user through WhatsApp",
-        "slug": "auth-signinwithwhatsappotp",
+        "id": "sign-in-with-sso",
+        "title": "Sign in a user through SSO",
+        "slug": "auth-signinwithsso",
         "product": "auth",
         "type": "function"
       },
diff --git a/spec/supabase_js_v2.yml b/spec/supabase_js_v2.yml
index 756981f630e..8c8df4ce60b 100644
--- a/spec/supabase_js_v2.yml
+++ b/spec/supabase_js_v2.yml
@@ -319,6 +319,50 @@ functions:
           })
           const oAuthToken = data.session.provider_token // use to access provider API
           ```
+  - id: sign-in-with-sso
+    title: 'signInWithSSO()'
+    $ref: '@supabase/gotrue-js.GoTrueClient.signInWithSSO'
+    notes: |
+      - Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.
+      - If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.
+      - In case you need to use a different way to start the authentication flow with an identity provider, you can use the `providerId` property. For example:  
+          - Mapping specific user email addresses with an identity provider.
+          - Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.
+    examples:
+      - id: sign-in-with-domain
+        name: Sign in with email domain
+        isSpotlight: true
+        code: |
+          ```js
+            // You can extract the user's email domain and use it to trigger the
+            // authentication flow with the correct identity provider.
+
+            const { data, error } = await supabase.auth.signInWithSSO({
+              domain: 'company.com'
+            })
+
+            if (data?.url) {
+              // redirect the user to the identity provider's authentication flow
+              window.location.href = data.url
+            }
+          ```
+      - id: sign-in-with-provider-uuid
+        name: Sign in with provider UUID
+        isSpotlight: true
+        code: |
+          ```js
+            // Useful when you need to map a user's sign in request according
+            // to different rules that can't use email domains.
+
+            const { data, error } = await supabase.auth.signInWithSSO({
+              providerId: '21648a9d-8d5a-4555-a9d1-d6375dc14e92'
+            })
+
+            if (data?.url) {
+              // redirect the user to the identity provider's authentication flow
+              window.location.href = data.url
+            }
+          ```
   - id: sign-out
     title: 'signOut()'
     $ref: '@supabase/gotrue-js.GoTrueClient.signOut'

From 37e874e56435f9498d53779231ae13452c456363 Mon Sep 17 00:00:00 2001
From: Stojan Dimitrovski <sdimitrovski@gmail.com>
Date: Fri, 7 Apr 2023 12:42:01 +0200
Subject: [PATCH 2/2] docs: link to `signInWithSSO` reference doc in SAML guide

---
 apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx b/apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx
index d5598cc9c7a..7c5bd60da23 100644
--- a/apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx
+++ b/apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx
@@ -185,7 +185,7 @@ supabase.auth.signInWithSSO({
 })
 ```
 
-Calling this method starts the sign-in process using the identity provider registered for the `company.com` domain name. It is not required that identity providers be assigned one or multiple domain names, in which case you can use the provider's unique ID instead.
+Calling [`signInWithSSO`](/docs/reference/javascript/auth-signinwithsso) starts the sign-in process using the identity provider registered for the `company.com` domain name. It is not required that identity providers be assigned one or multiple domain names, in which case you can use the provider's unique ID instead.
 
 ### Understanding attribute mappings