diff --git a/docs/docs.json b/docs/docs.json index 9b49a7138..aff97708b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -126,6 +126,7 @@ "icon": "at", "pages": [ "products/auth/providers/overview", + "products/auth/providers/sign-in-provider", "products/auth/providers/tokens", "products/auth/providers/connect", "products/auth/providers/idtokens", diff --git a/docs/products/auth/providers/sign-in-apple.mdx b/docs/products/auth/providers/sign-in-apple.mdx index a311eda44..72001656a 100644 --- a/docs/products/auth/providers/sign-in-apple.mdx +++ b/docs/products/auth/providers/sign-in-apple.mdx @@ -86,14 +86,4 @@ icon: apple ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'apple' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Apple as an OAuth provider in Nhost, you can sign in users using the Apple provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-azuread.mdx b/docs/products/auth/providers/sign-in-azuread.mdx index ff8defb05..9118eb811 100644 --- a/docs/products/auth/providers/sign-in-azuread.mdx +++ b/docs/products/auth/providers/sign-in-azuread.mdx @@ -36,14 +36,4 @@ Find the Redirect URL in your project settings -> Sign In Methods after enabling ## User Sign-In -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'azuread' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Azure AD as an OAuth provider in Nhost, you can sign in users using the Azure AD provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-bitbucket.mdx b/docs/products/auth/providers/sign-in-bitbucket.mdx index 5bcd91a03..fbe9934b2 100644 --- a/docs/products/auth/providers/sign-in-bitbucket.mdx +++ b/docs/products/auth/providers/sign-in-bitbucket.mdx @@ -39,13 +39,4 @@ Once saved, Bitbucket will show you a **Key (Client ID)** and a **Secret (Client ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users with Bitbucket: - -```js -nhost.auth.signIn({ - provider: "bitbucket", -}); - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Bitbucket as an OAuth provider in Nhost, you can sign in users using the Bitbucket provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-discord.mdx b/docs/products/auth/providers/sign-in-discord.mdx index ed36b4de9..5da327865 100644 --- a/docs/products/auth/providers/sign-in-discord.mdx +++ b/docs/products/auth/providers/sign-in-discord.mdx @@ -34,14 +34,4 @@ icon: discord ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'discord' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Discord as an OAuth provider in Nhost, you can sign in users using the Discord provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-entraid.mdx b/docs/products/auth/providers/sign-in-entraid.mdx index 9c0effbc7..03e5cda34 100644 --- a/docs/products/auth/providers/sign-in-entraid.mdx +++ b/docs/products/auth/providers/sign-in-entraid.mdx @@ -34,14 +34,4 @@ Find the Redirect URL in your project settings -> Sign In Methods after enabling ## User Sign-In -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'azuread' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Entra ID as an OAuth provider in Nhost, you can sign in users using the Entra ID provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-facebook.mdx b/docs/products/auth/providers/sign-in-facebook.mdx index 5c11b1a60..7467a39c6 100644 --- a/docs/products/auth/providers/sign-in-facebook.mdx +++ b/docs/products/auth/providers/sign-in-facebook.mdx @@ -57,14 +57,4 @@ To make sure we can fetch all user data (email, profile picture and name). For t ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'facebook' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Facebook as an OAuth provider in Nhost, you can sign in users using the Facebook provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-github.mdx b/docs/products/auth/providers/sign-in-github.mdx index 2a654c7c7..0a5f13992 100644 --- a/docs/products/auth/providers/sign-in-github.mdx +++ b/docs/products/auth/providers/sign-in-github.mdx @@ -42,14 +42,4 @@ icon: github ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: "github", -}); -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured GitHub as an OAuth provider in Nhost, you can sign in users using the GitHub provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-gitlab.mdx b/docs/products/auth/providers/sign-in-gitlab.mdx index efa764bc2..a9fe5396c 100644 --- a/docs/products/auth/providers/sign-in-gitlab.mdx +++ b/docs/products/auth/providers/sign-in-gitlab.mdx @@ -34,14 +34,4 @@ icon: gitlab ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: "gitlab", -}); -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured GitLab as an OAuth provider in Nhost, you can sign in users using the GitLab provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-google.mdx b/docs/products/auth/providers/sign-in-google.mdx index cbce57818..4d379d98c 100644 --- a/docs/products/auth/providers/sign-in-google.mdx +++ b/docs/products/auth/providers/sign-in-google.mdx @@ -66,14 +66,4 @@ icon: google ## Sign In Users -Use the Nhost JavaScript client to sign in users: - -```js -nhost.auth.signIn({ - provider: 'google' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Google as an OAuth provider in Nhost, you can sign in users using the Google provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-linkedin.mdx b/docs/products/auth/providers/sign-in-linkedin.mdx index 60ab37ac0..5332f1d70 100644 --- a/docs/products/auth/providers/sign-in-linkedin.mdx +++ b/docs/products/auth/providers/sign-in-linkedin.mdx @@ -57,14 +57,4 @@ icon: linkedin ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'linkedin' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured LinkedIn as an OAuth provider in Nhost, you can sign in users using the LinkedIn provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-provider.mdx b/docs/products/auth/providers/sign-in-provider.mdx new file mode 100644 index 000000000..fa1667e44 --- /dev/null +++ b/docs/products/auth/providers/sign-in-provider.mdx @@ -0,0 +1,244 @@ +--- +title: Sign In with OAuth Providers +description: Learn how OAuth provider sign-in works in Nhost and how to implement it in your application. +sidebarTitle: Sign In +icon: user +--- + +## Overview + +Nhost supports OAuth 2.0 authentication with various social providers including GitHub, Google, Apple, Discord, and more. This guide explains the OAuth sign-in flow and how to implement it in your application. + +## OAuth Sign-In Flow + +The OAuth authentication flow in Nhost involves several steps coordinating between your client application, Nhost Auth service, and the OAuth provider: + +```mermaid +sequenceDiagram + participant Client as Client Application + participant NhostAuth as Nhost Auth Service + participant Provider as OAuth Provider + + Client->>Client: User clicks "Sign in with Provider" + Client->>Client: Call nhost.auth.signInProviderURL(provider, options) + Client->>Client: Redirect to returned URL + + Client->>NhostAuth: GET /v1/signin/provider/{provider} + Note over NhostAuth: Generate OAuth state & store session + NhostAuth->>Provider: 302 Redirect to provider authorization + + Provider->>Provider: User authorizes application + Provider->>NhostAuth: 302 Callback with authorization code + Note over NhostAuth: Exchange code for tokens
Create/update user
Generate refresh token + + NhostAuth->>Client: 302 Redirect to redirectTo URL + Note over Client: URL contains refreshToken
or error information + + Client->>Client: Extract refreshToken from URL + Client->>NhostAuth: POST /v1/token with refreshToken + NhostAuth->>Client: Return session with accessToken + + Client->>Client: Store session & authenticate user +``` + +## Implementation Steps + +### 1. Generate the Provider Sign-In URL + +Use the `signInProviderURL()` method to generate the OAuth authorization URL. This method returns a URL that you'll redirect the user to: + +```tsx +import { nhost } from './lib/nhost'; + +const handleSocialSignIn = (provider: 'github' | 'google' | 'apple') => { + // Get the current origin to build the callback URL + const origin = window.location.origin; + const redirectUrl = `${origin}/verify`; + + // Generate the provider sign-in URL + const url = nhost.auth.signInProviderURL(provider, { + redirectTo: redirectUrl, + }); + + // Redirect the user to the OAuth provider + window.location.href = url; +}; +``` + +### 2. OAuth Provider Authorization + +When the user is redirected to the OAuth provider (e.g., GitHub, Google), they will: + +1. See a consent screen asking to authorize your application +2. Grant or deny permission to access their profile information +3. Be redirected back to Nhost Auth's callback URL + +### 3. Nhost Auth Callback Processing + +Nhost Auth receives the callback from the OAuth provider at `/v1/signin/provider/{provider}/callback` and performs the following: + +1. **Validates the OAuth state** to prevent CSRF attacks +2. **Exchanges the authorization code** for access and refresh tokens from the provider +3. **Fetches the user's profile** from the provider +4. **Creates or updates the user** in your Nhost database +5. **Generates a Nhost refresh token** for the session +6. **Redirects to your client application** at the `redirectTo` URL + +### 4. Handle the Redirect + +After successful authentication, Nhost redirects back to your `redirectTo` URL with query parameters. You need to handle two scenarios: + +#### Success - Extract the Refresh Token + +On success, the URL will contain a `refreshToken` parameter: + +``` +https://your-app.com/verify?refreshToken=abc123... +``` + +Extract this token and exchange it for a session: + +```tsx +import type { ErrorResponse } from '@nhost/nhost-js/auth'; +import type { FetchError } from '@nhost/nhost-js/fetch'; +import { useEffect, useState } from 'react'; +import { useNavigate, useLocation } from 'react-router-dom'; +import { nhost } from './lib/nhost'; + +export default function Verify() { + const navigate = useNavigate(); + const location = useLocation(); + const [status, setStatus] = useState<'verifying' | 'success' | 'error'>('verifying'); + const [error, setError] = useState(''); + + useEffect(() => { + const params = new URLSearchParams(location.search); + const refreshToken = params.get('refreshToken'); + + if (!refreshToken) { + setStatus('error'); + setError('No refresh token found in URL'); + return; + } + + let isMounted = true; + + async function processToken() { + try { + // Exchange refresh token for session + await nhost.auth.refreshToken({ refreshToken }); + + if (!isMounted) return; + + setStatus('success'); + + // Redirect to the application + setTimeout(() => { + if (isMounted) navigate('/profile'); + }, 1500); + } catch (err) { + const error = err as FetchError; + if (!isMounted) return; + + setStatus('error'); + setError(`An error occurred during verification: ${error.message}`); + } + } + + processToken(); + + return () => { + isMounted = false; + }; + }, [location.search, navigate]); + + return ( +
+ {status === 'verifying' &&

Verifying...

} + {status === 'success' &&

Successfully verified! Redirecting...

} + {status === 'error' && ( +
+

Verification failed: {error}

+ +
+ )} +
+ ); +} +``` + +#### Error - Handle Authentication Failure + +On error, the URL will contain error parameters: + +``` +https://your-app.com/verify?error=access_denied +``` + +You can handle these errors by checking for the `error` query parameter: + +```tsx +const params = new URLSearchParams(location.search); +const error = params.get('error'); + +if (error) { + // Handle error - redirect to sign-in page with error message + navigate(`/signin?error=${encodeURIComponent(error)}`); + return; +} +``` + +Common error scenarios include: +- User denied authorization at the OAuth provider +- Invalid OAuth request configuration +- Error from the OAuth provider +- Provider account already linked to another user + +### 5. Session Management + +Once you've exchanged the refresh token for a session, the Nhost SDK automatically manages: + +- **Access token** - Short-lived JWT for API requests (default: 15 minutes) +- **Refresh token** - Used to obtain new access tokens (default: 30 days) +- **Automatic token refresh** - The SDK refreshes tokens before expiration + +## Security Considerations + +### CSRF Protection + +Nhost automatically handles CSRF protection using the OAuth `state` parameter. Each sign-in request generates a unique state value that is validated during the callback. + +### Redirect URL Validation + +For security, Nhost validates that the `redirectTo` URL matches either your clientUrl or one of your configured allowed redirect URLs. Configure these in your Nhost project settings. + +### Custom Domains + +To use your own domain for the OAuth callback URL instead of the default Nhost domain, refer to the [custom domains](/platform/cloud/custom-domains) documentation. + +## Provider-Specific Setup + +Each OAuth provider requires specific configuration. Refer to the provider-specific guides for detailed setup instructions: + +- [Apple](/products/auth/providers/sign-in-apple) +- [Azure AD / Entra ID](/products/auth/providers/sign-in-azuread) +- [Bitbucket](/products/auth/providers/sign-in-bitbucket) +- [Discord](/products/auth/providers/sign-in-discord) +- [Facebook](/products/auth/providers/sign-in-facebook) +- [GitHub](/products/auth/providers/sign-in-github) +- [GitLab](/products/auth/providers/sign-in-gitlab) +- [Google](/products/auth/providers/sign-in-google) +- [LinkedIn](/products/auth/providers/sign-in-linkedin) +- [Spotify](/products/auth/providers/sign-in-spotify) +- [Strava](/products/auth/providers/sign-in-strava) +- [Twitch](/products/auth/providers/sign-in-twitch) +- [Windows Live](/products/auth/providers/sign-in-windowslive) +- [WorkOS](/products/auth/providers/sign-in-workos) + +## API Reference + +For detailed API documentation, see: + +- [signInProviderURL()](/reference/javascript/nhost-js/auth#signinproviderurl) in the JavaScript SDK reference +- [GET /v1/signin/provider/{ '{provider}' }](/reference/auth/get-signin-provider-{provider}) in the API reference +- [GET /v1/signin/provider/{ '{provider}' }/callback](/reference/auth/get-signin-provider-{provider}-callback) in the API reference diff --git a/docs/products/auth/providers/sign-in-spotify.mdx b/docs/products/auth/providers/sign-in-spotify.mdx index 2d64856bf..222de0331 100644 --- a/docs/products/auth/providers/sign-in-spotify.mdx +++ b/docs/products/auth/providers/sign-in-spotify.mdx @@ -42,14 +42,4 @@ icon: spotify ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'spotify' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Spotify as an OAuth provider in Nhost, you can sign in users using the Spotify provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-strava.mdx b/docs/products/auth/providers/sign-in-strava.mdx index 9e268a1ee..057ed8375 100644 --- a/docs/products/auth/providers/sign-in-strava.mdx +++ b/docs/products/auth/providers/sign-in-strava.mdx @@ -33,14 +33,4 @@ Due to Strava API updates, email is no longer returned and is intentionally left ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: "strava", -}); -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Strava as an OAuth provider in Nhost, you can sign in users using the Strava provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-twitch.mdx b/docs/products/auth/providers/sign-in-twitch.mdx index f63e84413..da01920be 100644 --- a/docs/products/auth/providers/sign-in-twitch.mdx +++ b/docs/products/auth/providers/sign-in-twitch.mdx @@ -36,14 +36,4 @@ icon: twitch ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'twitch' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured Twitch as an OAuth provider in Nhost, you can sign in users using the Twitch provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-windowslive.mdx b/docs/products/auth/providers/sign-in-windowslive.mdx index e354219ff..210e03c68 100644 --- a/docs/products/auth/providers/sign-in-windowslive.mdx +++ b/docs/products/auth/providers/sign-in-windowslive.mdx @@ -32,14 +32,4 @@ icon: windowslive ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: "windowslive", -}); -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured WindowsLive as an OAuth provider in Nhost, you can sign in users using the WindowsLive provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management. diff --git a/docs/products/auth/providers/sign-in-workos.mdx b/docs/products/auth/providers/sign-in-workos.mdx index f21a75364..8d37cfee9 100644 --- a/docs/products/auth/providers/sign-in-workos.mdx +++ b/docs/products/auth/providers/sign-in-workos.mdx @@ -56,14 +56,4 @@ See the [WorkOS documentation](https://workos.com/docs/) to learn more about how ## Sign In Users -Use the [Nhost JavaScript client](/reference/javascript) to sign in users: - -```js -nhost.auth.signIn({ - provider: 'workos' -}) -``` - - -To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation. - +Once you've configured WorkOS as an OAuth provider in Nhost, you can sign in users using the WorkOS provider. See the [OAuth Provider Sign-In Guide](/products/auth/providers/sign-in-provider) for detailed implementation instructions including the complete OAuth flow, error handling, and session management.