> 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.md).

# Social Auth

## What is Social Auth?

Social Auth enables third-party OAuth login inside your Natively app. Instead of building a custom authentication system, your users can sign in with an account they already have - Google, Facebook, Microsoft, KakaoTalk, or any other OAuth provider.

{% hint style="warning" %}
If your app offers any third-party login options, Apple requires you to also offer [Sign In with Apple](/natively-platform/features/social-auth/sign-in-with-apple.md) for your iOS app.
{% endhint %}

## How does it work?

When a user taps a social login button in your app, Natively intercepts the OAuth request and handles it outside the normal embedded browser flow. The exact behavior depends on the platform, provider, and OS version.

### iOS

Natively opens Apple's secure native authentication sheet ([ASWebAuthenticationSession](https://developer.apple.com/documentation/authenticationservices/aswebauthenticationsession)) to handle the OAuth flow. Before the sign-in page loads, iOS shows a system dialog asking the user to confirm they want to continue. Once confirmed, the sign-in page loads inside the sheet - the user signs in without fully leaving the app. Once authentication is complete, the provider [redirects](#redirect-url) back to your app to finish the sign-in.

{% hint style="danger" %}
For Social Auth to work correctly on iOS, your [AASA](/natively-platform/features/deep-links/universal-links.md#apple-app-site-association) file must include the `webcredentials` section. Without it, the native authentication sheet will not be triggered, and the authentication will fall back to the internal browser instead.
{% endhint %}

{% hint style="info" %}
Facebook on iOS is an exception - instead of the native session, Natively shows a notice asking the user to open the login page in an external browser. Cancelling reloads the current page. Confirming opens Facebook login externally, returning the user via [Deep Links](/natively-platform/features/deep-links.md) after authentication.
{% endhint %}

{% hint style="info" %}
If authentication fails or the user cancels it on iOS, Natively reloads the current page. It is not possible to intercept or handle these events in your web app.
{% endhint %}

### Android

Natively shows a Redirect notice asking the user to open the login page in the default browser. Cancelling reloads the current page. Confirming opens the login page in the device's default browser. Once authentication is complete, the provider [redirects](#redirect-url) back to your app to finish the sign-in.

{% hint style="info" %}
On Android 10 and older, the login page opens directly inside the embedded browser instead of the default browser. No dialog is shown. Natively adjusts the browser identification so the OAuth provider treats it as a regular mobile browser.
{% endhint %}

## Prerequisites 

{% hint style="success" %}
This feature requires the **Unlimited** or **Lifetime** plan. [See all plans](/getting-started/subscription-plans.md)
{% endhint %}

* [Deep Links](/natively-platform/features/deep-links.md) configured and working on both iOS and Android - required for the device to route the OAuth redirect back to your app.
* Your OAuth provider configured with the correct [Redirect URL](#redirect-url) before setting up Social Auth in the Natively Dashboard.

## Natively Dashboard Setup

{% hint style="danger" %}
[Deep Links](/natively-platform/features/deep-links.md) must be enabled and functioning correctly before setting up Social Auth. Without them, users cannot be redirected back to your app after authentication.
{% endhint %}

1. Open your Natively app dashboard and navigate to **Features** > **Social Auth**.
2. Toggle the feature to **Enabled**.
3. Enter your **Redirect URL** -  see [Redirect URL](#redirect-url) below for details.
4. *(Optional)* Add **Custom OAuth URLs** - see [Custom OAuth URLs](#custom-oauth-urls) below for details.
5. Click **Save**.
6. Rebuild your app(s).

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

### Redirect URL

The Redirect URL tells Natively which URL to watch for to know that authentication is complete. Once the OAuth provider finishes authenticating the user, it redirects to this URL carrying the authentication token. Natively detects this match, intercepts the redirect, and loads that final URL back into your mobile app, completing the sign-in.

{% hint style="warning" %}
The Redirect URL must exactly match the redirect URL configured on your OAuth provider's side (e.g. in Google Cloud Console). If they don't match, the provider will not redirect to the correct URL, and the authentication will fail.
{% endhint %}

{% hint style="warning" %}
The Redirect URL must be on the same domain as your [Deep Links](/natively-platform/features/deep-links.md) configuration. Deep Links are what allow the device to route the redirect back to your app instead of opening it as a normal web page. If the domains don't match, the user will not be redirected back to your app after authentication.
{% endhint %}

### Custom OAuth URLs

By default, Natively recognizes a set of built-in OAuth provider URLs: Google, Facebook, Microsoft, and KakaoTalk, and applies the native authentication flow to them automatically. Custom OAuth URLs allow you to expand this list with any additional OAuth provider your app uses.

When Natively detects a login URL that matches one of your custom entries, it applies the same authentication flow as for the built-in providers: native authentication sheet on iOS and an external browser on Android.

{% hint style="danger" %}
Do not add your own website or app domain to Custom OAuth URLs. Any link from your app to your own domain that matches a custom OAuth URL will trigger the redirect notice on Android or open a native authentication sheet on iOS instead of loading normally inside the app. Only add URLs that belong to the OAuth provider's authentication endpoints.
{% endhint %}

{% hint style="warning" %}
Custom OAuth URLs must include both a host and a path - for example `accounts.yourprovider.com/o/oauth2`. A domain alone without a path is not valid.
{% endhint %}

{% hint style="info" %}
Natively cannot verify whether a custom OAuth URL will work correctly with a given provider. Built-in providers like Google and Microsoft have been tested and verified. Custom providers should be tested thoroughly before releasing to users.
{% endhint %}

## Supported providers

Natively has built-in support for Google, Facebook, Microsoft, and KakaoTalk.

Any other OAuth provider can be added via [Custom OAuth URLs](#custom-oauth-urls). Note that unlisted providers are not guaranteed to work and should be tested thoroughly before releasing to users.

## Troubleshooting

<details>

<summary>Native authentication sheet not triggering on iOS, falls back to internal browser</summary>

Your AASA file is missing the `webcredentials` section, or it's not correctly formatted. Verify your file using the [Universal Links verification tools](/natively-platform/features/deep-links/universal-links.md#how-to-verify).

</details>

<details>

<summary>User is not redirected back to the app after authentication</summary>

Check the following:

* Redirect URL in Natively Dashboard matches the redirect URL configured on your OAuth provider's side exactly.
* Redirect URL domain matches your Universal Links Associated Domain.
* Deep Links are correctly configured and verified.
* App has been rebuilt after enabling Social Auth.

</details>

<details>

<summary>User stuck in browser, never returns to app</summary>

Most likely caused by a Redirect URL mismatch between Natively Dashboard and your OAuth provider configuration, or Universal Links not functioning correctly on the device.

</details>

<details>

<summary>User completes login but is not authenticated, or lands on the wrong page</summary>

On Android, the app may open even if the Redirect URL doesn't exactly match what Natively is watching for - Android Universal Links can still route the user back to the app, but the final URL loaded inside the app may not be the correct callback page, resulting in a failed or incomplete authentication.&#x20;

On iOS, this wouldn't happen - if the Redirect URL doesn't match, the app won't open at all.&#x20;

Verify that the Redirect URL in the Natively Dashboard exactly matches the callback URL configured in your OAuth provider and your web app.

</details>

<details>

<summary>Custom OAuth provider not working</summary>

Natively cannot guarantee untested providers. Verify your Custom OAuth URL includes both host and path, and confirm the provider's login flow doesn't significantly differ from standard OAuth redirect behavior.

</details>

<details>

<summary>Tapping a normal in-app link unexpectedly opens the native auth sheet or browser notice</summary>

A Custom OAuth URL includes a URL that matches your own website or app domain. Remove your own domain from Custom OAuth URLs - only OAuth provider authentication endpoints should be listed there.

</details>

<details>

<summary>Social Auth works after publishing, but fails in testing</summary>

Universal Links and Android App Links can be unreliable in development/testing builds, depending on how the app is installed and signed. They are expected to work reliably once the app is properly published to the App Store / Play Store. If you're seeing failures only in testing, verify your AASA file and assetlinks.json are correctly hosted and that the test build matches your production signing configuration.

</details>

<details>

<summary>Microsoft login fails for company/workspace accounts</summary>

Some Microsoft Workspace accounts have security settings that block login inside a WebView-based flow. The account administrator may need to adjust these settings.

</details>