Gravity Forms Social Sign-In Premium Add-on Setup Guide

The Gravity Forms Social Sign-In Premium Add-on adds a Social Sign-In field to Gravity Forms. The visitor presses Sign in with Google, Microsoft, Apple, Facebook or LinkedIn, agrees on the provider’s own screen, and the name, e-mail address and, if you want it, the photo fields of your form are filled in from the verified profile. The form can ask for nothing else and still know who is sending it.

The add-on uses your own app at each provider. You create the app, copy its keys into one settings page, and the sign-in runs between your site and the provider. There is no middleman, no account to open with us and no per-sign-in fee.

What you need

• WordPress 6.5 or newer and PHP 7.4 or newer, with the OpenSSL extension (every normal host has it).
• Gravity Forms 2.9 or newer. The add-on is tested with Gravity Forms 3.1.2 on PHP 8.3 and Gravity Forms 2.9.8 on PHP 7.4.
• A site on https. The providers only accept secure redirect addresses for live sites.
• An app (client ID and secret) at each provider you want to offer, created with your own account.
• An active license key for this add-on.

If Gravity Forms is missing or older than 2.9, the add-on shows a notice in the WordPress admin and does nothing else.

Install and activate

1. Install and activate the add-on like any plugin, after Gravity Forms.
2. Open Forms → Settings → Social Sign-In and enter your license key.
3. Open Forms → Social Sign-In to enter the keys of your apps. This is the page with a card for each provider.

Set up a provider

Every provider card has the same parts: an Enabled box, the client ID, the client secret, the redirect address and a Test sign-in button. The redirect address is the one thing you must copy to the provider, so the card shows it with a Copy button. It looks like your-site/wp-json/gesl/v1/callback/google, with the provider’s name at the end.

1. Open the developer console of the provider (the card shows its address) and create an app or a client for a web application.
2. Paste the redirect address of the card into the list of allowed redirect addresses of that app. It must match exactly, including https and the trailing name.
3. Copy the client ID and the client secret into the card, tick Enabled and save.
4. Press Test sign-in. A small window opens, you sign in with the provider, and the card says whether the test passed. The test never logs you out, logs anyone in or creates a user.

Provider notes

• Google: create an OAuth client of the type web application in the Google Cloud console. The add-on asks for the openid, email and profile scopes only.
• Microsoft: register an application in Microsoft Entra, add a web redirect address and create a client secret. The Tenant box says who can sign in: common for any Microsoft account, organizations for work and school accounts, consumers for personal accounts, or the ID or domain of one tenant.
• Apple: create a Services ID with Sign in with Apple, add your domain and the redirect address, and create a key. The card asks for the Services ID, your Team ID, the Key ID and the text of the private key file (the .p8 file). The add-on signs the short-lived client secret that Apple wants by itself. Apple tells the name only the first time a person signs in to your app.
• Facebook: create an app with the Facebook Login product, add the redirect address to the valid OAuth redirect addresses, and switch the app to live mode when you are ready. The add-on asks for the email and public_profile permissions.
• LinkedIn: create an app, add the product Sign In with LinkedIn using OpenID Connect and the redirect address on the Auth tab.

The client secret is stored encrypted (AES-256-GCM with a key derived from your WordPress salts) and is never shown again after you save. To keep the saved secret, leave the field empty when you save the page. Tick Remove the saved secret to delete it. If your site salts change, the saved secrets can no longer be read and you enter them again.

Add the field to a form

1. Open the form in the editor and add Social Sign-In from the Advanced Fields group.
2. Tick the providers this form offers. A provider without keys is never shown to visitors.
3. Choose how it opens: a popup window (the form stays as it is) or the same window (the page leaves and comes back).
4. Choose the fields to fill: a Name or text field for the name, an E-mail or text field for the address and, if you like, a text or hidden field that receives the address of the photo.
5. Optional: tick Save the provider and a hashed user id in the entry, and edit the privacy text under the buttons.
6. Tick Required on the field if visitors must sign in before they can send the form.

The field works with AJAX forms and multi page forms. In the popup mode the fields of every page are filled at once, so the name and e-mail are already there when the visitor reaches the page that shows them. When a page is shown again after a validation error, the sign-in is kept. In the same-window mode the visitor comes back to the same page with the fields filled and the address cleaned of any technical parameters.

What is filled, and what is verified

The form is filled from the provider’s answer after the add-on has checked it. Nothing the browser says is trusted.

• The add-on starts the sign-in with the authorization code flow and PKCE (the S256 method), a random state value and, for the OpenID Connect providers, a random nonce.
• The state is used once and is tied to the browser that started the sign-in by a cookie. A returned link with the wrong state, an old state, a state used twice or a state from another browser is refused.
• The code is exchanged for tokens on your server, with your client secret and the PKCE verifier.
• For Google, Microsoft, Apple and LinkedIn the ID token is verified: the signature against the provider’s published keys (RS256 only, other algorithms and “none” are refused), the issuer, the audience (your client ID), the expiry and the nonce.
• For Facebook, which does not give an ID token on the web flow, the profile is read from the Graph API with the access token that your server received, signed with the app secret proof.
• Names are cut to a sensible length and stripped of markup. A photo address is accepted only when it is a plain https address.

If anything fails, the visitor sees a short message in the field and nothing is filled.

Accounts on your site

By default the add-on does nothing to WordPress users. It only fills the form. Two options on the settings page change that, and both are off until you tick them.

• Sign in an existing user with the same verified e-mail. A visitor whose provider confirms an e-mail address that belongs to an existing user is signed in as that user. The provider must say the address is verified: Google, Apple and LinkedIn do, Microsoft only when it sends its optional verified-domain claim, and Facebook is never treated as verified. An address that is not confirmed never signs anyone in.
• Create a new subscriber. When the verified e-mail has no account, a new user is created with the role subscriber, a long random password and no e-mail sent. The role cannot be changed by this add-on.

Administrators and any other user with more than subscriber-level rights are never signed in this way, whatever the e-mail says, and an account is never taken over: if the address belongs to a user and the provider does not prove the address, nothing happens to that user. A user the add-on created and who later gets more rights is not signed in any more. The check looks at the rights of the user, not at the name of the role, so a custom role with editing rights counts as privileged. A developer can list extra harmless capabilities with the filter gesl_benign_caps, but the rights to manage options, manage users or run plugins can never be listed.

A signed-in user is linked to the provider by a hashed provider user id (a keyed hash of the provider and the id, so the real number is never stored). The next sign-in finds the same user even if the e-mail address has changed.

What is saved

If you ticked Save the provider and a hashed user id in the entry, the field stores a value like google: followed by a 64-character hash. It identifies the same person across entries without exposing the provider’s account number. The value comes from the add-on’s own record of the sign-in, never from what the browser posts, so it cannot be forged.

The profile that is used to fill the form sits in a temporary record for at most 30 minutes, tied to the visitor’s browser, and is deleted as soon as the entry is saved.

Privacy and the law

A short privacy text is shown under the buttons of every field. You can edit it for each field. A suggested paragraph for your privacy policy is added to Settings → Privacy → Policy Guide. The provider receives the address of your site and learns that the visitor signs in to it, and the provider’s own policy applies to that part. You are responsible for choosing a legal basis and, where it is needed, for asking the visitor before the sign-in, for example with a consent field placed above the buttons.

For developers

• Action gesl_signed_in runs after a verified sign-in with the provider key, the profile, the account result and the form ID.
• Filter gesl_email_verified decides whether a Facebook address counts as verified (false by default).
• Filter gesl_button_html replaces the markup of a button, for example to use the official button artwork a provider asks for. Filter gesl_button_prefix changes the text Sign in with.
• Filter gesl_facebook_version sets the Graph API version.

Questions

Do the visitors need an account at my site first?

No. The sign-in only fills the form. An account is created only if you tick that option.

Why is my sign-in refused with a message about the state?

The sign-in must finish in the browser that started it, within ten minutes, and only once. Start it again from the form. If you use a page cache that serves the same page to everyone, the buttons still work, because nothing about the visitor is placed in the page.

Why did the test button say that the token could not be verified?

Check that the client ID in the card is the one of the app, that the Microsoft tenant matches the kind of accounts the app accepts, and that the clock of the server is right. The provider keys are fetched from the provider and cached for an hour.

Does it work in a popup on a phone?

Phones may open the popup as a new tab. When no opener window exists the add-on takes the visitor back to the form page with the fields filled, so it still works.

Can I use the official Google or Apple buttons?

Yes. Use the gesl_button_html filter to output the artwork and wording that the provider requires for your use. The built-in buttons are plain and brand-neutral.

Questions about the setup? Use the support tab in your account and we will help.