Overview#

Identity Toolkit is Google's Authentication Method

Because there is no explicit notification from Identity Toolkit to your app when a new account is created, it is normal that the user_id in the Identity Toolkit cookie may not appear in your own per-app user database.

If you have never seen that user before (the user_id is not in your database), you should get the user’s information and create a new user in your database based on that user_id. Remember that, although the Identity Toolkit ID Token includes an email address, the value of the user_id field is always a better choice for persisting and retrieving per-user information. Most obviously, it can survive email-address changes.

Complete the user’s profile information by Getting information for users (see below). Do keep in mind though that your site may also need additional information than what is provided by Identity Toolkit APIs. Identity Toolkit doesn’t remove the need for you to interact with a new user to acquire special information relative to your app, for example shoe size or favorite color.

If you have seen that user (the user_id is in your database), you should still get the user’s information to see if it has been updated since you originally stored it in your user database. One of the advantages of using identity providers is that the user may be more likely to keep their account with the IDP updated than with your app. Users will generally regard your app more highly if you keep it up to date with their most relevant data.

Getting information for users#

While the Identity Toolkit ID Token’s payload includes a certain amount of useful user information (email, name, photo URL) you can also retrieve per-user info stored in the Identity Toolkit user database by accessing the getAccountInfo API. Typically, this API requires you have a Identity Toolkit ID Token to use as a bearer access token access the info. Your server can access this information without having the user present by setting up a Service Account as described earlier under Configure service.

Keeping track of whether a user is signed in#

Normally, in the past, you would begin each request by checking whether you had a valid session active and, if not, dispatching to your sign-in module. A Identity Toolkit-enabled app should do the same, except the redirect should be to your widget url with the url parameter mode=select. For example if the user has no active session on your site you may redirect to https://yoursite.com/signin?mode=select

As an optimization, if you find no active session, depending on your risk management needs, you could check to see whether there is a Identity Toolkit cookie and if so, validate it and extract the user’s identity. The stated expiration time is two weeks after the issue time, but you can choose whether to verify against that time or use another length of time from the issue time depending on your risk needs.

Alternate methods for managing a local session state

In addition to the method of minting your own cookies to manage session state, you could alternately use one of these other techniques to create and validate session cookies:

  • Hybrid Cookie: You can take a hybrid approach and 1) rely on the existing Identity Toolkit token without any extra confirmation or signing bits and 2) make a copy of the Identity Toolkit cookie and sign it with the your encryption key as a way to confirm it has been validated. The latter cookie can be set as an HTTP-only too, but the regular Identity Toolkit cookie will not be an HTTP only cookie. If you only want to use HTTP only cookies, then you must either mint your own or make a copy.
  • Identity Toolkit cookie only: If the website is very simple, then it can just rely on the existing basic Identity Toolkit cookie. Doing this will mean that your site will not have any control over the session dynamics and the user’s session will last for the two week duration of the Identity Toolkit cookie.

You will still need to validate the signature on the Identity Toolkit ID token and extract the basic account information.

Sign-out URL#

If you’re using the user information box, when the user signs-out, Identity Toolkit will delete the Identity Toolkit cookie and redirect the user to the Signout URL. You should implement logic on this endpoint that ends your own session.

If you're not using the user information box, feel free to delete the Identity Toolkit cookie and end your own session whenever you wish.

Send Email URL#

To complete the closed loop system that allows users to authenticate to your site via IDP or password, you also need to support to send them emails in the case of password resets and email verification. The UI flow is largely managed by Identity Toolkit but you will have to implement the email sending functionality so that you can add your own messaging and branding. Because many of the largest email providers use SPF and DKIM to authenticate that messages really come from your domain, this will also reduce the chance that these are marked as spam.

The flow proceeds as follows:#

The user clicks a forgot password or change email link. The Identity Toolkit javascript will send an HTTP POST request to your Send Email/Forgot Password URL with relevant information. Forward this information to Google Identity Toolkit. If you are not using a web client library (e.g. Java, PHP), please refer to the Handling Email Changes and Handling Forgotten Passwords sections. Otherwise,

Forward the HTTP request to the GetOobResult method in your client library. In Java, for example, you would call GitkitClient.getOobResponse(HttpServletRequest req). Extract the action link from the OOB response and send it in an email to your user. Copy the OOB response to the HTTP response to fill in the UI. If successful, return {"success": true} in the response body. Otherwise, return {"success": false}.

For example of implementing the Send Email URL, check out the Go quickstart.

Note: For sites with CSRF protection, this POST request to your Send Email URL may be blocked. Identity Toolkit lets you write the JavaScript POST request yourself so that you can include any CSRF token your site requires. See the FAQ for more details.

Adding Identity Providers#

Once you have Sign in with Google and password accounts working, you will likely want to offer other sign in options for your users.

Facebook#

Create a Facebook application at developers.facebook.com. In the settings page for your Application, click the "Add Platform" button. Select Web, then add your website URL. Copy your Facebook App ID into the Client ID field and the Facebook App Secret into the Secret Key field in the Identity Toolkit configuration page. Be sure to click "save" when you are done. Add "facebook" to the idps field in the config variable for your javascript widget.

Yahoo#

Add "yahoo" to the idps field in the config variable for your javascript widget. Set the roll-out percentage in the settings console as appropriate. Be sure to click "save" when you are done.

Microsoft#

To enable Microsoft login, note that you need to have the Google Identity Toolkit javascript widget running at your identitytoolkit.server_widget_url.

Follow these instructions to enable your Microsoft app. You should register as a website using your widget_url. Once you have registered you app, copy the Client ID and Secret Key to the Identity Toolkit configuration page. Add "microsoft" to the idps field in the config variable for your javascript widget. Set the roll-out percentage in the settings console as appropriate. Be sure to click "save" when you are done.

AOL#

To enable AOL login, note that you need to have the Google Identity Toolkit javascript widget running at your identitytoolkit.server_widget_url.

Add "aol" to the idps field in the config variable for your javascript widget. Be sure to click "save" when you are done. Set the roll-out percentage in the settings console as appropriate. Be sure to click "save" when you are done.

PayPal#

To enable Paypal login, note that you need to have the Google Identity Toolkit javascript widget running at your identitytoolkit.server_widget_url.

Follow these instructions to enable your Paypal app. You should register as a website using your widget_url. Once you have registered you app, copy the Client ID and Secret Key to the Identity Toolkit configuration page. Be sure to click "save" when you are done. Add "paypal" to the idps field in the config variable for your javascript widget. Set the roll-out percentage in the settings console as appropriate. Be sure to click "save" when you are done.

More Information#

There might be more information for this subject on one of the following:

Add new attachment

Only authorized users are allowed to upload new attachments.
« This page (revision-3) was last changed on 28-Apr-2016 05:02 by jim