chrome.identity Plugin
This plugin provides OAuth2 authentication for Android and iOS.
On Android, this plugin uses Google Play Services; on iOS, it uses Google+.
Status
Stable on Android and iOS.
Reference
The API reference is here; a description of how to use the API is here.
Mobile Reference
Added Functions
chrome.identity.revokeAuthToken(object details, function callback)
Revokes the permissions associated with an OAuth2 access token and removes it from the cache.
- object
details
: Token information.- string
token
: The token to revoke.
- string
- function
callback
: Called when the token has been revoked.callback
has no parameters.
Amended Functions
chrome.identity.getAccounts(function callback)
This function is only supported on Android.
- function
callback
has one parameter:- string
id
: In this implementation, this is the e-mail address associated with the account.
- string
chrome.identity.getAuthToken(object details, function callback)
- object
details
recognizes an additional option:- string
accountHint
: The account to authenticate in the event that the account chooser dialog is to appear.- Specifying this prevents the account chooser dialog from appearing.
- This only has an effect on Android.
- string
- function
callback
has two parameters:- string
token
: The authentication token. - string
account
: The account associated with the token.
- string
chrome.identity.getProfileUserInfo(function callback)
- function
callback
has one parameter:- string
email
: The e-mail address associated with the account.
- string
Preparing Your Application
Android
You will need to register your application in the Google Cloud Console. Create a project.
On the left sidebar, navigate to "APIs & auth" > "Credentials". Click the red Create new Client ID
button.
Register your app as an "Android" app (under "Installed application" type). This requires a package name and a SHA1 fingerprint. To obtain the fingerprint, enter the following the command in a console window:
keytool -list -v -keystore ~/.android/debug.keystore
# Or for .p12 files:
keytool -list -v -keystore KEYSTORE.p12 -storetype PKCS12
If the commands are not found, try running via cca exec keytool ...
(On Windows, replace ~
with %USERPROFILE%
.)
You will be prompted for a password, which is android
.
This process will yield a client id, but no action is required with it (unlike for iOS).
Identity Without Google Play Services
If Google Play Services is unavailable (for instance, on some emulators), you can enable a web-based fallback authentication flow. To do this:
In the project created in the Google Cloud Console, create a new client ID. The "Web application" type should be selected by default. Empty the "Authorized JavaScript origins" text box, and in the "Authorized redirect URI" text box, remove the default and enter https://YOUR_CHROME_APP_ID.chromiumapp.org/
.
Put the yielded client ID in your manifest.mobile.json
under "web": { "oauth2": { "client_id": "..."}}
, as described in the "Updating Your Manifest" section.
Note that this requires pasting your Chrome app's key
value into manifest.json
, as described here.
iOS
For iOS, first follow Step 1 of the instructions here.
Note: If you change your app's bundle identifier at any time, you will need to correspondingly update the bundle identifier in the following places:
- the Google Cloud Console, under "APIs & Auth" > "Registered Apps", and
- your app's URL types in Xcode (located in the app's Info tab).
Next, follow Step 4 on the same page (here) to register a URL type. If the URL type is already registered, you have no more to do for this step.
Updating Your Manifest
Your manifest needs to be updated to include your client id and scopes. In a Chrome App, this is done in manifest.json as follows:
"oauth2": {
"client_id": "YOUR_CHROME_CLIENT_ID",
"scopes": [
"SCOPE_1",
"SCOPE_2",
"SCOPE_3"
]
},
Additionally, for each other platform (including web, if you'd like to support Android authentication without Google Play Services), add a section to manifest.mobile.json containing the appropriate client ID. For example:
"android": {
"oauth2": {
"client_id": "YOUR_ANDROID_CLIENT_ID"
}
},
"ios": {
"oauth2": {
"client_id": "YOUR_IOS_CLIENT_ID"
}
},
"web": {
"oauth2": {
"client_id": "YOUR_WEB_CLIENT_ID"
}
}
This will clobber the client ID in manifest.json according to the platform.
Note: You do not need to specify your client ID for Android, but may want to for completeness. :)
When using this plugin outside the context of a Chrome App, this information must be provided using chrome.runtime.setManifest
:
chrome.runtime.setManifest({
oauth2: {
client_id: 'YOUR_IOS_CLIENT_ID',
scopes: [ 'SCOPE_1', 'SCOPE_2', 'SCOPE_3' ]
}
});
You can also pass scopes at call-time via the options
object:
chrome.identity.getAuthToken({scopes:['A', 'B']}, callback);
Playing With Google APIs
The Google APIs Explorer is a useful tool for determining required scopes and testing various API use cases.
Release Notes
1.4.6 (July 13, 2016)
- Fix play services dependency to work with latest verion of play services.
1.4.5 (June 15, 2015)
- Fix
removeCachedAuthToken
throwing exception whensignOut
parameter not specified
1.4.4 (May 29, 2015)
- Fix logout so you can switch accounts without restarting the app.
1.4.3 (May 19, 2015)
- Fix regression in 1.4.2 where launchWebAuthFlow was broken
1.4.2 (April 30, 2015)
- Renamed plugin to pubilsh to NPM
1.4.1 (Mar 17, 2015)
- MCA #519 Use explicit require of InAppBrowser
1.4.0 (Jan 27, 2015)
- Allow passing scopes via details object (fixes #491)
- ios: Call failure callback when auth fails (fixes #498)
- Add
GET_ACCOUNTS
permission (fixes #495)
1.3.1 (November 17, 2014)
- Added an unsupported result for iOS getAccounts
- Added getAccounts on Android
1.3.0 (October 21, 2014)
- Added
chrome.identity.getProfileUserInfo
API. - Documentation updates.
1.2.3 (September 24, 2014)
- Replaced a deprecated method call.
- Added cached token refreshing.
1.2.2 (August 20, 2014)
- Fixed swizzling linker error
- Added a prompt to update Google Play Services
1.2.1 (May 8, 2014)
- Documentation updates.
- Fixed Android web authentication.
- Added account to iOS authentication (was already previously added for Android).
1.2.0 (April 1, 2014)
- Documentation updates.
- Added
accountHint
tochrome.identity.getAuthToken
. - Added the logged-in account to the callback of
chrome.identity.getAuthToken
.
1.1.0 (March 10, 2014)
- Documentation updates.
- Android: Use of the web auth flow when Play Services is unavailable
- Added
chrome.identity.getRedirectURL()
- Fixes to launchWebAuthFlow()