Custom SMTP server configuration via Management API
Custom SMTP can be configured using the Supabase Management API by making a PATCH request to https://api.supabase.com/v1/projects/$PROJECT_REF/config/auth with the following parameters: external_email_enabled (boolean), mailer_secure_email_change_enabled (boolean), mailer_autoconfirm (boolean), smtp_admin_email (string), smtp_host (string), smtp_port (number), smtp_user (string), smtp_pass (string), and smtp_sender_name (string). The request requires an Authorization header with a Bearer token from the Supabase dashboard account tokens page.
Default SMTP server restrictions and limitations
Supabase provides a default SMTP server for all projects to allow exploration and setup of email templates. This server has three key restrictions: (1) it sends messages only to pre-authorized addresses (project team members), refusing delivery to other addresses with an 'Email address not authorized' error; (2) it has significant rate limits currently set to a value that can change without notice; (3) it provides no SLA guarantee on message delivery or uptime. The default SMTP service is intended only for non-production use cases such as exploring Supabase Auth, setting up email templates with team members, and building toy projects or demos.
Common SMTP abuse scenarios
Bots or attackers may attempt to abuse your SMTP server by signing up fake users to your application, potentially slowly over months or in sudden bursts. Goals of such attacks include damaging email sending reputation (possibly demanding ransom), causing denial of service by preventing account creation and sign-ins, or forcing security posture reduction like disabling email confirmations to enable account takeover attacks.
Abuse mitigation: CAPTCHA protection
Configuring CAPTCHA protection is the most effective way to control bots attempting to abuse your SMTP sending reputation by signing up fake accounts. Services providing invisible CAPTCHA challenges are recommended so real users won't be asked to solve puzzles most of the time.
@supabase/ssr and @supabase/server can be combined
In a cookie-based framework you can compose @supabase/ssr and @supabase/server together by letting @supabase/ssr own the cookie session lifecycle and handing the resolved token to @supabase/server's primitives. This requires more setup.
@supabase/server withSupabase example
import { withSupabase } from '@supabase/server'
export default {
fetch: withSupabase({ auth: 'user' }, async (req, ctx) => {
// ctx.supabase is scoped to the caller and respects RLS
const { data } = await ctx.supabase.from('todos').select()
return Response.json(data)
}),
}
This example shows how to use @supabase/server for header-based auth. The ctx.supabase is scoped to the caller and respects row-level security.
@supabase/ssr createServerClient example
import { createServerClient } from '@supabase/ssr'
const supabase = createServerClient(
process.env.SUPABASE_URL!,
process.env.SUPABASE_PUBLISHABLE_KEY!,
{
cookies: {
getAll() {
// return the request's cookies
},
setAll(cookiesToSet) {
// write cookies back on the response
},
},
}
)
This example shows how to create a server client for SSR frameworks that reads and writes session cookies.
When to use @supabase/server
Use @supabase/server when auth arrives per request in headers as 'Authorization: Bearer <jwt>'. It runs in Edge Functions, Workers, Vercel, Bun, and framework APIs such as Hono, H3, Elysia, and NestJS. It implements stateless Bearer JWT plus apikey auth model, verifies JWTs, and resolves API keys for you.
When to use @supabase/ssr
Use @supabase/ssr when user sessions are stored in cookies. It is for SSR frameworks like Next.js, SvelteKit, and TanStack Start. It implements cookie-based sessions with refresh-token rotation, making the same user and session available on both client and server.
When to use @supabase/supabase-js
Use supabase-js directly when you want the base client or you are handling auth yourself. It runs in browser and server, and you wire up auth.
Three server-side auth packages in Supabase
@supabase/ssr and @supabase/server both build on top of supabase-js and solve different problems. They are not alternatives to each other.
SAML 2.0 for enterprise SSO
Supabase Auth provides SAML 2.0 support for enterprise single sign-on implementations.
Associate email or social login to Web3 account
To associate an email address, phone number, or other social login with a Web3 authenticated account, use the supabase.auth.updateUser() or supabase.auth.linkIdentity() APIs. Web3 wallets only expose the wallet address (public key) as identifying information, so Web3 accounts do not have email or phone numbers associated by default.
Sign in with Ethereum using window.ethereum API
To sign in a user with their Ethereum wallet using the window.ethereum global scope API:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'ethereum',
statement: 'I accept the Terms of Service at https://example.com/tos',
})
Sign in with Phantom for Solana
To sign in a user with Phantom wallet for Solana when multiple Solana wallets are attached to the page:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'solana',
statement: 'I accept the Terms of Service at https://example.com/tos',
wallet: window.phantom,
})
Solana wallet detection via window.solana
Most Solana wallet applications expose their API via the window.solana global scope object. To sign in a user, ensure the user has installed a wallet application (window.solana is defined) and the wallet is connected using the window.solana.connect() API.
Sign in with Ethereum using custom message and signature
To sign in a user with a custom Ethereum wallet API by passing a Sign in with Ethereum (EIP-4361) message and signature:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'ethereum',
message: '<sign in with ethereum message>',
signature: '<hex of the ethereum signature over the message>',
})
Sign in with Ethereum using EIP-6963 wallet detection
To sign in a user with their Ethereum wallet after obtaining a wallet through EIP-6963 detection:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'ethereum',
statement: 'I accept the Terms of Service at https://example.com/tos',
wallet: selectedWallet, // obtain this using the EIP-6963 mechanism
})
Ethereum wallet detection methods
There are two ways to detect if a user has an Ethereum wallet installed: detect the window.ethereum global scope object (works only if the user has one wallet installed), or use the wallet discovery mechanism (EIP-6963) to ask the user to choose a wallet before sign-in.
Web3 Redirect URL configuration for abuse prevention
Register your application's URL in Redirect URL settings to prevent Supabase from receiving signed messages destined for other applications. For a sign-in page at https://example.com/sign-in, add https://example.com/sign-in/ (with trailing slash) or use a glob pattern like https://example.com/**.
Example: Solana Wallet Adapter React component
Example React component using Solana Wallet Adapter:
function SignInButton() {
const wallet = useWallet()
return (
<>
{wallet.connected ? (
<button
onClick={() => {
supabase.auth.signInWithWeb3({
chain: 'solana',
statement: 'I accept the Terms of Service at https://example.com/tos',
wallet,
})
}}
>
Sign in with Solana
</button>
) : (
<WalletMultiButton />
)}
</>
)
}
function App() {
const endpoint = clusterApiUrl('devnet')
const wallets = useMemo(() => [], [])
return (
<ConnectionProvider endpoint={endpoint}>
<WalletProvider wallets={wallets}>
<WalletModalProvider>
<SignInButton />
</WalletModalProvider>
</WalletProvider>
</ConnectionProvider>
)
}
Sign in with Solana using window.solana API
To sign in a user with their Solana wallet using the window.solana API:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'solana',
statement: 'I accept the Terms of Service at https://example.com/tos',
})
Providing a statement is required for most Solana wallets and will be shown to the user in the consent dialog.
Sign in with Brave Wallet for Solana
To sign in a user with Brave Wallet for Solana when it is not registered as the default window.solana object:
const { data, error } = await supabase.auth.signInWithWeb3({
chain: 'solana',
statement: 'I accept the Terms of Service at https://example.com/tos',
wallet: window.braveSolana,
})
Control Web3 sign-in abuse with rate limits and CAPTCHA
To control project exposure to Web3 sign-in abuse, configure rate limits and CAPTCHA protection in the dashboard or via CLI. The web3 rate limit setting controls the number of Web3 logins that can be made in a 5 minute interval per IP address. Default example: web3 = 30.
Web3 sign-in abuse concerns
User accounts created with Web3 sign-in do not have an email address or phone number associated with them. This can open a project to abuse because creating a Web3 wallet account is free and easy to automate and difficult to correlate with a real person's identity.
Enable Web3 provider in CLI
To enable Web3 authentication via CLI, add the following configuration to your supabase/config.toml file:
[auth.web3.solana]
enabled = true
[auth.web3.ethereum]
enabled = true
Web3 wallet address as identity identifier
The wallet address is used as the identity identifier for Web3 authenticated users. In the identity data you can also find the statement and additional metadata associated with the wallet.
Web3 signature validation rules
Supabase Auth validates the following before issuing a user session: message structure validation, cryptographic signature verification, timestamp validation ensuring the signature was created within 10 minutes of the sign-in call, and URI and Domain validation ensuring these match your server's defined Redirect URLs.
Web3 sign-in message structure
A Web3 sign-in message includes: the domain asking for sign-in, the wallet address, a customizable statement (which can be used to ask for consent), the URI where sign-in occurred, version number, chain ID, nonce, timestamp issued at, and optional resources. The message is signed by the wallet and validated by Supabase Auth.
Solana Wallet Adapter for sign-in
The Solana Wallet Adapter system, based on the Wallet Standard, simplifies development by handling subtle differences between wallet applications. The Supabase JavaScript Client Library supports signing in with this approach. Follow the Solana Interact with Wallets guide for installation and configuration, and use the useWallet() React hook to obtain the connected wallet for sign-in.
Supported Web3 wallets
Supabase Auth supports all Solana wallets and all Ethereum wallets for Web3 sign-in.
Web3 authentication uses EIP 4361 standard
Sign in with Web3 uses the EIP 4361 standard to authenticate wallet addresses off-chain. The standard is widely supported by the Ethereum and Solana ecosystems. Authentication works by asking the Web3 wallet application to sign a predefined message with the user's wallet, which is then parsed by both the wallet application and Supabase Auth to verify its validity and purpose before creating a user account or session.
Confirm Email configuration behavior
When Confirm Email is disabled, the user's email does not need to be verified to login and is implicitly confirmed in the database. This configuration option is found in the email provider under provider-specific configuration.
General configuration options overview
Supabase Auth general configuration controls user access to an application. Key configuration options include: Allow new users to sign up (enables user registration; if disabled, only existing users can sign in), Confirm Email (requires users to verify email before first sign-in; when disabled, email verification is not required and email is implicitly confirmed in the database), Allow anonymous sign-ins (permits creation of anonymous users), and Allow manual linking (allows users to link accounts manually).
Model Context Protocol (MCP) support for OAuth
Supabase Auth supports Model Context Protocol (MCP) for authenticating AI agents and LLM tools. The protocol provides automatic OAuth discovery and client registration for AI applications.
OAuth 2.1 authorization code flow with PKCE
Supabase Auth implements the OAuth 2.1 authorization code flow with PKCE (Proof Key for Code Exchange). The flow works as follows: (1) the application redirects the user to the authorization endpoint, (2) Supabase Auth validates the request and redirects to a custom authorization UI, (3) the user authenticates using any enabled auth method and approves access, (4) Supabase Auth issues an authorization code, (5) the application exchanges the code for access and refresh tokens, (6) the application uses the access token to make authenticated API requests.
View detailed SAML provider information
To see all information about a specific SAML provider, run: supabase sso show <provider-id> --project-ref <your-project>. Use the -o json flag to output as JSON.
Update SAML identity provider configuration
You can update SAML provider settings using: supabase sso update <provider-id> --project-ref <your-project>. This is necessary when cryptographic keys are rotated, metadata URLs change, domains change, or attribute mappings change. The unique SAML EntityID cannot be changed; if it changes, the provider must be registered as a new connection.
Add SAML identity provider via CLI with metadata file
To register a SAML 2.0 identity provider with a metadata XML file, run: supabase sso add --type saml --project-ref <your-project> --metadata-file /path/to/saml/metadata.xml --domains company.com
SAML SSO sessions may have maximum duration
Depending on the configuration of the identity provider, a login session established with SAML SSO may forcibly log out a user after a certain period of time.
SAML SSO email addresses are not unique identifiers
Given the behavior with no identity linking in SAML SSO, email addresses are no longer a unique identifier for a user account. Always use the user's UUID to correctly reference user accounts.
SAML email attribute requirement
Supabase Auth requires that an email address is present in the SAML assertion. At this time it is not possible to have users without an email address, so SAML assertions without one will be rejected.
SAML identity linking not supported
User accounts created via SAML SSO are not eligible for identity linking to existing user accounts for security reasons. If a user with email valid.email@supabase.io signed up with a password and then uses their company SAML SSO login, there will be two valid.email@supabase.io user accounts in the system.
SAML attribute mapping: default values
You can specify a default value for an attribute key that may be missing in the SAML assertion. For example: {"keys": {"custom_claim": {"name": "custom_claim", "default": 123}}}.
SAML attribute mapping: array values
If a SAML assertion contains multiple values for a key (such as groups), only the first one is picked up by default. To capture all values as an array, mark the key with "array": true. For example: {"keys": {"groups": {"name": "groups", "array": true}}} will result in {"groups": ["group-a", "group-b", "group-c"]}.
SAML attribute mapping result in user identity
Attributes mapped from SAML assertions appear in two places: in the access token (JWT) of the user, and in the auth.identities table under the identity_data JSON column. Identities created for SSO providers have 'sso:<uuid-of-provider>' in the provider column, while id contains the unique NameID of the user account. The same data also appears under raw_user_meta_data in auth.users.
SAML attribute mapping basic example
Attribute mapping is configured with a JSON structure. For example, to map email and first_name, use: {"keys": {"email": {"name": "mail"}, "first_name": {"name": "givenName"}}}. When a SAML assertion contains attributes with names 'mail' and 'givenName', they are mapped to 'email' and 'first_name' claims respectively.
SAML 2.0 support requires Pro plan or above
SAML 2.0 support is offered on plans Pro and above. SAML 2.0 support is disabled by default on Supabase projects and must be enabled via the Auth Providers page in the dashboard.
JavaScript signInWithSSO example
import { createClient } from '@supabase/supabase-js'
const supabase = createClient('https://your-project-id.supabase.co', 'sb_publishable_...')
supabase.auth.signInWithSSO({
domain: 'company.com',
})
Calling signInWithSSO starts the sign-in process using the identity provider registered for the domain name. It is not required that identity providers be assigned domain names, in which case you can use the provider's unique ID instead.
SAML sign-in flow: Identity Provider Initiated (IdP-initiated)
Users can sign in to a Supabase project by clicking on an icon in the application menu on the company intranet or identity provider page (IdP-initiated flow). This allows users to access the application directly from their identity provider without needing to go through the application's sign-in interface.
SAML Single Logout (SLO) not currently supported
Single Logout (SLO) is not supported at this time with Supabase Auth as it is a rarely supported feature by identity providers. The URL is registered and advertised for when this becomes available. Supabase recommends using Session Timebox or Session Inactivity Timeout to force end-users to authenticate regularly.
SAML sign-in flow: Service Provider Initiated (SP-initiated)
To initiate a sign-in request from your application's user interface (SP-initiated flow), use the signInWithSSO method with a domain name or provider ID.
SAML metadata URL vs file support by provider
Commonly used SAML 2.0 identity providers that support Metadata URLs include Okta, Azure AD (Microsoft Entra), and PingIdentity. Commonly used SAML 2.0 identity providers that only support Metadata XML files include Google Workspaces (G Suite) and any self-hosted or on-prem identity provider behind a VPN.
SAML 2.0 identity providers supported
Supabase Auth supports enterprise-level Single Sign-On (SSO) for any identity providers compatible with the SAML 2.0 protocol. Commonly supported identity providers include Google Workspaces (formerly G Suite), Okta, Auth0, Microsoft Active Directory, Azure Active Directory, Microsoft Entra, PingIdentity, and OneLogin.
SAML attribute mapping: multiple names fallback
If a SAML assertion may expose the same attribute under different names for different users, specify multiple names to look up. These are checked in order until a value is found. For example: {"keys": {"custom_claim": {"names": ["first-look-for-this-attribute", "then-this-one"]}}}.
Remove SAML identity provider connection
To remove a connection to a SAML identity provider, run: supabase sso remove <provider-id> --project-ref <your-project>. All user accounts from that identity provider will be immediately logged out. User information remains in the system but those accounts cannot be accessed in the future, even if the connection is added again.
Supabase SAML configuration URLs and EntityID
The following SAML configuration information is used to set up identity providers for a Supabase project, where <project> is replaced with the project reference: EntityID is https://<project>.supabase.co/auth/v1/sso/saml/metadata. Metadata URL is https://<project>.supabase.co/auth/v1/sso/saml/metadata. Metadata URL for download is https://<project>.supabase.co/auth/v1/sso/saml/metadata?download=true. ACS URL is https://<project>.supabase.co/auth/v1/sso/saml/acs. SLO URL is https://<project>.supabase.co/auth/v1/sso/slo. NameID must be emailAddress or persistent format.
Update SAML identity provider attribute mappings
To change the attribute mappings for an existing SAML provider, use: supabase sso update <provider-uuid> --project-ref <your-project> --attribute-mapping-file /path/to/attribute/mapping.json
List SAML identity providers
To view a list of all registered SAML identity providers, run: supabase sso list --project-ref <your-project>
SAML email attribute name lookup order
If a SAML assertion does not explicitly contain an email attribute, Supabase Auth inspects the following attribute names in order: urn:oid:0.9.2342.19200300.100.1.3, http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, http://schemas.xmlsoap.org/claims/EmailAddress, mail, email. If none of these exist, it will use the SAML NameID value but only if the format is advertised as urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress.