# Social Authentication (OAuth) {#social-authentication-oauth}


Ever Gauzy supports social login via OAuth 2.0 with multiple providers. This allows users to sign in using their existing accounts.


## Supported Providers {#supported-providers}


| Provider      | Strategy                   | Environment Variable Prefix |
| ------------- | -------------------------- | --------------------------- |
| **Google**    | `passport-google-oauth20`  | `GOOGLE_`                   |
| **GitHub**    | `passport-github2`         | `GITHUB_`                   |
| **Facebook**  | `passport-facebook`        | `FACEBOOK_`                 |
| **Twitter**   | `passport-twitter`         | `TWITTER_`                  |
| **LinkedIn**  | `passport-linkedin-oauth2` | `LINKEDIN_`                 |
| **Microsoft** | `passport-microsoft`       | `MICROSOFT_`                |


## OAuth Flow {#oauth-flow}






```mermaid
graph TB
    A["User clicks 'Sign in with Google'"] --> B["Redirect to Google<br/>/api/auth/google"]
    B --> C["Google shows consent screen"]
    C -- "User approves" --> D["Google redirects to callback URL<br/>/api/auth/google/callback?code=xxx"]
    D --> E["Server exchanges code for tokens<br/>Fetches user profile from Google<br/>Creates or links user account<br/>Issues JWT tokens"]
    E --> F["Redirect to frontend with JWT tokens<br/>{baseUrl}/#/sign-in/success?jwt=xxx"]
```






## Configuration {#configuration}



### Google OAuth {#google-oauth}


1. Go to [Google Cloud Console](https://console.cloud.google.com)
2. Create/select a project
3. Navigate to **APIs & Services → Credentials**
4. Create **OAuth 2.0 Client ID**
5. Add authorized redirect URIs: `http://localhost:3000/api/auth/google/callback`

```bash
# .env
GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3000/api/auth/google/callback
```


### GitHub OAuth {#github-oauth}


1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Create a new **OAuth App**
3. Set callback URL: `http://localhost:3000/api/auth/github/callback`

```bash
# .env
GAUZY_GITHUB_OAUTH_CLIENT_ID=your-github-client-id
GAUZY_GITHUB_OAUTH_CLIENT_SECRET=your-github-client-secret
GAUZY_GITHUB_OAUTH_CALLBACK_URL=http://localhost:3000/api/auth/github/callback
```


### Facebook OAuth {#facebook-oauth}


1. Go to [Facebook Developers](https://developers.facebook.com)
2. Create a new app
3. Add the **Facebook Login** product
4. Set redirect URI: `http://localhost:3000/api/auth/facebook/callback`

```bash
# .env
FACEBOOK_CLIENT_ID=your-facebook-app-id
FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
FACEBOOK_CALLBACK_URL=http://localhost:3000/api/auth/facebook/callback
FACEBOOK_GRAPH_VERSION=v6.0
```


### Twitter OAuth {#twitter-oauth}


```bash
# .env
TWITTER_CLIENT_ID=your-twitter-api-key
TWITTER_CLIENT_SECRET=your-twitter-api-secret
TWITTER_CALLBACK_URL=http://localhost:3000/api/auth/twitter/callback
```


### LinkedIn OAuth {#linkedin-oauth}


```bash
# .env
LINKEDIN_CLIENT_ID=your-linkedin-client-id
LINKEDIN_CLIENT_SECRET=your-linkedin-client-secret
LINKEDIN_CALLBACK_URL=http://localhost:3000/api/auth/linkedin/callback
```


### Microsoft OAuth {#microsoft-oauth}


```bash
# .env
MICROSOFT_CLIENT_ID=your-microsoft-app-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_CALLBACK_URL=http://localhost:3000/api/auth/microsoft/callback
MICROSOFT_RESOURCE=https://graph.microsoft.com
MICROSOFT_TENANT=common
```


## Feature Flags {#feature-flags}


Social login providers can be enabled/disabled:

```bash
# .env
FEATURE_SOCIAL_LOGIN_GOOGLE=true
FEATURE_SOCIAL_LOGIN_GITHUB=true
FEATURE_SOCIAL_LOGIN_FACEBOOK=true
FEATURE_SOCIAL_LOGIN_TWITTER=false
FEATURE_SOCIAL_LOGIN_LINKEDIN=true
FEATURE_SOCIAL_LOGIN_MICROSOFT=true
```


## User Linking {#user-linking}



### New User {#new-user}


If no account exists with the OAuth email:

1. A new User record is created
2. Profile picture from provider is stored
3. User is sent to the onboarding flow (create tenant)
4. JWT tokens are issued


### Existing User {#existing-user}


If an account with the OAuth email already exists:

1. The OAuth profile is linked to the existing user
2. JWT tokens are issued
3. User is redirected to the dashboard


## Callback URL Pattern {#callback-url-pattern}


All callback URLs follow the pattern:

```
{API_BASE_URL}/api/auth/{provider}/callback
```

| Environment    | Example                                          |
| -------------- | ------------------------------------------------ |
| **Local**      | `http://localhost:3000/api/auth/google/callback` |
| **Production** | `https://api.gauzy.co/api/auth/google/callback`  |



> [!IMPORTANT]
> **Important**
>
> Make sure the callback URLs in your provider console **exactly match** the URLs configured in `.env`.




## Frontend Integration {#frontend-integration}


The frontend triggers social login by navigating to the provider endpoint:

```typescript
// In Angular component
loginWithGoogle(): void {
  window.location.href = `${environment.apiBaseUrl}/api/auth/google`;
}
```

After successful authentication, the server redirects back to the frontend with JWT tokens as query parameters.


## Related Pages {#related-pages}


- [Auth Overview](https://sourcey-gauzy.pages.dev/authentication/auth-overview/index.md) — authentication architecture
- [JWT Authentication](https://sourcey-gauzy.pages.dev/authentication/jwt-authentication/index.md) — token management
- [Configuration](https://sourcey-gauzy.pages.dev/getting-started/configuration/index.md) — all environment variables