authentication.html

{{+bindTo:partials.standard_store_article}}
<p class="caution">
  <b>Important:</b>
  Chrome will be removing support for Chrome Apps on Windows, Mac, and
  Linux.  Chrome OS will continue to support Chrome Apps.  Additionally,
  Chrome and the Web Store will continue to support extensions on all
  platforms.
  <a href="http://blog.chromium.org/2016/08/from-chrome-apps-to-web.html">
  Read the announcement</a> and learn more about
  <a href="https://developers.chrome.com/apps/migration">
  migrating your app</a>.
</p>

<h1>Supporting Federated Login with Google Accounts for Chrome Web Store
    Apps</h1>

<p class="attribution">
    Written by Jan Kleinert<br/>
    November 2010
</p>

<p>
    When a user installs and launches your app from the Chrome Web Store, odds
    are they’ll be signed in to their Google Account. If your app requires
    authentication, then you should significantly streamline the process for
    your users by supporting Federated Login to allow users to sign in to your
    app using their Google Accounts. In this article, we’ll cover some the
    basics of Federated Login using Google Accounts, things to consider when
    designing your authentication flow, some examples of apps that allow users
    to sign in using their Google Accounts, and resources to help you learn more
    and get started.
</p>

<h2 id="overview">
    Overview of Federated Login
</h2>

<p>
    Federated Login, based on the <a href="http://openid.net">OpenID</a>
    standard, frees users from having to set up separate account credentials for
    different web apps, and frees developers from the task of implementing login
    authentication measures. OpenID achieves this goal by providing a framework
    in which users can establish an account with an OpenID provider, such as
    Google, and use that account to sign in to any web app that accepts OpenIDs.
</p>

<p>
    Google supports the OpenID 2.0 protocol, providing authentication support as
    an OpenID provider. A third-party site can request Google to authenticate
    users who are signing in with an existing Google Account. Google will return
    an identifier to the third-party site that the site can use to recognize the
    user. This identifier is uniquely identifies the user, enabling the
    third-party site to recognize the user across multiple sessions.
</p>

<h2 id="considerations">
    Considerations
</h2>

<p>
    When deciding how to structure the authentication flow for your app, keep
    the following considerations in mind.
</p>


<h4>Will you be adding support for Federated Login with Google Accounts on top
    of an existing authentication system?</h4>
<p>
    If so, you can provide users a way to link their new accounts with their
    existing accounts. For more guidance and best practices for handling and
    linking legacy accounts, see <a
        href="http://sites.google.com/site/oauthgoog/UXFedLogin/loginlogic">this
    article</a>. In the <a href="#examples">Examples</a> section below, you'll
    see a walk through of the account creation process for Springpad, which
    gives the user the choice to link with an existing account or continue as a
    new user.
</p>

<h4>Do you you want to use a different authentication flow if your app is
    launched via the Google Chrome app launcher?</h4>
<p>
    You can further streamline the process for users by supporting a different
    authentication flow when your app is launched via the Google Chrome app
    launcher as opposed to a bookmark or link. You can use JavaScript to check
    whether <code>window.chrome.app.isInstalled</code> is defined. If it is, the
    app is running from the Google Chrome app launcher, and you can assume
    they'll be signing in via their Google Account. Here's an example of the
    code you'd use:
<pre>if (window.chrome.app.isInstalled) {
  // You're running as an installed app, via the app launcher!
} else {
  // You're running via a bookmark or link.
}</pre>
</p>

<h4>Must users provide information in order to create a new account in your
    system?</h4>
<p>
    With OpenID, you can request information such as first name, last name,
    email address, region, and language. You request this additional information
    by including <a
        href="https://developers.google.com/accounts/docs/OpenID#endpoint">attribute
    exchange parameters</a> in the authentication requests that you send to the
    Google OpenID endpoint. What if you require additional information such as
    settings related to your app, or if you require a user to accept your terms
    of service before creating an account? In those cases, you can prompt the
    user to provide additional information after they've opted to sign in with
    their Google Account. In the <a href="#examples">Examples</a> section below,
    you'll see a walk through of the account creation process for Manymoon,
    which demonstrates this process. If the extra information is optional, then
    you can also consider waiting until after a user has created their account
    to gather this information, in order to simplify the account creation
    process.
</p>

<h4>What authentication options will you present to your users?</h4>
<p>
    The way you decide to design your user interface may be different if you
    only support Federated Login with Google Accounts versus supporting
    Federated Login with Google Accounts and your existing authentication
    system. See <a href="http://sites.google.com/site/oauthgoog/UXFedLogin">Usability
    Research on Federated Login</a> for more options.
</p>

<h4>Do you want to use a pop-up UI or a browser redirect flow for signing
    in?</h4>
<p>
    You have a choice of how users will be prompted for their Google Account
    credentials. You can prompt them via a pop-up UI, or you can use a browser
    redirect flow. Our <a href="samples.html#php">PHP sample code</a>
    demonstrates how to use the pop-up UI, while the <a
        href="samples.html#java">Java</a> and <a href="samples.html#python">Python</a>
    sample code uses the browser redirect flow. To try the different styles of
    authentication yourself, see <a href="http://www.puffypoodles.com/">these
    examples</a>.
</p>

<h4>What if a user deletes their Google Account?</h4>
<p>
    If a user deletes their Google Account, they can no longer sign in to your
    app using that account. In this case, you could provide a way of associating
    accounts in your system with a different OpenID identifier, similar to a
    password reset flow.
</p>

<h2 id="workflow">
    Sample Workflow
</h2>

<p>
    This sample workflow walks through the authentication process for an app
    that supports Federated Login.
</p>

<img src="images/authentication.png"/>

<h2 id="examples">
    Examples
</h2>
<p>
    The screencasts below show three different account creation and
    authentication scenarios from a user's perspective.
</p>


<h4>Basic authentication flow</h4>
<p>
    This screencast uses the Diary.com app to demonstrate a basic authentication
    flow.
</p>
<p>
    <iframe title="YouTube video player" class="youtube-player" type="text/html"
            width="480" height="390"
            src="https://www.youtube.com/embed/u4FBk_XUw2Q?rel=0"
            frameborder="0"></iframe>
</p>
<br/>

<h4>Requesting additional information during account creation</h4>
<p>
    In this screencast, the Manymoon app demonstrates an account creation flow
    where the user is prompted for additional information.
</p>
<p>
    <iframe title="YouTube video player" class="youtube-player" type="text/html"
            width="480" height="390"
            src="https://www.youtube.com/embed/wV0ModwrCvo?rel=0"
            frameborder="0"></iframe>
</p>
<br/>

<h4>Linking with an existing account</h4>
<p>
    This screencast uses the Springpad app to show how a user can sign in to an
    app with their Google Account and then link to an existing Springpad
    account.
</p>
<p>
    <iframe title="YouTube video player" class="youtube-player" type="text/html"
            width="480" height="390"
            src="https://www.youtube.com/embed/_k7lmFC9IrY?rel=0"
            frameborder="0"></iframe>
</p>

<h2 id="resources">
    Resources and Best Practices
</h2>

<p>
    This section has some final tips about terminology, federated identity, and
    where you can get more information.
</p>

<p>
    For consistency with Google Accounts, we recommend using the following terms
    to
    refer to account creation and authentication:
<ul>
    <li><strong>sign in</strong></li>
    <li><strong>sign out</strong></li>
    <li><strong>create</strong></li>
</ul>
</p>

<p class="note">
    <b>Note</b>:
    The adjective and noun forms of the first two terms are <em>sign-in</em> and
    <em>sign-out</em>. Also note that the user <em>signs in to</em> an account
    (that's three words).
</p>

<p>
    When a user is creating an account in your app, we recommend displaying a
    splash page to the user before prompting them to sign in to their Google
    Account. Displaying a splash page provides context to the user about why
    they're being asked to sign in to their Google Account. The Springpad app in
    the <a href="#examples">Examples</a> section above demonstrates one possible
    layout for a splash page. See <a
        href="http://sites.google.com/site/oauthgoog/UXFedLogin">Usability
    Research on Federated Login</a> for more options.
</p>

<p>
    Make sure you're using the correct federated identity URL when you request
    the <a href="https://developers.google.com/accounts/docs/OpenID#endpoint">OpenID
    endpoint</a>. The URL you should use to get the Google OpenID endpoint is
    <code>https://www.google.com/accounts/o8/id</code>.
</p>

<p>
    Here are some places where you can find more information
    about OpenID and Federated Login for Google Accounts.
</p>
<ul>
    <li>For technical guidance on using Federated Login for Google Accounts, see
        the documentation for <a
                href="https://developers.google.com/accounts/docs/OpenID#working">working
            with OpenID</a>.
    </li>
    <li>The <a href="identify_user.html">Identifying the User</a> section of the
        Chrome Web Store Developer's Guide provides more details on when
        supporting Federated Login with Google Accounts is required and when
        it's optional, as well as a listing of OpenID libraries you can use.
    </li>
    <li>For sample code that demonstrates how to obtain the OpenID identifier
        for a user and how to use the Chrome Web Store Licensing API, see these
        <a href="samples.html">samples</a> for Java, Python, and PHP.
    </li>
    <li>Visit the <a
            href="http://groups.google.com/group/google-federated-login-api">Google
        Group on Federated Login</a> for discussion on using Google's OpenID
        API</a>.
    </li>
</ul>

{{/partials.standard_store_article}}