Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(signup): skip in-app onboarding for oauth connector signups (#118850)

Rafael Audibert35cd2a53c3c4
diff --git a/docs/published/handbook/engineering/oauth-development-guide.md b/docs/published/handbook/engineering/oauth-development-guide.md
index 3effeb85dcf2..be12cc02a78b 100644
--- a/docs/published/handbook/engineering/oauth-development-guide.md
+++ b/docs/published/handbook/engineering/oauth-development-guide.md
@@ -352,6 +352,8 @@ The redirect also sets the `ph_pending_oauth_connection` cookie so those screens
- Cleared when the person grants or denies the authorization.
- A CIMD client seen for the first time has no application row yet, so the cookie carries the host of its `client_id` URL as the name.
+An account created while the cookie is present skips in-app onboarding. Signup sets `onboarding_skipped_reason` to `connector`, pinned to the signup organization, so another organization the person joins later still shows onboarding. A delegated invitee keeps onboarding, because running it is the reason for the invite.
+
While the cookie is present, the signup form pins the data region to the region the form is served from. An OAuth client is registered in one region only, so an account created in the other region could not finish the connection.
Analytics: the frontend captures `oauth pending connection viewed` with a `screen` property (`login`, `signup`, or `verify_email`). `user signed up` carries `signup_oauth_client_name` and `signup_oauth_client_id`, which are also set as person properties, so a signup can be traced back to the application that started it.
diff --git a/frontend/src/generated/core/api.schemas.ts b/frontend/src/generated/core/api.schemas.ts
index 605e1f06dc23..af757a952e4e 100644
--- a/frontend/src/generated/core/api.schemas.ts
+++ b/frontend/src/generated/core/api.schemas.ts
@@ -5976,6 +5976,7 @@ export const ShortcutPositionEnumApi = {
* * `later` - Skipped for later
* * `other` - Other
* * `provisioned` - Account provisioned by a partner
+ * * `connector` - Signed up through an OAuth connector
*/
export type OnboardingSkippedReasonEnumApi =
(typeof OnboardingSkippedReasonEnumApi)[keyof typeof OnboardingSkippedReasonEnumApi]
@@ -5985,6 +5986,7 @@ export const OnboardingSkippedReasonEnumApi = {
Later: 'later',
Other: 'other',
Provisioned: 'provisioned',
+ Connector: 'connector',
} as const
/**
diff --git a/frontend/src/types.ts b/frontend/src/types.ts
index 835f2d53e6ce..ca4edd702467 100644
--- a/frontend/src/types.ts
+++ b/frontend/src/types.ts
@@ -389,7 +389,7 @@ export type UserShortcutPosition = 'above' | 'below' | 'hidden'
// Mirrors posthog.models.user.OnboardingSkippedReason. Kept as a union here to avoid a
// hard dependency on generated types; when adopting generated `UserApi`, switch to
// `OnboardingSkippedReasonEnumApi` from `~/generated/core/api.schemas`.
-export type OnboardingSkippedReason = 'delegated' | 'later' | 'other' | 'provisioned' | null
+export type OnboardingSkippedReason = 'delegated' | 'later' | 'other' | 'provisioned' | 'connector' | null
/** Full User model. */
export interface UserType extends UserBaseType {
diff --git a/posthog/api/signup.py b/posthog/api/signup.py
index d7fc258537ec..dfa2bcb95646 100644
--- a/posthog/api/signup.py
+++ b/posthog/api/signup.py
@@ -35,7 +35,10 @@ from posthog.email import is_email_available
from posthog.event_usage import alias_invite_id, report_user_joined_organization, report_user_signed_up
from posthog.exceptions_capture import capture_exception
from posthog.helpers.email_utils import EmailValidationHelper, reject_plus_addressed_email, validate_display_name
-from posthog.helpers.oauth_pending_connection import read_pending_oauth_connection
+from posthog.helpers.oauth_pending_connection import (
+ apply_connector_signup_onboarding_skip,
+ read_pending_oauth_connection,
+)
from posthog.helpers.verified_domain_enforcement import resolve_login_organization
from posthog.models import (
InviteExpiredException,
@@ -72,6 +75,8 @@ SIGNUP_BLOCKED_DETAIL = (
f"and quote the code {SECURITY_REFUSAL_CODE}."
)
+DELEGATED_ONBOARDING_NEXT = "/onboarding"
+
def _save_session_with_recovery(session: SessionBase) -> None:
"""Persist session state and recover from missing-row session races."""
@@ -343,6 +348,9 @@ class SignupSerializer(serializers.Serializer):
_save_session_with_recovery(request.session)
user = self._user
+ oauth_connection = read_pending_oauth_connection(request)
+ if oauth_connection is not None:
+ apply_connector_signup_onboarding_skip(user, self._organization)
report_user_signed_up(
user,
@@ -355,7 +363,7 @@ class SignupSerializer(serializers.Serializer):
role_at_organization=role_at_organization,
referral_source=referral_source,
referral_source_ai_prompt=referral_source_ai_prompt,
- oauth_connection=read_pending_oauth_connection(request),
+ oauth_connection=oauth_connection,
)
# Fire-and-forget real-time enrichment for onboarding routing. Fully guarded and
@@ -723,6 +731,11 @@ class InviteSignupSerializer(serializers.Serializer):
user.save(update_fields=["credentials_reviewed_at"])
if is_new_user:
+ oauth_connection = read_pending_oauth_connection(request)
+ # A delegated invitee is the teammate asked to run onboarding, so they keep it.
+ if oauth_connection is not None and not is_delegation:
+ apply_connector_signup_onboarding_skip(user, invite.organization)
+
verify_email_or_login(self.context["request"], user)
report_user_signed_up(
@@ -734,7 +747,7 @@ class InviteSignupSerializer(serializers.Serializer):
user_analytics_metadata=user.get_analytics_metadata(),
org_analytics_metadata=user.organization.get_analytics_metadata() if user.organization else None,
role_at_organization=role_at_organization,
- oauth_connection=read_pending_oauth_connection(request),
+ oauth_connection=oauth_connection,
referral_source="signed up from invite link",
)
@@ -975,7 +988,7 @@ def process_social_invite_signup(
invite.validate(user=user, email=email)
invite.use(user, prevalidated=True)
if is_delegation:
- strategy.session_set("next", "/onboarding")
+ strategy.session_set("next", DELEGATED_ONBOARDING_NEXT)
return user
else:
invite.validate(user=None, email=email)
@@ -989,7 +1002,7 @@ def process_social_invite_signup(
raise ValidationError(message, code="unknown", params={"source": "social_create_user"})
if is_delegation:
- strategy.session_set("next", "/onboarding")
+ strategy.session_set("next", DELEGATED_ONBOARDING_NEXT)
return _user
@@ -1042,7 +1055,7 @@ def process_social_domain_jit_provisioning_signup(
raise ValidationError(message, code="unknown", params={"source": "social_create_user"})
if is_delegation:
- strategy.session_set("next", "/onboarding")
+ strategy.session_set("next", DELEGATED_ONBOARDING_NEXT)
except (OrganizationInvite.DoesNotExist, InviteExpiredException):
user = User.objects.create_and_join(
@@ -1222,6 +1235,12 @@ def social_create_user(
return redirect(f"/organization/confirm-creation?{query_params_string}")
+ oauth_connection = read_pending_oauth_connection(request)
+ # A delegated invitee is the teammate asked to run onboarding, so they keep it.
+ is_delegated_invitee = strategy.session_get("next") == DELEGATED_ONBOARDING_NEXT
+ if oauth_connection is not None and user.organization is not None and not is_delegated_invitee:
+ apply_connector_signup_onboarding_skip(user, user.organization)
+
report_user_signed_up(
user,
is_instance_first_user=User.objects.count() == 1,
@@ -1232,7 +1251,7 @@ def social_create_user(
user_analytics_metadata=user.get_analytics_metadata(),
org_analytics_metadata=user.organization.get_analytics_metadata() if user.organization else None,
referral_source="social signup - no info",
- oauth_connection=read_pending_oauth_connection(request),
+ oauth_connection=oauth_connection,
)
return {"is_new": True, "user": user}
diff --git a/posthog/api/test/test_signup.py b/posthog/api/test/test_signup.py
index f15cf0fbf0bc..e93a7646a886 100644
--- a/posthog/api/test/test_signup.py
+++ b/posthog/api/test/test_signup.py
@@ -1625,21 +1625,53 @@ class TestSignupAPI(APIBaseTest):
)
mock_email_verifier.assert_called_once_with(user)
+ @parameterized.expand(
+ [
+ ("plain_signup", "plain", True),
+ ("social_signup", "social", True),
+ ("invite_signup", "invite", True),
+ ("delegated_invite_signup", "delegated_invite", False),
+ ]
+ )
@patch("posthoganalytics.capture")
- def test_api_sign_up_reports_the_pending_oauth_connection(self, mock_capture):
+ def test_api_sign_up_reports_the_pending_oauth_connection(
+ self, _name: str, signup_path: str, expect_onboarding_skip: bool, mock_capture
+ ):
+ email = "[email protected]"
self.client.cookies[PENDING_OAUTH_CONNECTION_COOKIE] = PendingOAuthConnection(
client_name="Claude", client_id="https://claude.example.com/.well-known/oauth-client"
).to_cookie_value()
- response = self.client.post(
- "/api/signup/",
- {
- "first_name": "Jane",
- "email": "[email protected]",
- "password": VALID_TEST_PASSWORD,
- "role_at_organization": "product",
- },
- )
+ invite_organization: Optional[Organization] = None
+ if signup_path == "plain":
+ response = self.client.post(
+ "/api/signup/",
+ {
+ "first_name": "Jane",
+ "email": email,
+ "password": VALID_TEST_PASSWORD,
+ "role_at_organization": "product",
+ },
+ )
+ elif signup_path == "social":
+ session = self.client.session
+ session["backend"] = "google-oauth2"
+ session["email"] = email
+ session.save()
+ response = self.client.post(
+ "/api/social_signup/", {"first_name": "Jane", "organization_name": "Jane's Org"}
+ )
+ else:
+ invite_organization = Organization.objects.create(name="Invited Org")
+ Team.objects.create(organization=invite_organization)
+ invite = OrganizationInvite.objects.create(
+ target_email=email,
+ organization=invite_organization,
+ is_setup_delegation=signup_path == "delegated_invite",
+ )
+ response = self.client.post(
+ f"/api/signup/{invite.id}/", {"first_name": "Jane", "password": VALID_TEST_PASSWORD}
+ )
self.assertEqual(response.status_code, status.HTTP_201_CREATED)
signup_calls = [c for c in mock_capture.call_args_list if c.kwargs.get("event") == "user signed up"]
@@ -1648,6 +1680,17 @@ class TestSignupAPI(APIBaseTest):
self.assertEqual(properties["signup_oauth_client_id"], "https://claude.example.com/.well-known/oauth-client")
self.assertEqual(properties["$set"]["signup_oauth_client_name"], "Claude")
+ user = User.objects.get(email=email)
+ if expect_onboarding_skip:
+ self.assertIsNotNone(user.onboarding_skipped_at)
+ self.assertEqual(user.onboarding_skipped_reason, "connector")
+ expected_organization = invite_organization or user.organization
+ assert expected_organization is not None
+ self.assertEqual(user.onboarding_skipped_organization_id, expected_organization.id)
+ else:
+ self.assertIsNone(user.onboarding_skipped_at)
+ self.assertIsNone(user.onboarding_skipped_reason)
+
@pytest.mark.skip_on_multitenancy
@patch("posthog.utils.get_ip_address", return_value="192.168.1.100")
def test_signup_rate_limit_by_ip(self, mock_get_ip):
diff --git a/posthog/helpers/oauth_pending_connection.py b/posthog/helpers/oauth_pending_connection.py
index 4bbb796fec91..9de71b7dd805 100644
--- a/posthog/helpers/oauth_pending_connection.py
+++ b/posthog/helpers/oauth_pending_connection.py
@@ -11,11 +11,17 @@ holds public application metadata only: the same name and logo the consent scree
"""
import json
+from typing import TYPE_CHECKING
from urllib.parse import quote, unquote
from django.http import HttpRequest, HttpResponse
+from django.utils import timezone
from posthog.dataclasses import frozen
+from posthog.models.user import OnboardingSkippedReason
+
+if TYPE_CHECKING:
+ from posthog.models import Organization, User
PENDING_OAUTH_CONNECTION_COOKIE = "ph_pending_oauth_connection"
@@ -123,3 +129,19 @@ def clear_pending_oauth_connection_cookie(request: HttpRequest, response: HttpRe
def read_pending_oauth_connection(request: HttpRequest) -> PendingOAuthConnection | None:
return PendingOAuthConnection.from_cookie_value(request.COOKIES.get(PENDING_OAUTH_CONNECTION_COOKIE))
+
+
+def apply_connector_signup_onboarding_skip(user: "User", organization: "Organization") -> None:
+ """Keep an account created through an OAuth connector out of in-app onboarding.
+
+ The person starts from inside the connecting application and goes back to it after
+ consent, so they never see the onboarding flow the app would otherwise send them to.
+ The skip is pinned to the signup organization, so another organization the person
+ joins later still shows onboarding.
+ """
+ user.onboarding_skipped_at = timezone.now()
+ user.onboarding_skipped_reason = OnboardingSkippedReason.CONNECTOR
+ user.onboarding_skipped_organization_id = organization.id
+ user.save(
+ update_fields=["onboarding_skipped_at", "onboarding_skipped_reason", "onboarding_skipped_organization_id"]
+ )
diff --git a/posthog/migrations/1405_user_onboarding_skipped_reason_connector.py b/posthog/migrations/1405_user_onboarding_skipped_reason_connector.py
new file mode 100644
index 000000000000..c09f432f15a2
--- /dev/null
+++ b/posthog/migrations/1405_user_onboarding_skipped_reason_connector.py
@@ -0,0 +1,34 @@
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+ # choices live only in Django's state, so the database is left alone. A plain AlterField would
+ # emit no SQL either, but it reads as a lock on posthog_user, which is read on every request.
+
+ dependencies = [
+ ("posthog", "1404_organization_inactive_quota_index"),
+ ]
+
+ operations = [
+ migrations.SeparateDatabaseAndState(
+ state_operations=[
+ migrations.AlterField(
+ model_name="user",
+ name="onboarding_skipped_reason",
+ field=models.CharField(
+ blank=True,
+ choices=[
+ ("delegated", "Delegated to teammate"),
+ ("later", "Skipped for later"),
+ ("other", "Other"),
+ ("provisioned", "Account provisioned by a partner"),
+ ("connector", "Signed up through an OAuth connector"),
+ ],
+ max_length=32,
+ null=True,
+ ),
+ ),
+ ],
+ database_operations=[],
+ ),
+ ]
diff --git a/posthog/migrations/max_migration.txt b/posthog/migrations/max_migration.txt
index d7275626aff4..b0acb460d5cb 100644
--- a/posthog/migrations/max_migration.txt
+++ b/posthog/migrations/max_migration.txt
@@ -1 +1 @@
-1404_organization_inactive_quota_index
+1405_user_onboarding_skipped_reason_connector
diff --git a/posthog/models/user.py b/posthog/models/user.py
index 1e37be916292..d01a6d7fe011 100644
--- a/posthog/models/user.py
+++ b/posthog/models/user.py
@@ -233,6 +233,7 @@ class OnboardingSkippedReason(models.TextChoices):
LATER = "later", "Skipped for later"
OTHER = "other", "Other"
PROVISIONED = "provisioned", "Account provisioned by a partner"
+ CONNECTOR = "connector", "Signed up through an OAuth connector"
class OnboardingFlowVariant(models.TextChoices):
diff --git a/products/desktop/packages/api-client/src/generated.ts b/products/desktop/packages/api-client/src/generated.ts
index cce83222dfd1..720489e84d4b 100644
--- a/products/desktop/packages/api-client/src/generated.ts
+++ b/products/desktop/packages/api-client/src/generated.ts
@@ -16799,12 +16799,14 @@ export namespace Schemas {
* * `later` - Skipped for later
* * `other` - Other
* * `provisioned` - Account provisioned by a partner
+ * * `connector` - Signed up through an OAuth connector
*/
export type OnboardingSkippedReasonEnum =
| "delegated"
| "later"
| "other"
- | "provisioned";
+ | "provisioned"
+ | "connector";
/**
* * `1` - member
* * `8` - administrator
diff --git a/services/mcp/src/api/generated.ts b/services/mcp/src/api/generated.ts
index 3b990d4d6302..37f5411daebc 100644
--- a/services/mcp/src/api/generated.ts
+++ b/services/mcp/src/api/generated.ts
@@ -70795,6 +70795,7 @@ export namespace Schemas {
* * `later` - Skipped for later
* * `other` - Other
* * `provisioned` - Account provisioned by a partner
+ * * `connector` - Signed up through an OAuth connector
*/
export type OnboardingSkippedReasonEnum = typeof OnboardingSkippedReasonEnum[keyof typeof OnboardingSkippedReasonEnum];
@@ -70804,6 +70805,7 @@ export namespace Schemas {
Later: 'later',
Other: 'other',
Provisioned: 'provisioned',
+ Connector: 'connector',
} as const;
export interface OnlinePerformanceRow {