OAuth Provider Setup

AuthProxy supports authentication via seven OAuth/social login providers (Google, Telegram, Discord, Apple, Facebook, GitHub, VKontakte). Each provider requires separate configuration with API credentials. Some providers support account linking (?link=true) — attaching a social account to an existing user session.

Supported Providers

Provider	LoginMethod flag	HTTP	Auth Method	Link	Endpoint
Google	Google (128)	GET	JWT validation	Yes	/auth/v1/social/google?token={jwt}
Telegram	Telegram (16)	GET	HMAC-SHA256 widget data	—	/auth/v1/social/telegram?...widget params...
Discord	Discord (256)	GET	OAuth 2.0 code exchange	Yes	/auth/v1/social/discord?code=&state=
Apple	Apple (16384)	POST	Sign In with Apple identity token	—	/auth/v1/social/apple?token=&state=
Facebook	Facebook (32768)	GET	OAuth 2.0 code exchange	Yes	/auth/v1/social/facebook?code=&state=
GitHub	Github (512)	GET	OAuth 2.0 code exchange	—	/auth/v1/social/github?code=&state=
VKontakte	Vk (1024)	GET	JWT validation	—	/auth/v1/social/vk?token=&state=

Google

Google authentication validates JWT tokens issued by Google's OAuth service.

Setup

1. Go to Google Cloud Console
2. Create or select a project
3. Navigate to APIs & Services > Credentials
4. Create an OAuth 2.0 Client ID (Web application)
5. Add authorized redirect URIs: https://yourdomain.com/auth/v1/social/google

Configuration

{
  "Config": {
    "GoogleOauthSettings": {
      "ClientId": "your-client-id.apps.googleusercontent.com",
      "ClientSecret": "your-client-secret",
      "RedirectUri": "https://yourdomain.com/auth/v1/social/google"
    }
  }
}

How it works: AuthProxy validates the Google JWT token using Google's public certificates (automatically cached and refreshed).

Telegram

Telegram authentication uses the Telegram Login Widget and Telegram Mini App WebApp data.

Setup

1. Create a bot via @BotFather
2. Use /setdomain to set the bot's allowed domain

Configuration

{
  "TelegramBot": "your-bot-token-from-botfather"
}

How it works: AuthProxy verifies the HMAC-SHA256 signature of the Telegram widget data using the bot token hash. Also supports Telegram Mini App WebApp.initData validation.

Two authentication modes

• Login Widget — user clicks "Log in with Telegram" button on the web page
• Mini App — Telegram opens the PWA as a Mini App, passing WebApp.initData

Discord

Discord authentication uses the standard OAuth 2.0 authorization code flow.

Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Navigate to OAuth2 section
4. Add redirect: https://yourdomain.com/auth/v1/social/discord
5. Copy Client ID and Client Secret

Configuration

{
  "Config": {
    "DiscordOauthSettings": {
      "ClientId": "your-discord-client-id",
      "ClientSecret": "your-discord-client-secret",
      "RedirectPath": "/auth/v1/social/discord"
    }
  }
}

Note: Discord uses RedirectPath (not full URL). AuthProxy dynamically constructs the full redirect URI from the request domain. This enables multi-domain setups where the same AuthProxy instance serves multiple domains.

Scopes: identify email — retrieves user ID, username, discriminator, avatar, and email.

Apple

Apple Sign In uses POST-based authentication with Apple's identity token.

Setup

1. Go to Apple Developer > Certificates, Identifiers & Profiles
2. Register a Services ID for Sign In with Apple
3. Configure the domain and return URL
4. Create a private key for Sign In with Apple

Configuration

{
  "Config": {
    "AppleOauthSettings": {
      "ClientId": "com.yourdomain.service",
      "TeamId": "your-apple-team-id",
      "KeyId": "your-key-id",
      "PrivateKey": "your-private-key-contents"
    }
  }
}

How it works: The Apple endpoint accepts POST requests (unlike other providers which use GET). AuthProxy validates the Apple identity token and extracts the user's email and unique Apple ID.

note

Apple only sends the user's name on the first login. AuthProxy saves it during initial registration.

Facebook

Facebook authentication uses the standard OAuth 2.0 authorization code flow. Supports account linking (?link=true).

Setup

1. Go to Meta for Developers
2. Create a new app (Consumer type)
3. Add Facebook Login product
4. Set Valid OAuth Redirect URIs: https://yourdomain.com/auth/v1/social/facebook

Configuration

{
  "Config": {
    "FacebookOauthSettings": {
      "ClientId": "your-facebook-app-id",
      "ClientSecret": "your-facebook-app-secret",
      "RedirectUri": "https://yourdomain.com/auth/v1/social/facebook"
    }
  }
}

Scopes: email public_profile — retrieves user ID, name, and email.

GitHub

GitHub authentication uses OAuth 2.0.

Setup

1. Go to GitHub Developer Settings
2. Create a new OAuth App
3. Set authorization callback URL: https://yourdomain.com/auth/v1/social/github
4. Copy Client ID and Client Secret

Configuration

{
  "Config": {
    "GitHubOauthSettings": {
      "ClientId": "your-github-client-id",
      "ClientSecret": "your-github-client-secret",
      "RedirectUri": "https://yourdomain.com/auth/v1/social/github"
    }
  }
}

VKontakte (VK)

VK authentication uses JWT token validation.

Setup

1. Go to VK Developer
2. Create an application
3. Configure OAuth redirect URI

Configuration

{
  "Config": {
    "VkOauthSettings": {
      "ClientId": "your-vk-app-id",
      "ClientSecret": "your-vk-secret"
    }
  }
}

How it works: AuthProxy validates the VK JWT token using VK's public certificates.

User Matching

When a user logs in via OAuth, AuthProxy calls CRM resolution and returns one of social flow statuses:

result.status	Meaning	Client action
Success	Social identity is resolved and session is created.	Continue normal login redirect.
LinkConfirmationRequired	CRM found a matching local account by verified email/phone, but provider ext_id is not linked yet.	Open /login/social-link-confirm?token=... in browser with active target account session.
ManualLinkRequired	Automatic flow is blocked by policy or conflict guard.	Stop flow, show support/manual merge instruction.

confirmToken is returned in result.confirmToken (not in error.message), so continuation is an explicit business result.

Matching policy (ProxyAdmin)

/ProxyAdmin/Settings → Social Contact Match Policy (SettingType.FederatedContactMatchPolicy):

• ManualLinkOnly (default) — matching account requires explicit session-based link confirmation.
• AutoLinkVerified — verified contacts may be linked automatically (high-trust environments only).
• LookupOnlyCreateBlock — no auto-link and no new account creation when a matching contact exists.

Resolution sequence

When provider ext_id is not linked yet, CRM resolves in this order:

1. Extracts the external ID from the provider (Google sub, Telegram ID, Discord ID, etc.).
2. Looks up the user in CRM by provider ext_id.
3. If not found, checks verified email/phone candidates (provider-dependent trust). Existing CRM contacts are considered match candidates only when user_exid_flags.Verified is set.
4. Applies Social Contact Match Policy.
5. Creates session only for Success.

Unverified/manual contacts can block automatic linking, but they are not trusted as the target account for social matching.

All social logins are recorded in login_log; the login_type column stores the sequential LoginType enum (e.g. 8 Google, 9 Discord), not the LoginMethod bitmask.

Verified email matrix

Not all providers guarantee a verified email at the protocol level. The platform splits them by trustworthiness and only marks the resulting CRM email as verified for the providers in the left column:

Email considered verified	Email NOT considered verified
Google	Facebook
Apple	VKontakte
GitHub	Telegram
Discord (only when provider returns verified = true)	—

When a provider cannot prove email verification (right column), the user must complete an OTP confirmation on email separately before the contact ends up with user_exid_flags.Verified set. See Verified Contacts for the full flag semantics and the operator-side "Mark verified" workflow.

Telegram bot confirmation

The Telegram bot uses the same CRM resolution policy as browser social login:

• If Telegram id already owns a CRM account, a shared own contact phone or confirmed email is attached/promoted as Verified.
• If phone/email belongs to another verified CRM account, CRM returns LinkConfirmationRequired or ManualLinkRequired according to the policy.
• Telegram phone is accepted as verified only when Telegram marks the shared contact as the current user (contact.UserId == telegram id). Address-book contacts are rejected.
• Email confirmation codes are bound to the Telegram user that initiated the flow; another Telegram user cannot paste the code to complete the link.

Enabling/Disabling Providers

Providers are automatically enabled when their configuration is present in appsettings.json. To disable a provider, remove or comment out its configuration section.

The get_info endpoint (/auth/v1/get_info) returns the list of currently enabled authentication methods, which PWA frontends use to show/hide login buttons.