Custom Social Login with Google

When integrating Descope flows in a website, often you'll want to allow Social Login with Google as one of the authentication methods for your users. However, when you actually sign in with the flow, the Google sign-in page will not be personalized to your website domain by default. In order to get that to work, you'll need to make a few changes and create a Google Social Login app. This tutorial will explain all the steps on how to do that.

Current Default Login Page

The default Descope login app looks like this (Click on Google):

However, if you use the Descope login app, the sign in page will default to show Sign in to continue to Descope.

Instead of displaying Descope and our logo, this guide will show you how to personalize your Google Sign-In Page to display your own company logo and domain instead.

Solution

To make this happen, you'll need to configure a few things on the Google side and the Descope side, as well as configure a new CNAME in your domain's DNS records.

Configuring the CNAME

You will need to create a custom domain that points to cname.descope.com (US) / CNAME.euc1.descope.com (EU), so that if the redirect URI is auth.example.com for instance, the Google page will show Sign in to continue to with example.com instead of descope.com

See the Custom Domain guide for a step by step guide for managing sessions within cookies.

Once that is completed, you will need to create a new public Google app.

Creating a new Google App

1. You will need to follow the steps here, to create an OAuth Google login app with your personalized settings and logo.

2. When going through all of the steps, you'll need to add scopes. This tells Google what information the app can access about the user that is signing in. If you want to learn more about the specific scopes, you can do so here

You MUST check openid, and we highly recommend using the userInfo.email and userInfo.profile scopes as well:

3. Once the app has been created, you should head back to your dashboard to see this:

Now click on Publish App, and your app should be published in production for anyone to see.

If you got confused with any of the steps, there is an FAQ here that should be able to help answer any questions you may have had while creating the app.

4. To get the client ID and secret for your new app, click on Credentials in the left-hand sidebar and select + Create Credentials

5. Select OAuth Client ID, and then select the application type you're using Descope with. Then, fill in the rest of the information below, and click Create:

1. Name - add your own name
2. Authorized JavaScript - add your website url - Example: http://www.example.com
3. Authorized redirect URIs - <Get this from Descope Console, look at instructions below>

It's important to make sure that the authorized redirect URI is configured here properly, as this needs to match what is in the Descope console for the OAuth callback. You can get URI by heading to the Descope console here, and clicking on Google -> Use my own account (under Authentication account). Don't worry about the rest of the fields for now, just enter the CNAME you created in the first step, under OAuth Callback CNAME, and you should see the URL to register in your social app change. That will be your authorized redirect URI. Copy that URL over, and paste it in the Google developer console.

Also, make sure to leave that Descope Console window open, as you'll need it again in the final steps.

Your page should look something like this:

6. Copy your client ID and the secret to the clipboard, and we should be done with Google!

Now that you've created a Google App and have it published and approved by Google, you can wrap this up by changing a few simple things in the Descope Console.

Descope Configuration

1. Go to the Descope Console, click on Google, and then select Use my own account underneath Authentication account:

2. From Google, copy over the Client ID and Client Secret (from the Google Developer Console), and OAuth CNAME you've configured in your DNS and paste them into the respective fields.

3. Make sure that your CNAME is present in the OAuth Callback CNAME field. This should have been done in step 5, of setting up the Google App.

4. Finally, as if you were using the Descope app instead of your own custom app, put the redirect URL you wish to redirect your users to after they have successfully logged in. If you have already set a redirect URL with a Descope SDK, this field is not required to be set.

Prompt

The Prompt setting controls how users are prompted when they sign in with Google, such as forcing them to re-authenticate (login), re-approve permissions (consent), or choose an account (select_account). Prompts can also be overridden at the Flow level. See Configure the Prompt for what each option does.

User Attribute Mapping

User Attribute Mapping maps the attributes Google returns to fields on the Descope user, including custom attributes. See Configure User Attribute Mapping for how to set up mappings and when user information is refreshed on login.

Advanced

The Advanced section contains optional settings such as Manage tokens from provider, Callback Domain, Redirect URL, and Email address handling. See Configure Advanced Settings for the full list.

Managing Tokens from Provider

Enable Manage tokens from provider and select an Outbound App to have Descope store the user's Google OAuth tokens. You must first create the Outbound App in the Descope Console before you can select it here. See Configure Advanced Settings for details.

Email Address Handling

Email address handling controls whether the email address Google returns is used as a login ID, which allows sign-ins to merge with existing users who have the same email, or is only stored as a user attribute. See Configure Advanced Settings for the available options, and Handling OAuth Providers with Unverified Emails for how verified and unverified emails are handled.

And you're done! Now when you sign in, you should see your own personalized app page with your custom domain name. If you have any questions, please reach out to us here!