Sign in

Connect social media account (oauth 2.0)

A user (or Admin acting on a tenant-scoped brand account) connects a social-media account to the CRM via the provider's OAuth 2.0 + PKCE flow so the CRM can read mentions, send messages, and publish posts on their behalf.

When this happens: You go to Settings — Social Integration — Connect Account.

Step by step

  1. 1

    Go to Settings — Social Integration.

    Lists providers configured by Admin with their state (Not Connected / Connected / Requires Re-auth).

  2. 2

    Select LinkedIn — Connect.

    EasyCRM generates a PKCE code verifier + challenge and an anti-CSRF state value, stores them server-side, and redirects to the provider authorize endpoint with scope = read profile + post + DM + organization (only the scopes enabled by Admin).

  3. 3

    User signs in and grants consent. Redirects back to /api/integrations/social/callback?code=…&state=….

    EasyCRM checks state, exchanges the code for access + refresh tokens, encrypts both at rest (AES-256), and stores them on IntegrationConnection with. (or BrandAccountId for tenant scope). Calls the provider profile endpoint to verify connection. EasyCRM stores ExternalUserId, ExternalHandle, and ExternalDisplayName. Enqueues an initial profile-enrichment backfill job and a 7-day mention backfill so the timeline is not empty on first view. EasyCRM shows: Connected as @handle. Last sync: just now.

Other paths

Connect a tenant brand account

Settings — Social Integration — Brand Accounts — Add Brand Account. Same OAuth flow as Main Flow but IntegrationConnection.OwnerUserId = null and BrandAccountId is set. Connection is visible to all users with EasyCrm.SocialCrm.UseBrandAccounts.

Reconnect after token expiry

Background refresh fails (refresh token revoked or expired). Sets and emits SocialConnectionDegraded event. UC-10.1 notification: Your LinkedIn connection needs re-authentication Open Settings — clicks Reconnect — repeats steps 4–8 in-place.

If something goes wrong

User denies consent

Returns . EasyCRM shows: Social connection was not authorized. The required scopes are needed for listening and engagement No connection is persisted.

`state` mismatch or csrf

The state in the callback does not match the value stored for the your session. EasyCRM returns HTTP 400, logs a security event.

Provider not configured

Admin has not registered the OAuth app. Connect buttons are disabled with tooltip: Contact your administrator to enable this provider

Good to know

  • OAuth 2.0 with PKCE is mandatory; implicit flow is not supported.
  • Access/refresh tokens are encrypted at rest using the ABP Data Protection key shared with email tokens (FR-09-001 / FR-13-001).
  • A user may connect at most one account per provider; a tenant may connect multiple brand accounts per provider.
  • All connection actions are recorded in the audit log (SocialConnectionCreated, SocialConnectionRevoked).