| OLD | NEW |
|---|
| (Empty) | |
| 1 <h1 class="page_title">Identify User</h1> |
| 2 <p> |
| 3 Web authentication protocols utilize HTTP features, |
| 4 but packaged apps run inside the app container; |
| 5 they don’t load over HTTP and can’t perform redirects or set cookies. |
| 6 </p> |
| 7 <p> |
| 8 Use the <a href="experimental.identity.html">Chrome Identity API</a> |
| 9 to authenticate users: |
| 10 the <code>getAuthToken</code> for users logged into their Google Account and |
| 11 the <code>launchWebAuthFlow</code> for users logged into a non-Google account. |
| 12 If your app uses its own server to authenticate users, you will need to use the
latter. |
| 13 </p> |
| 14 <p class="note"> |
| 15 <b>API Samples: </b> |
| 16 Want to play with the code? |
| 17 Check out the |
| 18 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/identity
">identity</a> sample. |
| 19 </p> |
| 20 <h2 id="how">How it works</h2> |
| 21 <p> |
| 22 Apps that use Google accounts |
| 23 need to specify the OAuth2 client ID |
| 24 and scopes in their manifest. |
| 25 When users install the apps, |
| 26 the OAuth2 permissions are displayed along with the Chrome permissions. |
| 27 Once a user accepts the permissions, |
| 28 the apps can get the access token |
| 29 using <code>getAuthToken</code>. |
| 30 </p> |
| 31 <p> |
| 32 Apps that want to perform authentication |
| 33 with any provider must call <code>launchAuthFlow</code>. |
| 34 This method uses a browser pop-up to show the provider pages |
| 35 and captures redirects to the specific URL patterns. |
| 36 The redirect URLs are passed to the app |
| 37 and the app extracts the token from the URL. |
| 38 </p> |
| 39 <h2 id="google">Google account authentication</h2> |
| 40 <p> |
| 41 Here are the five steps you need to complete: |
| 42 </p> |
| 43 <ol> |
| 44 <li>Add permissions to your manifest and upload your app.</li> |
| 45 <li>Copy key in the installed <code>manifest.json</code> to your source
manifest.</li> |
| 46 <li>Get your client ID.</li> |
| 47 <li>Update your manifest to include the client ID and scopes.</li> |
| 48 <li>Get the authentication token.</li> |
| 49 </ol> |
| 50 <h3>Add permissions and upload app</h3> |
| 51 <p> |
| 52 The identity API is still experimental. |
| 53 You need to make sure the experimental |
| 54 and identity permissions are in your manifest. |
| 55 You can then upload your app to the apps and extensions management page |
| 56 (see <a href="publish_app.html">Publish</a>). |
| 57 </p> |
| 58 <pre> |
| 59 "permissions": [ |
| 60 "experimental", |
| 61 "identity" |
| 62 ] |
| 63 </pre> |
| 64 <h3>Copy key to your manifest</h3> |
| 65 <p> |
| 66 You need to copy the key in the installed |
| 67 <code>manifest.json</code> to your source manifest. |
| 68 This ensures that the key isn't overridden anytime your reload your app |
| 69 or share the app with other users. |
| 70 It's not the most graceful task, but here's how it goes: |
| 71 </p> |
| 72 <ol> |
| 73 <li>Go to your |
| 74 <a href="http://www.chromium.org/user-experience/user-data-direc
tory">user data directory</a>. |
| 75 Example on MacOs: <code>~/Library/Application\ Support/Google/Ch
rome/Default/Extensions</code></li> |
| 76 <li>List the installed apps and extensions and match your app ID on the
apps and extensions management page |
| 77 to the same ID here.</li> |
| 78 <li>Go to the installed app directory (this will be a version within the
app ID). |
| 79 Open the installed <code>manifest.json</code> |
| 80 (pico is a quick way to open the file).</li> |
| 81 <li>Copy the "key" in the installed <code>manifest.json</code> and paste
it into your app's source manifest file.</li> |
| 82 </ol> |
| 83 <h3>Get your client ID</h3> |
| 84 <p> |
| 85 Setting up the client ID is currently not available externally |
| 86 via <a href="https://devconsole-canary.corp.google.com/apis/">Google APIs Consol
e</a>. |
| 87 So to setup the OAuth2 client ID, |
| 88 email <a href="mailto:chrome-apps-auth-requests@google.com">chrome-apps-auth-req
uest@google.com</a> |
| 89 with your stable app ID and |
| 90 we will reply appropriately with your OAuth2 client ID. |
| 91 </p> |
| 92 <h3>Update your manifest</h3> |
| 93 <p> |
| 94 You need to update your manifest to include |
| 95 the client ID and scopes. |
| 96 Here's the sample "oauth2" for the |
| 97 <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/gdocs">g
docs sample</a>: |
| 98 </p> |
| 99 <pre> |
| 100 "oauth2": { |
| 101 "client_id": "665859454684.apps.googleusercontent.com", |
| 102 "scopes": [ |
| 103 "https://docs.google.com/feeds/", |
| 104 "https://docs.googleusercontent.com/", |
| 105 "https://spreadsheets.google.com/feeds/", |
| 106 "https://www.googleapis.com/auth/drive.file" |
| 107 ] |
| 108 } |
| 109 </pre> |
| 110 <h3>Get the token</h3> |
| 111 <p> |
| 112 You are now ready to get the auth token: |
| 113 </p> |
| 114 <pre> |
| 115 chrome.experimental.identity.getAuthToken(function(token) { }) |
| 116 </pre> |
| 117 <h2 id="non">Non-Google account authentication</h2> |
| 118 <p> |
| 119 Here are the three steps you need to complete: |
| 120 </p> |
| 121 <ol> |
| 122 <li>Register with the provider.</li> |
| 123 <li>Add permissions for provider resources that your app will access.</l
i> |
| 124 <li>Get the authentication token.</li> |
| 125 </ol> |
| 126 <h3>Register with the provider</h3> |
| 127 <p> |
| 128 You need to register an OAuth2 client ID with the provider |
| 129 and configure the client ID as a website. |
| 130 For the redirect URI to be entered during registration, |
| 131 use the URL of the form: |
| 132 <code>https://<extension-id>.chromiumapp.org/<anything-here></code> |
| 133 </p> |
| 134 <p> |
| 135 For example, if you app ID is abcdefghijklmnopqrstuvwxyzabcdef and |
| 136 you want provider_cb to be the path, |
| 137 to distinguish it with redirect URIs from other providers, |
| 138 you should use: |
| 139 <code>https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb</code
> |
| 140 </p> |
| 141 <h3>Add permissions for provider</h3> |
| 142 <p> |
| 143 To make cross-original XHRs to Google API endpoints, |
| 144 you need to whitelist those patterns in the permissions: |
| 145 </p> |
| 146 <pre> |
| 147 "permissions": [ |
| 148 ... |
| 149 "https://docs.google.com/feeds/", |
| 150 "https://docs.googleusercontent.com/", |
| 151 “https://www.website-of-provider-with-user-photos.com/photos/” |
| 152 ] |
| 153 </pre> |
| 154 <h3>Get the token</h3> |
| 155 <p> |
| 156 To get the token: |
| 157 </p> |
| 158 <pre> |
| 159 chrome.experimental.identity.launchWebAuthFlow( |
| 160 {‘url’: ‘<url-to-do-auth>’, ‘interactive’: true}, |
| 161 function(redirect_url) { // Extract token from redirect_url }); |
| 162 </pre> |
| 163 <p> |
| 164 The <url-to-do-auth> is whatever the URL is to do auth to the provider from a
website. |
| 165 For example, let us say that you are performing OAuth2 flow with a provider |
| 166 and have registered your app with client id 123456789012345 and |
| 167 you want access to user’s photos on the provider’s website: |
| 168 <code>https://www.website-of-provider-with-user-photos.com/dialog/oauth?client_i
d=123456789012345&<br>redirect_uri=https://abcdefghijklmnopqrstuvwxyzabcdef.
chromiumapp.org/provider_cb&response_type=token&scope=user_photos</code> |
| 169 </p> |
| 170 <p> |
| 171 The provider will perform authentication and if appropriate, |
| 172 will show login and/or approval UI to the user. |
| 173 It will then redirect to |
| 174 <code>https://abcdefghijklmnopqrstuvwxyzabcdef.chromiumapp.org/provider_cb#authT
oken=<auth-token></code> |
| 175 </p> |
| 176 <p> |
| 177 Chrome will capture that and invoke the callback |
| 178 of the app with the full redirect URL. |
| 179 The app should extract the token out of the URL. |
| 180 </p> |
| 181 <h3>Interactive versus silent mode</h3> |
| 182 <p> |
| 183 When calling <code>launchWebAuthFlow</code>, |
| 184 you can pass a flag (‘interactive’: true in the example above) |
| 185 indicating whether you want the API to be called |
| 186 in interactive mode or not (aka silent mode). |
| 187 If you invoke the API in interactive mode, |
| 188 the user is shown UI, if necessary, |
| 189 to get the token (signin UI and/or approval UI; |
| 190 or for that matter any provider specific UI). |
| 191 </p> |
| 192 <p> |
| 193 If you invoke the API in silent mode, |
| 194 the API will only return a token if the provider is able |
| 195 to provide a token without showing any UI. |
| 196 This is useful in cases when an app is doing the flow at app startup, for exampl
e, |
| 197 or in general in cases where there is no user gesture involved. |
| 198 </p> |
| 199 <p> |
| 200 The best practice we suggest is to use silent mode |
| 201 when there is no user gesture involved and use interactive mode |
| 202 if there is a user gesture (for example, the user clicked the Sign In button in
your app). |
| 203 Note that we do not enforce gesture requirement. |
| 204 </p> |
| 205 <p class="backtotop"><a href="#top">Back to top</a></p> |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 10832042:
Extensions Docs Server: Doc conversion script (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src