Browser App Best Practices

The following is a checklist of steps to take when using Google Sign-In with work accounts for a SaaS offering available in a desktop browser. These are suggested best practices for SaaS developers. It can be very complex to implement sign-in well, so consider using software and services that handle most of this for you. Google Identity Toolkit is one option, but you might also evaluate other vendors that support these standards such as Ping Identity. After your SaaS sign-in supports G Suite customers, you might also request to become a listed vendor in the G Suite Marketplace.

  1. Very few SaaS apps require Google Sign-In for all their users, so first determine if the end-user should try to authenticate with Google Sign-In. There are multiple ways to do this. Google itself acts as relying party to thousands of companies who run their own identity provider. If you look at desktop apps like Google Drive, you will see that the first step of the sign-in flow just asks for an email address. After that is entered, the app can determine if the user should be redirected to an identity provider or authenticated with a password. Not all apps have a single account per email address though, and those others generally need to first ask the user for their Tenant name. Other variants of this are also possible.

  2. After the first step is done, if the app determines that the account should be authenticated with Google Sign-In, we suggest using our web SDK. If your app already has the user's email address, the flow can be improved by including it in your OpenID Connect request so Google knows to only look for accounts that end in that domain name. On the web this is done using the login_hint parameter. If your app doesn't have the full email address, but knows the domain name, then you can pass that instead so Google knows to only look for accounts that end in that domain name. On the web, this is done using the hd parameter.

  3. After you get an OpenID Connect assertion from Google, check that Google confirmed it is an account controlled by the administrators of the domain name.

    • In JavaScript, this is done using the GoogleUser.getHostedDomain() function
    • On the server, the hd claim in the ID token is used to verify the domain is what you expected. See Authenticate with a backend server.

    Then, use the asserted email address to find the account record in your system. However, the sub value in the ID token is a more stable identifier, so the preferred approach is for the company to have provisioned the account in your system ahead of time including giving you that sub ID.

  4. Google's OpenID Connect support can be used for the initial authentication of a user. Your app needs to manage the session after that point.

  5. If you have all the steps above working, you should register as a vendor in the G Suite Marketplace. One of the advantages it provides is enabling a G Suite IT admin to easily add your applications to the allowlist so employees can be signed into them automatically instead of each employee having to consent to sign in.

    It is also possible for IT admins to manually allowlist your application, but the steps involved are more complex:

    1. Open the G Suite admin console.
    2. Click the Security icon, then click Show More > Advanced Settings > Manage API client access.
    3. Type the OAuth Client ID your SaaS application registered with Google, which is normally a string of letters and numbers followed by
    4. In the API Scopes field, type the following string:
      If your app needs to request additional scopes to access Google APIs, specify them here as well.
    5. Click Authorize. The authorization will take effect in about 30 minutes.