> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/natively-platform/features/social-auth/google-oauth.md).

# Google OAuth

This guide walks you through configuring Natively [Social Auth](/natively-platform/features/social-auth.md) so that Sign in with Google works correctly inside your Natively app. It covers the general setup process using your own Google Cloud Console project, as well as platform-specific instructions for Lovable, Base44, and Replit.

## Prerequisites

* [Universal Links](/natively-platform/features/deep-links/universal-links.md) configured and working on both iOS and Android.
* [Google Cloud account](https://console.cloud.google.com) - only required if you're using your own Google Cloud OAuth credentials, or building a custom implementation.

{% hint style="warning" %}
If you're building with an AI-powered editor like Lovable, Base44, or Replit, skip ahead to [AI Agents Platform Setup](#ai-agents-platform-setup).
{% endhint %}

## General Setup

This section covers setting up Google OAuth from scratch using your own Google Cloud project - applicable to Bubble, custom implementations, or any platform not covered in the AI Agents Platform Setup section below.

{% hint style="warning" %}
This guide covers only the configuration of the Google Cloud Console and Natively Dashboard. Implementing the actual Sign in with Google button and logic on your website is your responsibility - refer to [Google's official OAuth documentation](https://developers.google.com/identity/protocols/oauth2) for that part.
{% endhint %}

### Google Cloud Console Configuration

#### Create a Google Cloud Project

If you don't already have a Google Cloud project, create one first:

1. Open [Google Cloud Console](https://console.cloud.google.com)
2. Click the project selector at the top and select **New Project**.
3. Enter a project name and click **Create**.

#### Configure OAuth Consent Screen

Before creating credentials, you need to configure the OAuth consent screen - this is what users see when they are asked to grant your app access to their Google account.

1. In the Google Cloud Console, navigate to **APIs & Services** > **OAuth consent screen**. In the opened window, click **Get Started**.
2. Fill in the required fields:
   1. **App name** - the name users will see on the consent screen.
   2. **User support email** - an email users can contact for support.
   3. **Audience** - select **External** as the user type.
   4. **Developer contact information** - your email address.
3. Click **Save and Continue** through the remaining steps.

#### Create OAuth Credentials

1. Navigate to the [Clients page](https://console.developers.google.com/auth/clients).
2. Click **Create Client**.
3. Select **Web application** as the application type.
4. Enter a name for your OAuth client.
5. *(Optional)* Under **Authorized JavaScript origins**, add your app's domain (e.g. `https://yourdomain.com`) - only required if your implementation makes OAuth requests directly from client-side JavaScript.
6. Under **Authorized redirect URIs**, add your app's redirect URL - see [Redirect URL](#redirect-url) below for the correct format.
7. Click **Create**.
8. Copy your **Client ID** and **Client Secret** - you will need these in your platform setup.

{% hint style="warning" %}
The **Client Secret** is only shown once at creation time, and the JSON file is your only way to retrieve it later. Download and store it securely before closing the dialog.
{% endhint %}

### Redirect URL

The Redirect URL is the URL your web app uses to handle the authentication token after the user successfully signs in with Google. It must match exactly what you configure in your Google Cloud OAuth client's Authorized redirect URLs - for example `https://yourdomain.com/auth/callback`.

{% hint style="warning" %}
Google requires an exact match between the **Redirect URL** and the **Authorized redirect URI** in Google Cloud Console, including the scheme (`https`), trailing slashes, and path. Even a small mismatch will cause a `redirect_uri_mismatch` error from Google.
{% endhint %}

{% hint style="warning" %}
The Redirect URL must be on the same domain as your Universal Links configuration. If the domains don't match, the user will not be redirected back to your app after authentication.
{% endhint %}

### Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Social Auth**.
2. Enter your **Redirect URL** - the same value you added to **Authorized redirect URIs** in [Google Cloud Console](#create-oauth-credentials).
3. Click **Save**.
4. Rebuild your app(s).

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

{% hint style="info" %}
No **Custom OAuth URL** is needed for the general setup - Google is a built-in OAuth provider already recognized by Natively.
{% endhint %}

## AI Agents Platform Setup

{% hint style="warning" %}
This section documents how Google OAuth is currently configured on Base44, Lovable, and Replit, as of the time of writing. These platforms are not controlled by Natively, and their setup flows may change at any time. If something in this guide no longer matches what you see on your platform, check that platform's own documentation or support for the most current steps.
{% endhint %}

{% hint style="warning" %}
The steps below reflect the configuration that worked in our own test apps for each platform. Your app's authentication setup may differ - for example, if you've customized the login flow, added extra redirect logic, or modified how callbacks are handled. We recommend validating each redirect and callback in your own app before relying on this configuration, since we don't manage or know about your specific implementation.
{% endhint %}

{% tabs %}
{% tab title="Lovable" %}
Lovable offers two ways to set up Google sign-in: [**Managed by Lovable**](#managed-by-lovable), where Lovable handles the OAuth credentials for you, or [**Your own credentials**](#your-own-credentials), where you connect your own Google Cloud OAuth client. Both result in the same sign-in experience for your users - the difference is who manages the credentials and what branding appears on the consent screen.

### Managed by Lovable

This is the default and simplest option - no Google Cloud Console setup required.

{% stepper %}
{% step %}

#### Set up and test Google Sign-In on your website

Before connecting Google OAuth to Natively, make sure Google sign-in works correctly on your website first. Follow [Lovable's official guide](https://docs.lovable.dev/features/google-auth) to enable Google authentication. Test the flow on your live website - sign in and sign out - to confirm it works before continuing.
{% endstep %}

{% step %}

#### Set a custom Redirect URL (callback)

By default, Lovable redirects users back to your app's root URL after sign-in. For Natively to correctly detect when authentication is complete, you need a dedicated callback URL.

Ask Lovable:

```
Set my Google sign-in to use a custom redirect URL of window.location.origin + '/auth/callback' and create a matching /auth/callback page that finalizes the session and navigates to /
```

{% hint style="info" %}
`/auth/callback` is just an example path. You can use any path you'd like, as long as it matches exactly between your Lovable app and the Redirect URL you configure in the Natively Dashboard in the next step.
{% endhint %}

Test again on your live website to confirm sign-in still works correctly with the new callback.
{% endstep %}

{% step %}

#### Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Social Auth**.
2. Enter your **Redirect URL** - must exactly match the callback path you configured in Step 2.
3. Add to **Custom OAuth URLs**:  `oauth.lovable.app/initiate` .
4. Click **Save**.
5. Rebuild your app(s).

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

{% hint style="danger" %}
The **Custom OAuth URL** must be entered exactly as provided. Any difference in the path will prevent Natively from correctly detecting Lovable's Google sign-in flow.
{% endhint %}
{% endstep %}
{% endstepper %}

### Your own credentials

Use this option if you need full control over the consent screen branding or have specific compliance requirements. Requires a [Google Cloud Console configuration](#google-cloud-console-configuration).

{% stepper %}
{% step %}

#### Google Cloud OAuth configuration

1. Set up your [Google Cloud OAuth credentials](#create-oauth-credentials). 
2. The Authorized Redirect URI to add in Google Cloud Console is `https://oauth.lovable.app/callback`.
   {% endstep %}

{% step %}

#### Lovable project configuration

In your Lovable project:

1. Go to **More** > **Cloud** > **Users** > **Auth** > **Google**.
2. Select **Your own credentials**.
3. Enter your **Client ID** and **Client secret** from Google Cloud Console.
4. Under **Redirect URL(s)**, check **only** `https://oauth.lovable.app/callback` , leave `https://{yourdomain}/~oauth/callback` **unchecked**.
5. **Save** the changes.
   {% endstep %}

{% step %}

#### Natively Dashboard setup

Follow the same Steps 1-3 from the [Managed by Lovable](#managed-by-lovable) section to set up and test Google Sign-In, set a custom [Redirect URL](#set-a-custom-redirect-url-callback), and configure the [Natively Dashboard](#natively-dashboard-setup-1). 
{% endstep %}
{% endstepper %}

{% hint style="danger" %}
Selecting **both** checkboxes, or selecting **only** your app's own domain, will cause authentication to fail. **Only** `https://oauth.lovable.app/callback` should be checked.
{% endhint %}

### Testing

After completing the setup above, you need to test Google Sign-In on a real device. If sign-in doesn't work as expected, see the [Troubleshooting](#troubleshooting) section below, or the [Social Auth Troubleshooting](/natively-platform/features/social-auth.md#troubleshooting) section for issues related to the overall sign-in flow.
{% endtab %}

{% tab title="Base44" %}
Base44 offers two ways to set up Google sign-in: [**Default Base44 OAuth**](#default-base44-oauth), which uses Base44's own credentials, or [**Custom OAuth from Google Console**](#custom-oauth-from-google-console), where you connect your own Google Cloud OAuth client. Both result in the same sign-in experience for your users - the difference is who manages the credentials and what branding appears on the consent screen.

### Default Base44 OAuth

This is the default and simplest option - no Google Cloud Console setup required.

{% stepper %}
{% step %}

#### Set up and test Google Sign-In on your website

Before connecting Google OAuth to Natively, make sure Google sign-in works correctly on your website first. Follow [Base44's official guide](https://docs.base44.com/Setting-up-your-app/Managing-login-and-registration#customizing-the-google-login) to enable Google authentication. Test the flow on your live website - sign in and sign out - to confirm it works before continuing.
{% endstep %}

{% step %}

#### Set a custom Redirect URL (callback)

By default, Base44 may redirect users back to your app's root URL after sign-in, or use an internal flow that doesn't support a custom callback. For Natively to correctly detect when authentication is complete, you need a dedicated callback URL.

Ask Base44:

```
Set my Google sign-in to use a custom redirect URL of window.location.origin + '/auth/callback' and create a matching /auth/callback page that finalizes the session and navigates to /
```

{% hint style="info" %}
`/auth/callback` is just an example path. You can use any path you'd like, as long as it matches exactly between your Base44 app and the Redirect URL you configure in the Natively Dashboard in the next step.
{% endhint %}

Test again on your live website to confirm sign-in still works correctly with the new callback.
{% endstep %}

{% step %}

#### Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Social Auth**.
2. Enter your **Redirect URL** - must exactly match the callback path you configured in Step 2.
3. Add to **Custom OAuth URLs**:  `app.base44.com/api/apps/auth/login` .
4. Click **Save**.
5. Rebuild your app(s).

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

{% hint style="danger" %}
The **Custom OAuth URL** must be entered exactly as provided. Any difference in the path will prevent Natively from correctly detecting Base44's Google sign-in flow.
{% endhint %}
{% endstep %}
{% endstepper %}

### Custom OAuth from Google Console

{% hint style="info" %}
Custom OAuth from Google Console is only available on Base44's **Builder** plan or higher.
{% endhint %}

Use this option if you need full control over the consent screen branding or have specific compliance requirements. Requires a [Google Cloud Console configuration](#google-cloud-console-configuration).

{% stepper %}
{% step %}

#### Google Cloud OAuth configuration

1. Set up your [Google Cloud OAuth credentials](#create-oauth-credentials). 
2. The Authorized Redirect URI to add in Google Cloud Console is `https://app.base44.com/api/apps/auth/callback`.
   {% endstep %}

{% step %}

#### Base44 project configuration

In your Base44 project:

1. Go to **Dashboard** > **Settings** > **Authentication** > **Google authentication**.
2. **Select Use a custom OAuth from Google Console.**
3. Enter your **Client ID** and **Client secret** from Google Cloud Console.
4. Click **Update** to save the changes.
   {% endstep %}

{% step %}

#### Natively Dashboard setup

Follow the same Steps 1-3 from the [Default Base44 OAuth](#default-base44-oauth) section to set up and test Google Sign-In, set a custom [Redirect URL](#set-a-custom-redirect-url-callback-1), and configure the [Natively Dashboard](#natively-dashboard-setup-3). 
{% endstep %}
{% endstepper %}

### Testing

After completing the setup above, you need to test Google Sign-In on a real device. If sign-in doesn't work as expected, see the [Troubleshooting](#troubleshooting) section below, or the [Social Auth Troubleshooting](/natively-platform/features/social-auth.md#troubleshooting) section for issues related to the overall sign-in flow.
{% endtab %}

{% tab title="Replit" %}
Replit uses [Clerk](https://clerk.com) to handle authentication, including Google sign-in. Replit offers two ways to set up Google sign-in: [**Replit-managed credentials**](#replit-managed-credentials), the default option, or [**Custom credentials**](#custom-credentials), where you connect your own Google Cloud OAuth client. Both result in the same sign-in experience for your users - the difference is who manages the credentials and what branding appears on the consent screen.

### Replit-managed credentials

This is the default and simplest option - no Google Cloud Console setup required.

{% stepper %}
{% step %}

#### Set up and test Google Sign-In on your website

Before connecting Google OAuth to Natively, make sure Google sign-in works correctly on your website first. Follow [Replit's official guide](https://docs.replit.com/references/auth-and-identity/google) to enable Google authentication. Test the flow on your live website - sign in and sign out - to confirm it works before continuing.
{% endstep %}

{% step %}

#### Set a custom Redirect URL (callback)

By default, Replit may redirect users back to your app's root URL after sign-in. For Natively to correctly detect when authentication is complete, you need a dedicated callback URL.

Ask Replit:

```
Set my Google sign-in to use a custom redirect URL of window.location.origin + '/auth/callback' and create a matching /auth/callback page that finalizes the session and navigates to /
```

{% hint style="info" %}
`/auth/callback` is just an example path. You can use any path you'd like, as long as it matches exactly between your Replit app and the Redirect URL you configure in the Natively Dashboard in the next step.
{% endhint %}

Test again on your live website to confirm sign-in still works correctly with the new callback.
{% endstep %}

{% step %}

#### Natively Dashboard Setup

1. Open your Natively app dashboard and navigate to **Features** > **Social Auth**.
2. Enter your **Redirect URL** - must exactly match the callback path you configured in Step 2.
3. Click **Save**.
4. Rebuild your app(s).

{% hint style="warning" %}
You must rebuild your app for these changes to take effect.
{% endhint %}

{% hint style="info" %}
No **Custom OAuth URL** is needed for Replit - the Google sign-in flow goes directly to Google and back to your app's domain without passing through an intermediate platform URL.
{% endhint %}
{% endstep %}
{% endstepper %}

### Custom credentials

{% hint style="warning" %}
Custom Google OAuth credentials in Replit are only available in the **Production** environment, not in development.
{% endhint %}

Use this option if you need full control over the consent screen branding or have specific compliance requirements. Requires a [Google Cloud Console configuration](#google-cloud-console-configuration).

{% stepper %}
{% step %}

#### Google Cloud OAuth configuration

1. Set up your [Google Cloud OAuth credentials](#create-oauth-credentials). 
2. You will need your Replit **Redirect callback URLs** and **JavaScript origins** values for this - see Step 2 below.
   {% endstep %}

{% step %}

#### Replit project configuration

In your Replit project:

1. Go to **Auth pane** > **Configure tab** > **SSO providers** > **Google**.
2. Select **Custom credentials.**
3. Enter your **Client ID** and **Client secret** from Google Cloud Console.
4. Under **Provider setup**, copy the values shown for **Redirect callback URLs** and **JavaScript origins**, and add them to your OAuth client's **Authorized redirect URIs** and **Authorized JavaScript origins** in Google Cloud Console.
5. Click **Mark all as done**.
6. Click **Save changes**.
   {% endstep %}

{% step %}

#### Natively Dashboard setup

Follow the same Steps 1-3 from the [Replit-managed credentials](#replit-managed-credentials) section to set up and test Google Sign-In, set a custom [Redirect URL](#set-a-custom-redirect-url-callback-2), and configure the [Natively Dashboard](#natively-dashboard-setup-6). 
{% endstep %}
{% endstepper %}

### Testing

After completing the setup above, you need to test Google Sign-In on a real device. If sign-in doesn't work as expected, see the [Troubleshooting](#troubleshooting) section below, or the [Social Auth Troubleshooting](/natively-platform/features/social-auth.md#troubleshooting) section for issues related to the overall sign-in flow.
{% endtab %}
{% endtabs %}

## Troubleshooting

<details>

<summary><code>disallowed_useragent</code> error from Google</summary>

Google blocks OAuth requests made from embedded browsers (WebView) for security reasons. If you see this error, it means the Google sign-in request is loading inside Natively's embedded browser (Internal Browser) instead of being intercepted and opened in the native authentication flow. Check whether your platform uses any intermediate redirect before reaching Google's OAuth screen (for example, `oauth.lovable.app/initiate` or `app.base44.com/api/apps/auth/login`), and make sure that the exact URL is added to Custom OAuth URLs in the Natively Dashboard.

</details>

<details>

<summary><code>redirect_uri_mismatch</code> error from Google</summary>

This error comes directly from Google and means the redirect URI your app is sending in the OAuth request doesn't match any of the Authorized redirect URIs registered in your Google Cloud OAuth client. This is unrelated to the Natively Dashboard configuration. Check your Google Cloud Console OAuth client and make sure the exact redirect URI being used (by your platform or website) is added, including the matching scheme (`http` vs `https`), trailing slashes, and path exactly.

</details>

<details>

<summary>User is stuck in the browser after signing in and never returns to the app</summary>

This usually means the Redirect URL Natively is watching for does not match the URL the OAuth provider is actually redirecting to. Double-check that the Redirect URL in the Natively Dashboard matches exactly what's configured on your platform and in Google Cloud Console.&#x20;

This can also happen if [Universal Links](/natively-platform/features/deep-links/universal-links.md) are not correctly configured, meaning that the app just cannot be opened when the website domain is triggered.

</details>

<details>

<summary>Sign-in works on the website but fails in the Natively app</summary>

There are many possible causes here: Universal Links misconfiguration, an incorrect Custom OAuth URL, or a Redirect URL mismatch. Rather than checking each setting individually, the most reliable approach is to trace the actual redirect chain your website's Google sign-in flow goes through (using a tool like a network inspector or a URL tracer), and compare each step against what's configured in the Natively Dashboard - Custom OAuth URLs should match any intermediate redirect domains, and Redirect URL should match the final destination URL exactly.

</details>

<details>

<summary>Google account picker is skipped; the user is signed in automatically</summary>

If your device has only one Google account signed in, Google may skip the account picker and sign in automatically without showing the consent screen. This has been observed when using your own Google Cloud credentials on Lovable, Base44, and Replit. This happens because the `prompt` parameter is not being passed by the platform's OAuth request. This is a platform-level behavior and cannot be managed from the Natively side.

</details>

<details>

<summary>Google Sign-in is not working in the Natively Preview app</summary>

Social Auth is not available in the Natively Preview app. Test the full sign-in flow on a real device using a full build instead.

</details>

<details>

<summary>System dialog shows the platform's domain instead of Google (or another OAuth provider)</summary>

On iOS, the native authentication sheet displays a system dialog like *"'\[Your App]' Wants to Use '\[domain]' to Sign In"* before the sign-in page loads. Even though you've configured Google (or another provider) for sign-in, this dialog may show a different domain instead - for example `app.base44.com` rather than anything related to Google. This happens because platforms like Base44 and Lovable redirect through their own domain before reaching Google, and Natively's native authentication sheet reflects the first domain it intercepts, not the final OAuth provider. This is expected behavior and cannot be changed, as it depends entirely on how the platform structures its OAuth redirects.

</details>