Chances are you may have read the note about Google+ closing with a disinterested sigh. After all, you never integrated your app with Google+ social buttons or APIs.
You may want to think again.
If you added Google Sign-In to your application over the last eight years, you probably followed the advice given to developers at the time to use the Google+ People API. This was recommended even if you just wanted profile or email address of your users, something usually served by the ID token provided by the Google Identity service. You’ll want to make the change below, or you could start seeing failures in the next few months.
When Google Accounts were Google Plus Accounts
When Google released Google+ in 2011, they made significant changes to which APIs they wanted developers to call for user information. There was no reason to believe Google+ wouldn’t be successful, so these APIs seemed a future proof way to ensure developers would be getting the best information for a user, including the additional social information Google+ provided. Most of us in the cloud software industry know this impulse; we want to move customers and developers to where our resources are strategically focused and not duplicate APIs across different services.
All the ways to get user information
To understand Google’s motivations, it’s helpful to understand all the ways you can get data about a user on modern cloud platforms such as Google and Microsoft. This is due to our mutual commitment to standards, particularly OAuth2 and OpenID Connect.
Using the Identity Service
When a developer writes code to sign a user in to their application, chances are very good they are using OAuth2 and OpenID Connect. You can think of OpenID Connect as a layer above OAuth2 meant specifically to sign in users and prove they have an account with the identity service. All major identity services use OAuth2 and OpenID Connect, including Facebook, Amazon, Google, and Microsoft.
OpenID Connect specifies two ways to get information about the signed in user:
- By looking in to the ID token which comes back to the app when authenticating the user.
- By calling a UserInfo endpoint with an Access Token. Any additional information outside of what is in the ID token usually requires additional consent.
The original idea of the ID Token was for it to act as a verifiable calling card of sorts on the internet, able to be passed around from service to service so each could easily customize its experience to the user without needing to call a backend service (like the UserInfo endpoint).
In practice this use is much more restricted. Since the ID token can be passed around to other services on the internet, and that can cause disclosure of the Personally Identifable Information (PII), most of the industry has moved towards a very restricted set of PII claims in the ID token (email, Full Name, etc.) requiring a call to either the UserInfo endpoint or a Graph service for all other user data.
Using the Graph Service
Most modern platforms also have a “Graph API” that you can call to get information about a user.
For Microsoft this User graph endpoint is very extensive and well beyond what can be provided through a UserInfo endpoint. Google’s new People API is equally extensive.
All of these options to get user information leads to developer confusion. Although the ID token allows you to not need additional network calls to identify the user, most apps need updated data and end up calling the UserInfo endpoint anyway. Some SDKs built exclusively to the OAuth2 standards like App Auth will rely on UserInfo for user data, whereas SDKs from the services themselves like MSAL from Microsoft and Google SignIn will use the Graph API.
There is no easy answer. For years we at Microsoft resisted implementing the UserInfo endpoint and pointed developers to the Graph API to reduce developer confusion. Alas, to better support developers who want to use their SDK of choice we recently relented and added a UserInfo endpoint of our own.
Google Points Developers To The Graph
Google made much the same decision in recommending developers use their Graph API for Google+. Part of this change was to point developers who needed information about a Google (now Google+) user in their app to use the Google+ People API:
This was the default guidance for the entire eight year span Google+ was available. This was maintained as interest in Google+ was reduced and Google Accounts lost their Plus branding.
Why Your App May Be Impacted
Most app developers took a dependency on Google+ People API without knowing it, even if the rest of their app had no ties to Google+ at all. Since most app developers aren’t identity experts, they had little awareness they were taking this dependency or the other options available to them.
This means soon developers will begin seeing failures in their applications. You can easily see if you’re impacted by searching for the /v1/people/me endpoint in your code.
How To Fix Your Google Identity Platform Sign-In
There are two paths to fixing your Google sign-in. Which you choose depends on how you use the Google platform.
Option 1: Use the ID token you get from Google
If you are only using Google accounts to sign-in users to your app and you have a backing user account in your own database, then just sticking with the standards and using the ID token should be fine. This is usually for apps that allow you to associate a Google account after account creation since you’re not interested in the full profile.
The best practice is to use the sub in the ID token as the user identifier. The sub will map to the old Google+ profile ID. You should never use the email address as the primary key to your own user database. Consider this a good time to update to the sub claim if you do so.
If you are confident you are always getting the token from Google using TLS and using it only for your app, then ID Token verification isn’t really necessary. Even Google agrees.
However, if you either receive an ID token from another app or send it along to your backend, you’ll want to validate it. Even though Google offers a token validation endpoint, I can’t recommend you just call an API to validate a token. This introduces a round-trip to a server and can impact your service if the endpoint goes down. Instead, you should validate the token yourself using the keys that Google provides in their configuration endpoint. Google has documentation on how to validate the ID token.
Option 2: Transition to the new Google People API
If you are using Google account to sign-in users to your app and rely on data from Google about that user, then migrate to the new People API.
The best part of using the new People API is that if you previously were using scopes of the Google+ People API, your users won’t be prompted for re-consent when using the new API!
This is available for the following old Google+ People API scopes: