Extensions Docs Server: Doc conversion script

chrome/common/extensions/docs/server2/templates/articles/app_identity.html

+<h1>Identify User</h1>
+
+
+<p>
+Web authentication protocols utilize HTTP features,
+but packaged apps run inside the app container;
+they don’t load over HTTP and can’t perform redirects or set cookies.
+</p>
+
+<p>
+Use the <a href="experimental.identity.html">Chrome Identity API</a>
+to authenticate users:
+the <code>getAuthToken</code> for users logged into their Google Account and
+the <code>launchWebAuthFlow</code> for users logged into a non-Google account.
+If your app uses its own server to authenticate users, you will need to use the latter.
+</p>
+
+<p class="note">
+<b>API Samples: </b>
+Want to play with the code?
+Check out the
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/identity">identity</a> sample.
+</p>
+
+<h2 id="how">How it works</h2>
+
+<p>
+Apps that use Google accounts
+need to specify the OAuth2 client ID
+and scopes in their manifest.
+When users install the apps,
+the OAuth2 permissions are displayed along with the Chrome permissions.
+Once a user accepts the permissions,
+the apps can get the access token
+using <code>getAuthToken</code>.
+</p>
+
+<p>
+Apps that want to perform authentication
+with any provider must call <code>launchAuthFlow</code>.
+This method uses a browser pop-up to show the provider pages
+and captures redirects to the specific URL patterns.
+The redirect URLs are passed to the app
+and the app extracts the token from the URL.
+</p>
+
+<h2 id="google">Google account authentication</h2>
+
+<p>
+Here are the five steps you need to complete:
+</p>
+
+<ol>
+        <li>Add permissions to your manifest and upload your app.</li>
+        <li>Copy key in the installed <code>manifest.json</code> to your source manifest.</li>
+        <li>Get your client ID.</li>
+        <li>Update your manifest to include the client ID and scopes.</li>
+        <li>Get the authentication token.</li>
+</ol>
+
+<h3>Add permissions and upload app</h3>
+
+<p>
+The identity API is still experimental.
+You need to make sure the experimental
+and identity permissions are in your manifest.
+You can then upload your app to the apps and extensions management page
+(see <a href="publish_app.html">Publish</a>).
+</p>
+
+<pre>
+"permissions": [
+  "experimental",
+  "identity"
+ ]
+</pre>
+
+<h3>Copy key to your manifest</h3>
+
+<p>
+You need to copy the key in the installed
+<code>manifest.json</code> to your source manifest.
+This ensures that the key isn't overridden anytime your reload your app
+or share the app with other users.
+It's not the most graceful task, but here's how it goes:
+</p>
+
+<ol>
+        <li>Go to your
+                <a href="http://www.chromium.org/user-experience/user-data-directory">user data directory</a>.
+                Example on MacOs: <code>~/Library/Application\ Support/Google/Chrome/Default/Extensions</code></li>
+        <li>List the installed apps and extensions and match your app ID on the apps and extensions management page
+                to the same ID here.</li>
+        <li>Go to the installed app directory (this will be a version within the app ID).
+                Open the installed <code>manifest.json</code>
+                (pico is a quick way to open the file).</li>
+        <li>Copy the "key" in the installed <code>manifest.json</code> and paste it into your app's source manifest file.</li>
+</ol>
+
+<h3>Get your client ID</h3>
+
+<p>
+Setting up the client ID is currently not available externally
+via <a href="https://devconsole-canary.corp.google.com/apis/">Google APIs Console</a>.
+So to setup the OAuth2 client ID,
+email <a href="mailto:chrome-apps-auth-requests@google.com">chrome-apps-auth-request@google.com</a>
+with your stable app ID and
+we will reply appropriately with your OAuth2 client ID.
+</p>
+
+<h3>Update your manifest</h3>
+
+<p>
+You need to update your manifest to include
+the client ID and scopes.
+Here's the sample "oauth2" for the
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gdocs">gdocs sample</a>:
+</p>
+
+<pre>
+"oauth2": {
+    "client_id": "665859454684.apps.googleusercontent.com",
+    "scopes": [
+      "https://docs.google.com/feeds/",
+      "https://docs.googleusercontent.com/",
+      "https://spreadsheets.google.com/feeds/",
+      "https://www.googleapis.com/auth/drive.file"
+    ]
+  }
+</pre>
+
+<h3>Get the token</h3>
+
+<p>
+You are now ready to get the auth token:
+</p>
+
+<pre>
+chrome.experimental.identity.getAuthToken(function(token) { })
+</pre>
+
+<h2 id="non">Non-Google account authentication</h2>
+
+<p>
+Here are the three steps you need to complete:
+</p>
+
+<ol>
+        <li>Register with the provider.</li>
+        <li>Add permissions for provider resources that your app will access.</li>
+        <li>Get the authentication token.</li>
+</ol>
+
+<h3>Register with the provider</h3>
+
+<p>
+You need to register an OAuth2 client ID with the provider
+and configure the client ID as a website.
+For the  redirect URI to be entered during registration,
+use the URL of the form:
+<code>https://<extension-id>.chromiumapp.org/<anything-here></code>
+</p>
+
+<p>
+For example, if you app ID is abcdefghijklmnopqrstuvwxyzabcdef and
+you want provider_cb to be the path,
+to distinguish it with redirect URIs from other providers,
+you should use:
+<code>https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb</code>
+</p>
+
+<h3>Add permissions for provider</h3>
+
+<p>
+To make cross-original XHRs to Google API endpoints,
+you need to whitelist those patterns in the permissions:
+</p>
+
+<pre>
+"permissions": [
+  ...
+  "https://docs.google.com/feeds/",
+  "https://docs.googleusercontent.com/",
+  “https://www.website-of-provider-with-user-photos.com/photos/”
+]
+</pre>
+
+<h3>Get the token</h3>
+
+<p>
+To get the token:
+</p>
+
+<pre>
+chrome.experimental.identity.launchWebAuthFlow(
+  {‘url’: ‘&lt;url-to-do-auth>’, ‘interactive’: true},
+  function(redirect_url) { // Extract token from redirect_url });
+</pre>
+
+<p>
+The &lt;url-to-do-auth> is whatever the URL is to do auth to the provider from a website.
+For example, let us say that you are performing OAuth2 flow with a provider
+and have registered your app with client id 123456789012345 and
+you want access to user’s photos on the provider’s website:
+<code>https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_id=123456789012345&amp;<br>redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb&amp;response_type=token&amp;scope=user_photos</code>
+</p>
+
+<p>
+The provider will perform authentication and if appropriate,
+will show login and/or approval UI to the user.
+It will then redirect to
+<code>https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authToken=&lt;auth-token></code>
+</p>
+
+<p>
+Chrome will capture that and invoke the callback
+of the app with the full redirect URL.
+The app should extract the token out of the URL.
+</p>
+
+<h3>Interactive versus silent mode</h3>
+
+<p>
+When calling <code>launchWebAuthFlow</code>,
+you can pass a flag (‘interactive’: true in the example above)
+indicating whether you want the API to be called
+in interactive mode or not (aka silent mode).
+If you invoke the API in interactive mode,
+the user is shown UI, if necessary,
+to get the token (signin UI and/or approval UI;
+or for that matter any provider specific UI).
+</p>
+
+<p>
+If you invoke the API in silent mode,
+the API will only return a token if the provider is able
+to provide a token without showing any UI.
+This is useful in cases when an app is doing the flow at app startup, for example,
+or in general in cases where there is no user gesture involved.
+</p>
+
+<p>
+The best practice we suggest is to use silent mode
+when there is no user gesture involved and use interactive mode
+if there is a user gesture (for example, the user clicked the Sign In button in your app).
+Note that we do not enforce gesture requirement.
+</p>
+
+<p class="backtotop"><a href="#top">Back to top</a></p>