基于Supabase实现企业SSO接入

步骤一：获取Supabase项目信息

开通Supabase项目后，可获取以下Supabase信息项。

验证项目状态

curl 'https://<your-supabase-url>/auth/v1/health' \
  -H 'apikey: <your-anon-key>'

返回示例

{"version":"vunspecified","name":"GoTrue","description":"GoTrue is a user registration and authentication API"}

步骤二：获取SP元数据

SAML服务提供商（SP）的元数据可通过以下地址公开访问：

https://<your-supabase-url>/sso/saml/metadata

您需要用到以下两个关键地址，在后续步骤中将其配置到IdP中：

步骤三：配置重定向URL

1. 登录Supabase Dashboard，在Dashboard侧边栏单击Authentication>URL Configuration，进入Site URL配置页面。

2. 在Site URL区域，填入前端域名地址，然后单击Save changes保存。

步骤四：注册身份提供商（IdP）

使用Management API将您的IdP注册到Supabase。

curl -X POST 'https://<your-supabase-url>/auth/v1/admin/sso/providers' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "saml",
    "metadata_url": "https://<your-idp>/samlp/metadata/<client-id>",
    "domains": ["yourdomain.com"]
  }'

# 1. 在可访问IdP的环境中获取Metadata XML
curl 'https://<your-idp>/samlp/metadata/<client-id>' > idp-metadata.xml

# 2. 注册到Supabase
curl -X POST 'https://<your-supabase-url>/auth/v1/admin/sso/providers' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "saml",
    "metadata_xml": "<EntityDescriptor ...>...</EntityDescriptor>",
    "domains": ["yourdomain.com"]
  }'

https://<tenant>.auth0.com/samlp/metadata/<client-id>

curl -X POST 'https://<your-supabase-url>/auth/v1/admin/sso/providers' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "saml",
    "metadata_url": "https://dev-xxx.auth0.com/samlp/metadata/YOUR_CLIENT_ID",
    "domains": ["example.com"]
  }'

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "type": "saml",
  "saml": {
    "entity_id": "urn:dev-xxx.auth0.com"
  },
  "domains": [{"domain": "example.com"}]
}

步骤五：在IdP侧配置SP信息

注册完成后，需要在您的IdP中配置Supabase的SP信息。

步骤六：前端集成

1. 安装依赖。

   npm install @supabase/supabase-js

2. 初始化客户端。SAML SSO必须使用implicit flow。

   import { createClient } from '@supabase/supabase-js'
   
   const supabase = createClient(
     'https://<your-supabase-url>',
     '<your-anon-key>',
     {
       auth: {
         flowType: 'implicit',
         detectSessionInUrl: true,
         persistSession: true,
         autoRefreshToken: true,
       }
     }
   )

3. 发起SSO登录。

   • 通过Provider ID发起登录：

     const { data, error } = await supabase.auth.signInWithSSO({
       providerId: '<your-provider-id>',
       options: {
         redirectTo: window.location.origin
       }
     })
     
     if (error) {
       console.error('登录失败:', error.message)
       return
     }
     
     if (data?.url) {
       window.location.href = data.url
     }

   • 通过域名自动匹配Provider：

     const { data, error } = await supabase.auth.signInWithSSO({
       domain: 'yourdomain.com'
     })

4. 处理登录回调。

   IdP认证完成后会重定向回前端，URL格式为：

   https://<your-app-domain>/#access_token=<jwt>&refresh_token=<token>&expires_in=3600&token_type=bearer

   由于supabase-js的初始化是异步的，建议手动解析URL hash：

   function decodeJWT(token) {
     try {
       return JSON.parse(atob(token.split('.')[1].replace(/-/g, '+').replace(/_/g, '/')))
     } catch {
       return null
     }
   }
   
   async function init() {
     const hash = window.location.hash.substring(1)
     if (hash.includes('access_token')) {
       const params = new URLSearchParams(hash)
       const accessToken = params.get('access_token')
       const refreshToken = params.get('refresh_token')
       const expiresAt = params.get('expires_at')
       
       window.history.replaceState({}, '', window.location.pathname)
       
       const payload = decodeJWT(accessToken)
       if (payload) {
         const session = {
           access_token: accessToken,
           refresh_token: refreshToken || '',
           expires_at: expiresAt ? parseInt(expiresAt) : payload.exp,
           token_type: 'bearer',
           user: {
             id: payload.sub,
             email: payload.email,
             role: payload.role,
             app_metadata: payload.app_metadata || {},
             user_metadata: payload.user_metadata || {},
           }
         }
         onLoginSuccess(session)
         return
       }
     }
   
     const { data: { session } } = await supabase.auth.getSession()
     if (session) {
       onLoginSuccess(session)
     } else {
       showLoginPage()
     }
   }
   
   document.addEventListener('DOMContentLoaded', init)

5. 查看JWT Payload结构。

   登录成功后，JWT解码后包含以下关键字段：

   {
     "sub": "8c308927-4ba1-4507-b6f8-f751b791****",
     "email": "user@example.com",
     "role": "authenticated",
     "aal": "aal1",
     "amr": [{
       "method": "sso/saml",
       "timestamp": 1774928127,
       "provider": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     }],
     "app_metadata": {
       "provider": "sso:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
     },
     "session_id": "aeaf9cdb-dbcd-46ab-95a5-ff956e69****"
   }

   通过amr[0].method === 'sso/saml'可确认用户通过SSO登录。

查询Provider列表

curl 'https://<your-supabase-url>/auth/v1/admin/sso/providers' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>'

您也可以通过Supabase Dashboard查看auth.sso_domains和auth.sso_providers表，确认已注册的SSO Provider。

查询单个Provider

curl 'https://<your-supabase-url>/auth/v1/admin/sso/providers/<provider-id>' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>'

更新Provider

curl -X PUT 'https://<your-supabase-url>/auth/v1/admin/sso/providers/<provider-id>' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>' \
  -H 'Content-Type: application/json' \
  -d '{"metadata_url": "https://<your-idp>/samlp/metadata/<client-id>"}'

删除Provider

curl -X DELETE 'https://<your-supabase-url>/auth/v1/admin/sso/providers/<provider-id>' \
  -H 'apikey: <your-service-role-key>' \
  -H 'Authorization: Bearer <your-service-role-key>'

单击登录按钮后没有跳转

确认createClient中设置了flowType: 'implicit'。默认的PKCE flow在SAML回调场景下可能导致问题。

回调后仍显示登录页

不要仅依赖supabase.auth.getSession()处理回调。SDK的初始化是异步的，请在DOMContentLoaded时手动解析URL hash中的access_token。

登录失败：No such SSO provider

1. 检查前端代码中的providerId是否与注册时返回的ID一致。

2. 强制刷新浏览器（Cmd+Shift+R / Ctrl+Shift+R）清除缓存。

登录失败：Failed to fetch

1. 检查网络是否能访问Supabase项目。

2. 在浏览器控制台执行测试命令验证连通性。

登录后跳回错误的地址

在signInWithSSO()的options.redirectTo中明确指定前端地址，该参数会覆盖实例默认的Site URL。

SAML RelayState has expired

SSO登录URL有时效性（通常几分钟）。请勿复用旧的登录URL，每次单击登录按钮时应重新调用signInWithSSO()。

Auth0报错：invalid_request

检查Auth0的Allowed Callback URLs是否包含您的前端域名，Application Callback URL是否为Supabase的ACS URL。