|
|
|
|
@@ -1,4 +1,4 @@
|
|
|
|
|
page.title=Authentication
|
|
|
|
|
page.title=Authorization
|
|
|
|
|
@jd:body
|
|
|
|
|
|
|
|
|
|
<div id="qv-wrapper">
|
|
|
|
|
@@ -6,28 +6,28 @@ page.title=Authentication
|
|
|
|
|
<h2>In this document</h2>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#choose">Choosing an Account</a></li>
|
|
|
|
|
<li><a href="#obtain">Obtaining an Authorization Token</a></li>
|
|
|
|
|
<li><a href="#obtain">Obtaining an Access Token</a></li>
|
|
|
|
|
<li><a href="#handle">Handling Exceptions</a></li>
|
|
|
|
|
<li><a href="#use">Using the Token</a></li>
|
|
|
|
|
<li><a href="#use">Using the Access Token</a></li>
|
|
|
|
|
</ol>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Google Play services offers a standard authentication flow for all Google APIs and
|
|
|
|
|
all components of Google Play services. In addition, you can leverage the authentication
|
|
|
|
|
portion of the Google Play services SDK to authenticate to services that are not yet supported
|
|
|
|
|
in the Google Play services platform by using the authentication token to manually make API
|
|
|
|
|
Google Play services offers a standard authorization flow for all Google APIs and
|
|
|
|
|
all components of Google Play services. In addition, you can leverage the authorization
|
|
|
|
|
portion of the Google Play services SDK to gain authorization to services that are not yet supported
|
|
|
|
|
in the Google Play services platform by using the access token to manually make API
|
|
|
|
|
requests or using a client library provided by the service provider.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>For implementation details, see the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code>, which shows you how
|
|
|
|
|
to carry out these basic steps for obtaining an authentication token.</p>
|
|
|
|
|
<p>For implementation details, see the sample in <code><android-sdk>/extras/google-play-services/samples/auth</code>,
|
|
|
|
|
which shows you how to carry out these basic steps for obtaining an acesss token.</p>
|
|
|
|
|
|
|
|
|
|
<h2 id="choose">Choosing an Account</h2>
|
|
|
|
|
<p>
|
|
|
|
|
Google Play services leverage existing accounts on an Android-powered device
|
|
|
|
|
to authenticate to the services that you want to use. To obtain an authorization token,
|
|
|
|
|
to gain authorization to the services that you want to use. To obtain an access token,
|
|
|
|
|
a valid Google account is required and it must exist on the device. You can ask your users which
|
|
|
|
|
account they want to use by enumerating the Google accounts on the device or using the
|
|
|
|
|
built-in
|
|
|
|
|
@@ -39,7 +39,7 @@ AccountPicker}</a>
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For example, here's how to gather all of the Google accounts on a device and return them
|
|
|
|
|
in an array. When obtaining an authorization token, only the email address of the account is
|
|
|
|
|
in an array. When obtaining an access token, only the email address of the account is
|
|
|
|
|
needed, so that is what the array stores:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
@@ -55,24 +55,24 @@ private String[] getAccountNames() {
|
|
|
|
|
return names;
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
<h2 id="obtain">Obtaining an Authorization Token</h2>
|
|
|
|
|
<h2 id="obtain">Obtaining an Access Token</h2>
|
|
|
|
|
<p>
|
|
|
|
|
With an email address, you can now obtain an authorization token. There are two general
|
|
|
|
|
With an email address, you can now obtain an access token. There are two general
|
|
|
|
|
ways to get a token:</p>
|
|
|
|
|
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Call one of the two overloaded <a
|
|
|
|
|
href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
|
|
|
|
|
>{@code GoogleAuthUtil.getToken()}</a> methods in a foreground activity where you can
|
|
|
|
|
display a dialog to the user to interactively handle authentication errors.</li>
|
|
|
|
|
display a dialog to the user to interactively handle authorization errors.</li>
|
|
|
|
|
<li>Call one of the three <a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
|
|
|
|
|
>{@code getTokenWithNotification()}</a>
|
|
|
|
|
methods if you are authenticating in a background service or sync adapter so that a notification is displayed if an authentication
|
|
|
|
|
error occurs.</a></li>
|
|
|
|
|
methods if you are trying to gain authorization in a background service or sync adapter so that a
|
|
|
|
|
notification is displayed if an error occurs.</a></li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<h3>Using getToken()</h3>
|
|
|
|
|
The following code snippet obtains an authentication token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}:
|
|
|
|
|
The following code snippet obtains an access token with an email address, the scope that you want to use for the service, and a {@link android.content.Context}:
|
|
|
|
|
<pre>
|
|
|
|
|
HelloActivity mActivity;
|
|
|
|
|
String mEmail;
|
|
|
|
|
@@ -90,13 +90,13 @@ try {
|
|
|
|
|
<p>Call this method off of the main UI thread since it executes network transactions. An easy way to do this
|
|
|
|
|
is in an {@link android.os.AsyncTask}.
|
|
|
|
|
The sample in the Google Play services SDK shows you how to wrap this call in an AsyncTask.
|
|
|
|
|
If authentication is successful, the token is returned. If not, the exceptions described in
|
|
|
|
|
If authorization is successful, the token is returned. If not, the exceptions described in
|
|
|
|
|
<a href="#handle">Handling Exceptions</a>
|
|
|
|
|
are thrown that you can catch and handle appropriately.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3>Using getTokenWithNotification()</h3>
|
|
|
|
|
<p>If you are obtaining authentication tokens in a background service or sync adapter, there
|
|
|
|
|
<p>If you are obtaining access tokens in a background service or sync adapter, there
|
|
|
|
|
are three overloaded
|
|
|
|
|
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
|
|
|
|
|
>{@code getTokenWithNotification()}</a> methods
|
|
|
|
|
@@ -104,11 +104,11 @@ try {
|
|
|
|
|
<ul>
|
|
|
|
|
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle)"
|
|
|
|
|
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras)}</a>:
|
|
|
|
|
For background services. Displays a notification to the user when authentication errors occur.</li>
|
|
|
|
|
For background services. Displays a notification to the user when authorization errors occur.</li>
|
|
|
|
|
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, android.content.Intent)"
|
|
|
|
|
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, Intent callback)}</a>:
|
|
|
|
|
This method is for use in background services. It displays a notification to the user
|
|
|
|
|
when authentication errors occur. If a user clicks the notification and then authorizes the
|
|
|
|
|
when authorization errors occur. If a user clicks the notification and then authorizes the
|
|
|
|
|
app to access the account, the intent is broadcasted. When using this method:
|
|
|
|
|
<ul>
|
|
|
|
|
<li>Create a {@link android.content.BroadcastReceiver} that registers the intent and handles
|
|
|
|
|
@@ -123,7 +123,7 @@ android.content.Intent#toUri toUri(Intent.URI_INTENT_SCHEME)} and
|
|
|
|
|
<li><a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getTokenWithNotification(android.content.Context, java.lang.String, java.lang.String, android.os.Bundle, java.lang.String, android.os.Bundle)"
|
|
|
|
|
>{@code getTokenWithNotification(Context context, String accountName, String scope, Bundle extras, String authority, Bundle syncBundle)}</a>:
|
|
|
|
|
This method is for use in sync adapters. It displays a notification to the user when
|
|
|
|
|
authentication errors occur. If a user clicks the notification and then authorizes the
|
|
|
|
|
errors occur. If a user clicks the notification and then authorizes the
|
|
|
|
|
app to access the account, the sync adapter retries syncing with the information
|
|
|
|
|
contained in the <code>syncBundle</code> parameter.</li>
|
|
|
|
|
</ul>
|
|
|
|
|
@@ -135,7 +135,7 @@ app to access the account, the sync adapter retries syncing with the information
|
|
|
|
|
|
|
|
|
|
<h2 id="handle">Handling Exceptions</h2>
|
|
|
|
|
<p>
|
|
|
|
|
When requesting an authentication token with
|
|
|
|
|
When requesting an access token with
|
|
|
|
|
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
|
|
|
|
|
>{@code GoogleAuthUtil.getToken()}</a>,
|
|
|
|
|
the following exceptions can be thrown:
|
|
|
|
|
@@ -167,7 +167,7 @@ app to access the account, the sync adapter retries syncing with the information
|
|
|
|
|
<a href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthException.html">{@code
|
|
|
|
|
GoogleAuthException}</a>:
|
|
|
|
|
This exception is thrown when the authorization fails, such as when an invalid scope is
|
|
|
|
|
specified or if the email address used to authenticate is actually not on the user's
|
|
|
|
|
specified or if the email address used for authorization is actually not on the user's
|
|
|
|
|
device.
|
|
|
|
|
</li>
|
|
|
|
|
<li>
|
|
|
|
|
@@ -189,7 +189,7 @@ GoogleAuthUtil}</a> class.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<h2 id="use">Using the Token</h2>
|
|
|
|
|
<h2 id="use">Using the Access Token</h2>
|
|
|
|
|
<p>
|
|
|
|
|
Once you have successfully obtained a token, you can use it to access Google services.
|
|
|
|
|
Many Google services provide client libraries, so it is recommended that you use these when
|
|
|
|
|
@@ -224,7 +224,7 @@ if (serverCode == 200) {
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Notice that you must manually invalidate the token if the response from the server
|
|
|
|
|
signifies an authentication error (401). This could mean the authentication token
|
|
|
|
|
signifies an authorization error (401). This could mean the access token
|
|
|
|
|
being used is invalid for the service's scope or the token may have expired. If this is the
|
|
|
|
|
case, obtain a new token using <a
|
|
|
|
|
href="{@docRoot}reference/com/google/android/gms/auth/GoogleAuthUtil.html#getToken(android.content.Context, java.lang.String, java.lang.String)"
|
|
|
|
|
|
Robert Ly