vasceannie/nhost
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): added instructions for oauth2 sign in (#3701)

Browse Source
This commit is contained in:
David Barroso
2025-11-17 10:06:25 +01:00
committed by GitHub
parent 9dab347348
commit 4e9de6a764
17 changed files with 260 additions and 164 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/docs.json
View File

@@ -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",

12
docs/products/auth/providers/sign-in-apple.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-azuread.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

11
docs/products/auth/providers/sign-in-bitbucket.mdx
View File

@@ -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",
});
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-discord.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-entraid.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-facebook.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-github.mdx
View File

@@ -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",
});
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-gitlab.mdx
View File

@@ -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",
});
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-google.mdx
View File

@@ -66,14 +66,4 @@ icon: google
## Sign In Users
Use the Nhost JavaScript client to sign in users:
```js
nhost.auth.signIn({
provider: 'google'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-linkedin.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

244
docs/products/auth/providers/sign-in-provider.mdx Normal file
View File

@@ -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<br/>Create/update user<br/>Generate refresh token
NhostAuth->>Client: 302 Redirect to redirectTo URL
Note over Client: URL contains refreshToken<br/>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<string>('');
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<ErrorResponse>;
if (!isMounted) return;
setStatus('error');
setError(`An error occurred during verification: ${error.message}`);
}
}
processToken();
return () => {
isMounted = false;
};
}, [location.search, navigate]);
return (
<div>
{status === 'verifying' && <p>Verifying...</p>}
{status === 'success' && <p>Successfully verified! Redirecting...</p>}
{status === 'error' && (
<div>
<p>Verification failed: {error}</p>
<button onClick={() => navigate('/signin')}>Back to Sign In</button>
</div>
)}
</div>
);
}
```
#### 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

12
docs/products/auth/providers/sign-in-spotify.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-strava.mdx
View File

@@ -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",
});
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-twitch.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-windowslive.mdx
View File

@@ -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",
});
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.

12
docs/products/auth/providers/sign-in-workos.mdx
View File

@@ -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'
})
```
<Note>
To use your own domain for the callback URL refer to the [custom domains](/platform/cloud/custom-domains) documentation.
</Note>
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.