feat: add sso (#358)

Author: J0

gotrue/_async/gotrue_client.py

@@ -31,6 +31,7 @@
     model_dump_json,
     model_validate,
     parse_auth_response,
+    parse_sso_response,
     parse_user_response,
 )
 from ..http_clients import AsyncClient
@@ -253,6 +254,63 @@ async def sign_in_with_password(
             self._notify_all_subscribers("SIGNED_IN", response.session)
         return response
 
+    async def sign_in_with_sso(self, credentials: SignInWithSSOCredentials):
+        """
+        Attempts a single-sign on using an enterprise Identity Provider. A
+        successful SSO attempt will redirect the current page to the identity
+        provider authorization page. The redirect URL is implementation and SSO
+        protocol specific.
+
+        You can use it by providing a SSO domain. Typically you can extract this
+        domain by asking users for their email address. If this domain is
+        registered on the Auth instance the redirect will use that organization's
+        currently active SSO Identity Provider for the login.
+        If you have built an organization-specific login page, you can use the
+        organization's SSO Identity Provider UUID directly instead.
+        """
+        self._remove_session()
+        provider_id = credentials.get("provider_id")
+        domain = credentials.get("domain")
+        options = credentials.get("options", {})
+        redirect_to = options.get("redirect_to")
+        captcha_token = options.get("captcha_token")
+        # HTTPX currently does not follow redirects: https://www.python-httpx.org/compatibility/
+        # Additionally, unlike the JS client, Python is a server side language and it's not possible
+        # to automatically redirect in browser for hte user
+        skip_http_redirect = options.get("skip_http_redirect", True)
+
+        if domain:
+            return self._request(
+                "POST",
+                "sso",
+                body={
+                    "domain": domain,
+                    "skip_http_redirect": skip_http_redirect,
+                    "gotrue_meta_security": {
+                        "captcha_token": captcha_token,
+                    },
+                },
+                redirect_to=redirect_to,
+                xform=parse_sso_response,
+            )
+        if provider_id:
+            return self._request(
+                "POST",
+                "sso",
+                body={
+                    "provider_id": provider_id,
+                    "skip_http_redirect": skip_http_redirect,
+                    "gotrue_meta_security": {
+                        "captcha_token": captcha_token,
+                    },
+                },
+                redirect_to=redirect_to,
+                xform=parse_sso_response,
+            )
+        raise AuthInvalidCredentialsError(
+            "You must provide either a domain or provider_id"
+        )
+
     async def sign_in_with_oauth(
         self,
         credentials: SignInWithOAuthCredentials,

gotrue/_sync/gotrue_client.py

@@ -31,6 +31,7 @@
     model_dump_json,
     model_validate,
     parse_auth_response,
+    parse_sso_response,
     parse_user_response,
 )
 from ..http_clients import SyncClient
@@ -253,6 +254,63 @@ def sign_in_with_password(
             self._notify_all_subscribers("SIGNED_IN", response.session)
         return response
 
+    def sign_in_with_sso(self, credentials: SignInWithSSOCredentials):
+        """
+        Attempts a single-sign on using an enterprise Identity Provider. A
+        successful SSO attempt will redirect the current page to the identity
+        provider authorization page. The redirect URL is implementation and SSO
+        protocol specific.
+
+        You can use it by providing a SSO domain. Typically you can extract this
+        domain by asking users for their email address. If this domain is
+        registered on the Auth instance the redirect will use that organization's
+        currently active SSO Identity Provider for the login.
+        If you have built an organization-specific login page, you can use the
+        organization's SSO Identity Provider UUID directly instead.
+        """
+        self._remove_session()
+        provider_id = credentials.get("provider_id")
+        domain = credentials.get("domain")
+        options = credentials.get("options", {})
+        redirect_to = options.get("redirect_to")
+        captcha_token = options.get("captcha_token")
+        # HTTPX currently does not follow redirects: https://www.python-httpx.org/compatibility/
+        # Additionally, unlike the JS client, Python is a server side language and it's not possible
+        # to automatically redirect in browser for hte user
+        skip_http_redirect = options.get("skip_http_redirect", True)
+
+        if domain:
+            return self._request(
+                "POST",
+                "sso",
+                body={
+                    "domain": domain,
+                    "skip_http_redirect": skip_http_redirect,
+                    "gotrue_meta_security": {
+                        "captcha_token": captcha_token,
+                    },
+                },
+                redirect_to=redirect_to,
+                xform=parse_sso_response,
+            )
+        if provider_id:
+            return self._request(
+                "POST",
+                "sso",
+                body={
+                    "provider_id": provider_id,
+                    "skip_http_redirect": skip_http_redirect,
+                    "gotrue_meta_security": {
+                        "captcha_token": captcha_token,
+                    },
+                },
+                redirect_to=redirect_to,
+                xform=parse_sso_response,
+            )
+        raise AuthInvalidCredentialsError(
+            "You must provide either a domain or provider_id"
+        )
+
     def sign_in_with_oauth(
         self,
         credentials: SignInWithOAuthCredentials,

gotrue/helpers.py

@@ -17,6 +17,7 @@
     GenerateLinkProperties,
     GenerateLinkResponse,
     Session,
+    SSOResponse,
     User,
     UserResponse,
 )
@@ -91,6 +92,10 @@ def parse_user_response(data: Any) -> UserResponse:
     return model_validate(UserResponse, data)
 
 
+def parse_sso_response(data: Any) -> SSOResponse:
+    return model_validate(SSOResponse, data)
+
+
 def get_error_message(error: Any) -> str:
     props = ["msg", "message", "error_description", "error"]
     filter = (

gotrue/types.py

@@ -94,6 +94,10 @@ class OAuthResponse(BaseModel):
     url: str
 
 
+class SSOResponse(BaseModel):
+    url: str
+
+
 class UserResponse(BaseModel):
     user: User
 
@@ -323,6 +327,17 @@ class SignInWithOAuthCredentials(TypedDict):
     options: NotRequired[SignInWithOAuthCredentialsOptions]
 
 
+class SignInWithSSOCredentials(TypedDict):
+    provider_id: NotRequired[str]
+    domain: NotRequired[str]
+    options: NotRequired[SignInWithSSOOptions]
+
+
+class SignInWithSSOOptions(TypedDict):
+    redirect_to: NotRequired[str]
+    skip_http_redirect: NotRequired[bool]
+
+
 class VerifyOtpParamsOptions(TypedDict):
     redirect_to: NotRequired[str]
     captcha_token: NotRequired[str]